Add changefeed triggers for summarization and memory processing (#4)

Author: jcodella

.env.template

@@ -1,9 +1,22 @@
 # This is a template for the .env file. Copy this file to .env and fill in the values for your accounts.
+
+# ---- Cosmos DB ----
 COSMOS_DB_ENDPOINT=https://<your-account>.documents.azure.com:443/
+# COSMOS_DB__accountEndpoint is required for the Azure Functions change feed trigger
+# (identity-based connection). Set it to the same value as COSMOS_DB_ENDPOINT.
+COSMOS_DB__accountEndpoint=https://<your-account>.documents.azure.com:443/
 COSMOS_DB_DATABASE=ai_memory
 COSMOS_DB_CONTAINER=memories
+COSMOS_DB_COUNTERS_CONTAINER=counter
+COSMOS_DB_LEASE_CONTAINER=leases
 COSMOS_DB_AUTOSCALE_MAX_RU=1000
 
+# ---- Change Feed Thresholds (set to 0 to disable) ----
+THREAD_SUMMARY_EVERY_N=0
+FACT_EXTRACTION_EVERY_N=0
+USER_SUMMARY_EVERY_N=0
+
+# ---- AI Foundry / Azure OpenAI ----
 AI_FOUNDRY_ENDPOINT=https://<your-account>.openai.azure.com/
 AI_FOUNDRY_API_KEY=
 EMBEDDING_MODEL=text-embedding-3-large
@@ -14,5 +27,6 @@ FULL_TEXT_LANGUAGE=en-US
 
 LLM_MODEL=<your-model-deployment>
 
+# ---- Azure Durable Functions ----
 ADF_ENDPOINT=http://localhost:7071/api
 ADF_KEY=

.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
-        run: pip install ruff
+        run: pip install 'ruff>=0.15,<0.16'
       - name: Ruff check
         run: ruff check agent_memory_toolkit/ tests/
       - name: Ruff format check

.gitignore

@@ -1,13 +1,18 @@
 # Environment
 .env
 local.settings.json
+.github/prompts/
+.github/skills/
 
 # agents
 .agents/
 .agent/
 .claude/
 skills/
 skills-lock.json
+openspec/
+openspec*
+
 
 
 # Python
@@ -19,6 +24,7 @@ build/
 *.egg
 .venv/
 venv/
+.pytest_cache/
 
 # Jupyter Notebook
 .ipynb_checkpoints/

Docs/README.md

@@ -6,10 +6,10 @@ This folder contains the main project documentation for Agent Memory Toolkit.
 
 | Document | Purpose |
 |----------|---------|
-| [concepts.md](concepts.md) | Explains the core memory model, including memory types (turn, summary, fact, user summary), threads, roles, and the processing pipeline. |
-| [local_testing.md](local_testing.md) | Covers local setup, environment configuration, RBAC, Cosmos provisioning, and running the toolkit and Azure Functions locally. |
-| [azure_testing.md](azure_testing.md) | Covers Azure deployment, cloud configuration, required services, and validation steps for running the toolkit in Azure. |
-| [design_patterns.md](design_patterns.md) | Shows when and how to call CRUD operations, summarization, fact extraction, and memory retrieval in chat and multi-agent applications. |
+| [concepts.md](concepts.md) | Explains the core memory model, including memory types (turn, summary, fact, user summary), threads, roles, the processing pipeline, and automatic change feed processing. |
+| [local_testing.md](local_testing.md) | Covers local setup, environment configuration, RBAC, Cosmos provisioning, running the toolkit and Azure Functions locally, and testing change feed auto-processing. |
+| [azure_testing.md](azure_testing.md) | Covers Azure deployment, cloud configuration, required services, change feed settings, and validation steps for running the toolkit in Azure. |
+| [design_patterns.md](design_patterns.md) | Shows when and how to call CRUD operations, summarization, fact extraction, and memory retrieval in chat and multi-agent applications, including automatic processing via the change feed. |
 
 ## Recommended Reading Order
 

Docs/azure_testing.md

@@ -111,6 +111,26 @@ az functionapp config appsettings set \
     LLM_MODEL="gpt-5-mini"
 ```
 
+### Change feed settings (optional)
+
+To enable automatic processing via the change feed trigger, add these settings:
+
+```bash
+az functionapp config appsettings set \
+  --name <function-app-name> \
+  --resource-group <resource-group> \
+  --settings \
+    COSMOS_DB__accountEndpoint="https://<cosmos-account-name>.documents.azure.com:443/" \
+    COSMOS_DB_COUNTERS_CONTAINER="counter" \
+    THREAD_SUMMARY_EVERY_N="5" \
+    FACT_EXTRACTION_EVERY_N="3" \
+    USER_SUMMARY_EVERY_N="10"
+```
+
+Set any threshold to `"0"` to disable that processing type.
+
+The `leases` container is created automatically by the Azure Functions runtime.
+
 If you use function-key auth for the HTTP trigger, keep the key for the client as `ADF_KEY`.
 
 ---
@@ -234,6 +254,7 @@ Bring the environment up in this order:
 9. test `generate_thread_summary()`
 10. test `extract_facts()` — verify single-line fact output
 11. test `generate_user_summary()` / `get_user_summary()`
+12. (if change feed is enabled) test automatic processing — write turns and verify derived memories appear
 
 This keeps failures isolated and easier to diagnose.
 
@@ -264,6 +285,32 @@ print(memory.generate_user_summary(user_id="user-1"))
 
 Thread summaries and user summaries update incrementally: repeated calls merge only new memories into the existing derived document.
 
+### Change feed auto-processing
+
+If you configured the change feed settings, verify automatic processing:
+
+```python
+import uuid
+
+# Use a threshold of 3 (THREAD_SUMMARY_EVERY_N=3) for testing
+thread_id = str(uuid.uuid4())
+for i in range(3):
+    memory.add_cosmos(
+        user_id="user-1",
+        thread_id=thread_id,
+        role="user",
+        content=f"Turn {i+1} for change feed validation",
+    )
+
+# Wait a few seconds for the change feed to trigger, then check:
+import time
+time.sleep(10)
+results = memory.get_memories(user_id="user-1", thread_id=thread_id, memory_type="summary")
+print(results)  # Should contain an auto-generated summary
+```
+
+Check the Function App logs to confirm the `on_memory_change` trigger fired and the orchestrator completed.
+
 ### Verify stored results
 
 ```python
@@ -293,6 +340,8 @@ Common issues:
 | Durable Function starts but fails | Missing app settings or downstream RBAC |
 | `No memories found` | No turn memories exist, or all candidate turns predate the existing summary |
 | Search is slow | Embedding latency, index choice, or region mismatch |
+| Change feed trigger not firing | Verify `COSMOS_DB__accountEndpoint` is set and the function can write to the configured `COSMOS_DB_COUNTERS_CONTAINER` container |
+| Auto-processing not starting | Check threshold settings are > 0 in Function App configuration |
 
 Recommended checks:
 

Docs/concepts.md

@@ -114,6 +114,59 @@ Prompts for summarization and fact extraction live in `azure_functions/prompts/`
 
 ---
 
+## Automatic Processing (Change Feed)
+
+In addition to on-demand processing via the SDK, the toolkit includes a Cosmos DB change feed trigger that **automatically** starts processing orchestrations when enough new turns have been written.
+
+```
+memories container
+      │  (change feed)
+      ▼
+on_memory_change trigger
+      │
+      ├── count turns per (user_id, thread_id)
+      │   └── crosses threshold? ──► start thread_summary / extract_facts
+      │
+      └── count turns per user_id
+          └── crosses threshold? ──► start user_summary
+```
+
+### How it works
+
+1. The change feed trigger watches the `memories` container for new documents.
+2. Only documents with `type == "turn"` are counted (summaries, facts, and user summaries are ignored).
+3. Documents in the dedicated `counter` container track how many turns have been seen per scope using ETag-based optimistic concurrency.
+4. When a counter crosses a configured threshold, the corresponding Durable Functions orchestration is started automatically.
+
+### Threshold settings
+
+| Setting | Scope | Default |
+|---------|-------|---------|
+| `THREAD_SUMMARY_EVERY_N` | Per `(user_id, thread_id)` | `0` (disabled) |
+| `FACT_EXTRACTION_EVERY_N` | Per `(user_id, thread_id)` | `0` (disabled) |
+| `USER_SUMMARY_EVERY_N` | Per `user_id` (across all threads) | `0` (disabled) |
+
+Set any value to `0` to disable that processing type. For example, setting `THREAD_SUMMARY_EVERY_N=5` generates a thread summary every 5 new turns in each thread.
+
+### Required containers
+
+| Container | Partition Key | Purpose |
+|-----------|---------------|---------|
+| `memories` | `/user_id`, `/thread_id` (hierarchical) | Existing memory store |
+| `counter` | `/user_id`, `/thread_id` (hierarchical) | Message count tracking for automatic processing |
+| `leases` | `/id` | Auto-created by the trigger for change feed checkpointing |
+
+### Push vs. pull
+
+| Mode | Trigger | Use case |
+|------|---------|----------|
+| **On-demand (pull)** | SDK call (`generate_thread_summary()`, etc.) | Explicit control over when processing happens |
+| **Automatic (push)** | Change feed trigger | Fire-and-forget — processing happens in the background as turns are written |
+
+Both modes use the same Durable Functions orchestrator and activities, so prompts, incremental update logic, and stored outputs are identical.
+
+---
+
 ## Local vs. Cloud Storage
 
 | Backend | Use Case | Persistence |

Docs/design_patterns.md

@@ -86,6 +86,7 @@ await mem.delete_cosmos(memory_id="<id>", user_id="user-1", thread_id=THREAD_ID)
 - **End of conversation** — after the user closes a session or a support ticket is resolved.
 - **Long-running thread** — when a thread exceeds a token budget (e.g. > 50 turns) and you need a compact representation for context.
 - **Periodic background job** — on a schedule to keep summaries up to date for active threads.
+- **Automatic (change feed)** — set `THREAD_SUMMARY_EVERY_N` and the change feed trigger handles it. See [Section 8](#8-automatic-processing-with-change-feed).
 
 Summaries are incremental: if one already exists for the thread, only newer turns are merged in.
 
@@ -111,6 +112,7 @@ The summary is stored automatically in Cosmos with id `summary_user-1_thread-abc
 - **After each meaningful exchange** — extract facts from the latest turns so they are available for retrieval immediately.
 - **End of conversation** — capture all discrete preferences, decisions, and requirements from the thread.
 - **Before a planning step** — in multi-agent workflows, extract facts before handing context to a planner agent.
+- **Automatic (change feed)** — set `FACT_EXTRACTION_EVERY_N` and the change feed trigger handles it. See [Section 8](#8-automatic-processing-with-change-feed).
 
 Each fact is stored as its own document with its own embedding, making it ideal for fine-grained semantic search.
 
@@ -133,6 +135,7 @@ result = await mem.extract_facts(
 - **Cross-session onboarding** — at the start of a new thread, generate (or update) the user summary so the agent has context from all prior conversations.
 - **After a thread summary is created** — chain it: summarize the thread, then update the user summary.
 - **On a schedule** — for users with many threads, run periodically to keep the profile current.
+- **Automatic (change feed)** — set `USER_SUMMARY_EVERY_N` and the change feed trigger handles it. See [Section 8](#8-automatic-processing-with-change-feed).
 
 User summaries are also incremental. The pipeline merges only new thread data into the existing profile.
 
@@ -311,6 +314,50 @@ await mem.generate_user_summary(
 
 ---
 
+## 8. Automatic Processing with Change Feed
+
+Instead of calling `generate_thread_summary()`, `extract_facts()`, or `generate_user_summary()` explicitly, you can let the Cosmos DB change feed trigger fire them automatically in the background.
+
+### How it works
+
+When a new turn is written to the `memories` container, the change feed trigger:
+
+1. Increments a counter document in the dedicated `counter` container for each relevant scope.
+2. Checks whether the counter has crossed a configured threshold.
+3. Starts the appropriate Durable Functions orchestration if the threshold is crossed.
+
+### Configuration
+
+Set these application settings (in `local.settings.json` locally or Function App settings in Azure):
+
+| Setting | Scope | Effect |
+|---------|-------|--------|
+| `THREAD_SUMMARY_EVERY_N=5` | Per `(user_id, thread_id)` | Summarize the thread every 5 turns |
+| `FACT_EXTRACTION_EVERY_N=3` | Per `(user_id, thread_id)` | Extract facts every 3 turns |
+| `USER_SUMMARY_EVERY_N=10` | Per `user_id` | Update user profile every 10 turns across all threads |
+
+Set any value to `0` to disable that processing type. All three default to `0` (disabled).
+
+### Required infrastructure
+
+The change feed trigger needs two additional Cosmos DB containers beyond the existing `memories` container:
+
+- **`counter`** — stores lightweight per-thread and per-user message counters used for threshold checks
+- **`leases`** — auto-created by the Azure Functions runtime for change feed checkpointing
+
+The `COSMOS_DB__accountEndpoint` setting must also be configured for the identity-based change feed binding.
+
+### When to use automatic vs. on-demand
+
+| Approach | Best for |
+|----------|----------|
+| **On-demand** | Full control, testing, one-off processing, chaining operations |
+| **Automatic** | Always-on background processing, fire-and-forget, production workloads |
+
+Both approaches use the same orchestrator and activities, so the output is identical.
+
+---
+
 ## Quick Reference
 
 | Operation | Method | When |
@@ -321,7 +368,7 @@ await mem.generate_user_summary(
 | Delete a memory | `delete_cosmos` | Remove incorrect or sensitive data |
 | Get a thread | `get_thread` | Load recent conversation context |
 | Semantic search | `search_cosmos` | Find relevant facts or summaries for a prompt |
-| Summarize a thread | `generate_thread_summary` | End of conversation or periodically |
-| Extract facts | `extract_facts` | After key exchanges or end of conversation |
-| Summarize a user | `generate_user_summary` | Cross-session profiling, after thread summaries |
+| Summarize a thread | `generate_thread_summary` | End of conversation, periodically, or automatic via change feed |
+| Extract facts | `extract_facts` | After key exchanges, end of conversation, or automatic via change feed |
+| Summarize a user | `generate_user_summary` | Cross-session profiling, after thread summaries, or automatic via change feed |
 | Get user summary | `get_user_summary` | Start of a new session |