Skip to content

Commit 1226c8d

Browse files
jcodellajcodella
authored
Readme on first commit
0 parents  commit 1226c8d

1 file changed

Lines changed: 182 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# Azure Cosmos DB Agent Memory Toolkit
2+
3+
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
4+
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
5+
[![Azure Cosmos DB](https://img.shields.io/badge/Azure-Cosmos%20DB-0078D4?logo=microsoft-azure)](https://azure.microsoft.com/en-us/products/cosmos-db/)
6+
[![Follow on X](https://img.shields.io/twitter/follow/AzureCosmosDB?style=social)](https://twitter.com/AzureCosmosDB)
7+
[![LinkedIn](https://img.shields.io/badge/LinkedIn-Azure%20Cosmos%20DB-0077B5?logo=linkedin)](https://www.linkedin.com/showcase/azure-cosmos-db/)
8+
[![YouTube](https://img.shields.io/badge/YouTube-Azure%20Cosmos%20DB-FF0000?logo=youtube&logoColor=white)](https://www.youtube.com/@AzureCosmosDB)
9+
10+
11+
Agent Memory Toolkit is a Python library and Azure-backed reference implementation for storing, retrieving, and transforming agent memories over time. It combines a simple SDK for local and Cosmos DB operations with Durable Functions pipelines that generate thread summaries, extract facts, and build cross-thread user profiles. The toolkit is designed for agent applications that need both raw conversation history and higher-value derived memory that can be searched semantically later. It provides matching sync (`AgentMemory`) and async (`AsyncAgentMemory`) APIs so the same memory model can be used in scripts, services, notebooks, and larger agent systems.
12+
13+
```
14+
┌────────────────────────────────────────────────────────────────────────────┐
15+
│ YOUR AGENTIC APP │
16+
│ Uses AgentMemory / AsyncAgentMemory │
17+
└────────────────────────────────┬───────────────────────────────────────────┘
18+
│
19+
▼
20+
┌────────────────────────────────────────────────────────────────────────────┐
21+
│ AGENT MEMORY TOOLKIT (Python SDK) │
22+
│ │
23+
│ • Local in-memory CRUD │
24+
│ • Cosmos DB storage and retrieval │
25+
│ • Calls into Azure Durable Functions for memory processing │
26+
└───────────────────────┬────────────────────────────────────────────┬───────┘
27+
│ │
28+
│ read / write │ Invoke processing pipeline
29+
▼ ▼
30+
┌───────────────────────────────────┐ ┌──────────────────────────────────┐
31+
│ AZURE COSMOS DB (NoSQL) │ │ AZURE DURABLE FUNCTIONS │
32+
│ │ │ │
33+
│ Stores: │ │ Orchestrates memory processing: │
34+
│ • turns │ │ • thread summaries │
35+
│ • summaries │◄─── memory management ───►│ • fact extraction │
36+
│ • facts │ │ • user summaries │
37+
│ • user summaries │ │ │
38+
│ │ │ Reads raw memories and │
39+
│ Supports query, vector, text │ │ writes processed memories back. │
40+
│ search over stored memories. │ └──────────────────┬───────────────┘
41+
└───────────────────────┬───────────┘ │
42+
│ embeddings and LLM-based processing │
43+
└──────────────────────┬───────────────────────────────────┘
44+
▼
45+
┌──────────────────────────────────┐
46+
│ MICROSOFT FOUNDRY │
47+
│ │
48+
│ • Embeddings for search │
49+
│ • Chat/LLM generation │
50+
│ │
51+
└──────────────────────────────────┘
52+
```
53+
54+
---
55+
56+
## Features
57+
58+
| Feature | Description |
59+
|---------|-------------|
60+
| **Local memory store** | In-memory CRUD — no Azure needed for development |
61+
| **Cosmos DB integration** | CRUD, `push_to_cosmos()` bulk upload, semantic search, hierarchical partition key, vector + full-text indexes |
62+
| **Thread summaries** | `generate_thread_summary()` — LLM-generated, incrementally updated, embedded and stored |
63+
| **Fact extraction** | `extract_facts()` — discrete, independently searchable assertions from a thread |
64+
| **User summaries** | `generate_user_summary()` — cross-thread user profile, incrementally updated |
65+
| **Incremental updates** | Thread and user summaries use point-read + time-filtering to merge new data with existing summaries |
66+
| **Externalized prompts** | LLM prompts live in editable Markdown files (`azure_functions/prompts/`) |
67+
| **Entra ID auth** | `DefaultAzureCredential` everywhere — `az login`, managed identities |
68+
69+
---
70+
71+
## Project Structure
72+
73+
```
74+
agent_memory_toolkit/ Python library — AgentMemory (sync) + AsyncAgentMemory (async)
75+
azure_functions/ Durable Functions — orchestrator, activities, HTTP trigger
76+
prompts/ LLM system prompts — summarize, facts, user_summary + update variants
77+
Samples/ Demo notebooks — sync (Demo.ipynb) + async (Demo_async.ipynb)
78+
Docs/ Documentation — concepts, local testing, Azure deployment
79+
```
80+
81+
---
82+
83+
## Quick Start
84+
85+
### 1. Install
86+
87+
```bash
88+
pip install -r requirements.txt
89+
```
90+
91+
### 2. Local-only (no Azure)
92+
93+
```python
94+
import uuid
95+
from agent_memory_toolkit import AgentMemory
96+
97+
memory = AgentMemory(use_default_credential=False)
98+
thread_id = str(uuid.uuid4())
99+
memory.add_local(user_id="user-001", role="user", thread_id=thread_id, content="Hello world")
100+
print(memory.get_local())
101+
```
102+
103+
### 3. With Cosmos DB + Azure OpenAI
104+
105+
```bash
106+
cp .env.template .env # fill in endpoint values
107+
```
108+
109+
```python
110+
import os, uuid
111+
from dotenv import load_dotenv
112+
from azure.identity import DefaultAzureCredential
113+
from agent_memory_toolkit import AgentMemory
114+
115+
load_dotenv()
116+
117+
memory = AgentMemory(
118+
cosmos_endpoint=os.getenv("COSMOS_DB_ENDPOINT"),
119+
cosmos_database=os.getenv("COSMOS_DB_DATABASE"),
120+
cosmos_container=os.getenv("COSMOS_DB_CONTAINER"),
121+
ai_foundry_endpoint=os.getenv("AI_FOUNDRY_ENDPOINT"),
122+
embedding_model=os.getenv("EMBEDDING_MODEL", "text-embedding-3-large"),
123+
adf_endpoint=os.getenv("ADF_ENDPOINT", "http://localhost:7071/api"),
124+
adf_key=os.getenv("ADF_KEY", ""),
125+
use_default_credential=True,
126+
cosmos_credential=DefaultAzureCredential(),
127+
)
128+
memory.create_memory_store()
129+
memory.connect_cosmos()
130+
131+
# Add directly to Cosmos
132+
thread_id = str(uuid.uuid4())
133+
memory.add_cosmos(user_id="user-001", role="user", thread_id=thread_id, content="Stored in Cosmos")
134+
print(memory.get_memories(user_id="user-001", thread_id=thread_id))
135+
136+
# Or add locally first, then bulk-upload
137+
memory.add_local(user_id="user-001", role="agent", thread_id=thread_id, content="Response text")
138+
memory.push_to_cosmos()
139+
```
140+
141+
### 4. Durable Function operations
142+
143+
These require the Azure Durable Functions host. See [local_testing.md](Docs/local_testing.md) for setup.
144+
145+
```python
146+
# Thread summary (incremental — merges with existing if present)
147+
result = memory.generate_thread_summary(user_id="user-001", thread_id=thread_id, recent_k=5)
148+
149+
# Fact extraction
150+
result = memory.extract_facts(user_id="user-001", thread_id=thread_id)
151+
152+
# User summary (incremental — cross-thread profile)
153+
result = memory.generate_user_summary(user_id="user-001")
154+
155+
# Retrieve stored user summary
156+
summary = memory.get_user_summary(user_id="user-001")
157+
```
158+
159+
> The async API (`AsyncAgentMemory`) is identical — just `await` each call.
160+
161+
---
162+
163+
## Azure Resources
164+
165+
| Resource | Purpose |
166+
|----------|---------|
167+
| **Cosmos DB for NoSQL** | Memory store with hierarchical partition key, vector index, full-text index |
168+
| **Azure OpenAI / AI Foundry** | Embedding model + chat model for summarization / fact extraction |
169+
| **Azure Functions** | Durable Functions orchestrator and activity functions |
170+
171+
All services use **Entra ID** auth via `DefaultAzureCredential`.
172+
173+
---
174+
175+
## Documentation
176+
177+
- **[concepts.md](Docs/concepts.md)** — Memory types, threads, roles, embeddings, processing pipeline
178+
- **[design_patterns.md](Docs/design_patterns.md)** — Integration patterns for chat apps and multi-agent systems
179+
- **[local_testing.md](Docs/local_testing.md)** — Prerequisites, environment setup, running locally, debugging
180+
- **[azure_testing.md](Docs/azure_testing.md)** — Azure deployment, RBAC, cloud validation
181+
182+
---

0 commit comments

Comments
 (0)