Updating cosmos db topology to use 3 containers

Author: Aayush Kataria

.env.template

@@ -10,8 +10,12 @@ COSMOS_DB__accountEndpoint=https://<your-account>.documents.azure.com:443/
 # letting you create databases/containers without RBAC role assignments.
 # Leave blank to use DefaultAzureCredential / managed identity.
 COSMOS_DB_KEY=
+# Database name. Must match what the Function App reads (COSMOS_DB_DATABASE there).
+# Default is "ai_memory"; change only if your infra deploys a different name.
 COSMOS_DB_DATABASE=ai_memory
-COSMOS_DB_CONTAINER=memories
+COSMOS_DB_MEMORIES_CONTAINER="memories"
+COSMOS_DB_SUMMARIES_CONTAINER="memories_summaries"
+COSMOS_DB_TURNS_CONTAINER="memories_turns"
 COSMOS_DB_COUNTERS_CONTAINER=counter
 COSMOS_DB_LEASE_CONTAINER=leases
 # Throughput mode for all required Cosmos DB containers created by the toolkit
@@ -29,6 +33,21 @@ THREAD_SUMMARY_EVERY_N=10
 FACT_EXTRACTION_EVERY_N=1
 USER_SUMMARY_EVERY_N=20
 
+# ---- Processor ownership (in-process SDK vs. Function App / Durable) ----
+# Controls which side runs the auto-trigger to avoid double-firing when both
+# the SDK and the Function App are deployed against the same database.
+#
+#   * Unset / blank        -> SDK auto-trigger fires; FA change-feed SKIPS.
+#                             (Pure SDK deployments — no env config needed.)
+#   * "inprocess"          -> SDK auto-trigger fires; FA change-feed SKIPS.
+#   * "durable"            -> SDK auto-trigger SKIPS; FA change-feed fires.
+#
+# The contract is asymmetric by design: the FA defaults to skip (default-deny)
+# so a fresh FA deploy next to an existing SDK install does not race. If you
+# run the Function App, you MUST set this to "durable" or processing will
+# silently no-op.
+MEMORY_PROCESSOR_OWNER=
+
 # ---- AI Foundry / Azure OpenAI ----
 AI_FOUNDRY_ENDPOINT=https://<your-account>.openai.azure.com/
 AI_FOUNDRY_API_KEY=
@@ -39,3 +58,6 @@ AI_FOUNDRY_EMBEDDING_DISTANCE_FUNCTION=cosine
 COSMOS_DB_FULL_TEXT_LANGUAGE=en-US
 
 AI_FOUNDRY_CHAT_DEPLOYMENT_NAME=<your-model-deployment>
+# Optional. Pin the Azure OpenAI REST API version used by chat and embeddings
+# clients. Leave blank to use the toolkit default ("2024-12-01-preview").
+AZURE_OPENAI_API_VERSION=

Docs/azure_testing.md

@@ -105,7 +105,7 @@ az functionapp config appsettings set \
   --settings \
     COSMOS_DB_ENDPOINT="https://<cosmos-account-name>.documents.azure.com:443/" \
     COSMOS_DB_DATABASE="ai_memory" \
-    COSMOS_DB_CONTAINER="memories" \
+    COSMOS_DB_MEMORIES_CONTAINER="memories" \
     COSMOS_DB_COUNTERS_CONTAINER="counter" \
     COSMOS_DB_LEASE_CONTAINER="leases" \
     COSMOS_DB_THROUGHPUT_MODE="serverless" \
@@ -178,7 +178,7 @@ Update `.env` to point at Azure instead of localhost:
 ```env
 COSMOS_DB_ENDPOINT=https://<cosmos-account-name>.documents.azure.com:443/
 COSMOS_DB_DATABASE=ai_memory
-COSMOS_DB_CONTAINER=memories
+COSMOS_DB_MEMORIES_CONTAINER=memories
 COSMOS_DB_COUNTERS_CONTAINER=counter
 COSMOS_DB_LEASE_CONTAINER=leases
 COSMOS_DB_THROUGHPUT_MODE=serverless
@@ -213,7 +213,7 @@ load_dotenv()
 memory = CosmosMemoryClient(
     cosmos_endpoint=os.getenv("COSMOS_DB_ENDPOINT"),
     cosmos_database=os.getenv("COSMOS_DB_DATABASE", "ai_memory"),
-    cosmos_container=os.getenv("COSMOS_DB_CONTAINER", "memories"),
+    cosmos_container=os.getenv("COSMOS_DB_MEMORIES_CONTAINER", "memories"),
     cosmos_counter_container=os.getenv("COSMOS_DB_COUNTERS_CONTAINER", "counter"),
     cosmos_lease_container=os.getenv("COSMOS_DB_LEASE_CONTAINER", "leases"),
     cosmos_throughput_mode=os.getenv("COSMOS_DB_THROUGHPUT_MODE", "serverless"),
@@ -242,7 +242,7 @@ load_dotenv()
 memory = AsyncCosmosMemoryClient(
     cosmos_endpoint=os.getenv("COSMOS_DB_ENDPOINT"),
     cosmos_database=os.getenv("COSMOS_DB_DATABASE", "ai_memory"),
-    cosmos_container=os.getenv("COSMOS_DB_CONTAINER", "memories"),
+    cosmos_container=os.getenv("COSMOS_DB_MEMORIES_CONTAINER", "memories"),
     cosmos_counter_container=os.getenv("COSMOS_DB_COUNTERS_CONTAINER", "counter"),
     cosmos_lease_container=os.getenv("COSMOS_DB_LEASE_CONTAINER", "leases"),
     cosmos_throughput_mode=os.getenv("COSMOS_DB_THROUGHPUT_MODE", "serverless"),

Docs/local_testing.md

@@ -71,7 +71,7 @@ Minimum `.env` values:
 ```env
 COSMOS_DB_ENDPOINT=https://<your-account>.documents.azure.com:443/
 COSMOS_DB_DATABASE=ai_memory
-COSMOS_DB_CONTAINER=memories
+COSMOS_DB_MEMORIES_CONTAINER=memories
 COSMOS_DB_COUNTERS_CONTAINER=counter
 COSMOS_DB_LEASE_CONTAINER=leases
 COSMOS_DB_THROUGHPUT_MODE=serverless
@@ -160,7 +160,7 @@ load_dotenv()
 memory = AgentMemory(
     cosmos_endpoint=os.getenv("COSMOS_DB_ENDPOINT"),
     cosmos_database=os.getenv("COSMOS_DB_DATABASE"),
-    cosmos_container=os.getenv("COSMOS_DB_CONTAINER"),
+    cosmos_container=os.getenv("COSMOS_DB_MEMORIES_CONTAINER"),
     cosmos_counter_container=os.getenv("COSMOS_DB_COUNTERS_CONTAINER", "counter"),
     cosmos_lease_container=os.getenv("COSMOS_DB_LEASE_CONTAINER", "leases"),
     cosmos_throughput_mode=os.getenv("COSMOS_DB_THROUGHPUT_MODE", "serverless"),
@@ -203,7 +203,7 @@ load_dotenv()
 memory = AsyncAgentMemory(
     cosmos_endpoint=os.getenv("COSMOS_DB_ENDPOINT"),
     cosmos_database=os.getenv("COSMOS_DB_DATABASE"),
-    cosmos_container=os.getenv("COSMOS_DB_CONTAINER"),
+    cosmos_container=os.getenv("COSMOS_DB_MEMORIES_CONTAINER"),
     cosmos_counter_container=os.getenv("COSMOS_DB_COUNTERS_CONTAINER", "counter"),
     cosmos_lease_container=os.getenv("COSMOS_DB_LEASE_CONTAINER", "leases"),
     cosmos_throughput_mode=os.getenv("COSMOS_DB_THROUGHPUT_MODE", "serverless"),
@@ -219,7 +219,7 @@ memory = AsyncAgentMemory(
 await memory.connect_cosmos(
     endpoint=os.getenv("COSMOS_DB_ENDPOINT"),
     database=os.getenv("COSMOS_DB_DATABASE"),
-    container=os.getenv("COSMOS_DB_CONTAINER"),
+    container=os.getenv("COSMOS_DB_MEMORIES_CONTAINER"),
     credential=AsyncDefaultAzureCredential(),
 )
 await memory.create_memory_store()

Docs/public_api.md

@@ -14,10 +14,11 @@
 
 ### Connection
 
-- `__init__(cosmos_endpoint=None, cosmos_credential=None, cosmos_key=None, cosmos_database=None, cosmos_container=None, cosmos_turns_container=None, cosmos_counter_container=None, cosmos_lease_container=None, cosmos_throughput_mode=None, cosmos_autoscale_max_ru=None, ai_foundry_endpoint=None, ai_foundry_credential=None, ai_foundry_api_key=None, embedding_deployment_name='text-embedding-3-large', embedding_dimensions=None, chat_deployment_name='gpt-4o-mini', use_default_credential=True, processor=None) -> None` — configure local state, model clients, optional Cosmos auto-connect, and optional processing backend. When `cosmos_turns_container` is set, turn-type documents land in a dedicated container so the main `memories` container only fires the Durable change-feed trigger for processed memory writes.
+- `__init__(cosmos_endpoint=None, cosmos_credential=None, cosmos_key=None, cosmos_database=None, cosmos_container=None, cosmos_turns_container='memories_turns', cosmos_summaries_container='memories_summaries', cosmos_counter_container=None, cosmos_lease_container=None, cosmos_throughput_mode=None, cosmos_autoscale_max_ru=None, ai_foundry_endpoint=None, ai_foundry_credential=None, ai_foundry_api_key=None, embedding_deployment_name='text-embedding-3-large', embedding_dimensions=None, chat_deployment_name='gpt-4o-mini', use_default_credential=True, processor=None) -> None` — configure local state, model clients, optional Cosmos auto-connect, and optional processing backend. The SDK uses a hard 3-container topology: turns in `memories_turns`, facts/episodic/procedural in `memories`, and summaries in `memories_summaries` (or the names you pass).
 - `close() -> None` — close Cosmos/model clients and owned credentials.
-- `connect_cosmos(endpoint=None, credential=None, key=None, database=None, container=None, turns_container=None) -> None` — connect to an existing memory container.
-- `create_memory_store(database=None, container=None, turns_container=None, counter_container=None, lease_container=None, endpoint=None, credential=None, key=None, embedding_dimensions=None, embedding_data_type=None, distance_function=None, full_text_language=None, throughput_mode=None, autoscale_max_ru=None) -> None` — create/connect the memory, optional turns, counter, and lease containers.
+- `connect_cosmos(endpoint=None, credential=None, key=None, database=None, container=None, turns_container=None, summaries_container=None) -> None` — connect to existing memory, turns, and summaries containers.
+- `create_memory_store(database=None, container=None, turns_container=None, summaries_container=None, counter_container=None, lease_container=None, endpoint=None, credential=None, key=None, embedding_dimensions=None, embedding_data_type=None, distance_function=None, full_text_language=None, throughput_mode=None, autoscale_max_ru=None) -> None` — create/connect the memory, turns, summaries, counter, and lease containers.
+- `validate_topology() -> None` — read metadata for all three memory containers and raise `RuntimeError` if any is missing or unreachable; call after connecting to catch infrastructure/config drift before writes.
 
 ### Memory CRUD
 
@@ -65,10 +66,11 @@ Local-buffer methods remain synchronous in-memory operations; Cosmos, retrieval,
 
 ### Connection
 
-- `__init__(cosmos_endpoint=None, cosmos_credential=None, cosmos_key=None, cosmos_database=None, cosmos_container=None, cosmos_turns_container=None, cosmos_counter_container=None, cosmos_lease_container=None, cosmos_throughput_mode=None, cosmos_autoscale_max_ru=None, ai_foundry_endpoint=None, ai_foundry_credential=None, ai_foundry_api_key=None, embedding_deployment_name='text-embedding-3-large', embedding_dimensions=None, chat_deployment_name='gpt-4o-mini', use_default_credential=True, processor=None) -> None` — configure async local state, model clients, and optional processing backend. When `cosmos_turns_container` is set, turn-type documents land in a dedicated container so the main `memories` container only fires the Durable change-feed trigger for processed memory writes.
+- `__init__(cosmos_endpoint=None, cosmos_credential=None, cosmos_key=None, cosmos_database=None, cosmos_container=None, cosmos_turns_container='memories_turns', cosmos_summaries_container='memories_summaries', cosmos_counter_container=None, cosmos_lease_container=None, cosmos_throughput_mode=None, cosmos_autoscale_max_ru=None, ai_foundry_endpoint=None, ai_foundry_credential=None, ai_foundry_api_key=None, embedding_deployment_name='text-embedding-3-large', embedding_dimensions=None, chat_deployment_name='gpt-4o-mini', use_default_credential=True, processor=None) -> None` — configure async local state, model clients, and optional processing backend. The async SDK uses the same hard 3-container topology as the sync client.
 - `async close() -> None` — close async/sync resources and owned credentials.
-- `async connect_cosmos(endpoint=None, credential=None, key=None, database=None, container=None, turns_container=None) -> None` — connect to an existing memory container.
-- `async create_memory_store(database=None, container=None, turns_container=None, counter_container=None, lease_container=None, endpoint=None, credential=None, key=None, embedding_dimensions=None, embedding_data_type=None, distance_function=None, full_text_language=None, throughput_mode=None, autoscale_max_ru=None) -> None` — create/connect memory, optional turns, counter, and lease containers.
+- `async connect_cosmos(endpoint=None, credential=None, key=None, database=None, container=None, turns_container=None, summaries_container=None) -> None` — connect to existing memory, turns, and summaries containers.
+- `async create_memory_store(database=None, container=None, turns_container=None, summaries_container=None, counter_container=None, lease_container=None, endpoint=None, credential=None, key=None, embedding_dimensions=None, embedding_data_type=None, distance_function=None, full_text_language=None, throughput_mode=None, autoscale_max_ru=None) -> None` — create/connect memory, turns, summaries, counter, and lease containers.
+- `async validate_topology() -> None` — read metadata for all three memory containers and raise `RuntimeError` if any is missing or unreachable; call after connecting to catch infrastructure/config drift before writes.
 
 ### Memory CRUD
 
@@ -110,6 +112,10 @@ Local-buffer methods remain synchronous in-memory operations; Cosmos, retrieval,
 - `async remove_tags(memory_id, user_id, thread_id, tags) -> None` — remove tags from a memory.
 - `async list_tags(user_id, *, thread_id=None, prefix=None, include_sys=False) -> list[str]` — list sorted, deduped tags for a user; omits `sys:*` by default.
 
+## Topology validation
+
+Use `validate_topology()` (sync) or `await validate_topology()` (async) after `connect_cosmos()` or `create_memory_store()` to verify that `memories`, `memories_turns`, and `memories_summaries` all exist and are readable. The method raises `RuntimeError` with redeploy guidance on the first missing or unreachable container.
+
 ## Extension Points
 
 Sync extension protocols live in `agent_memory_toolkit.services`; async variants live in `agent_memory_toolkit.aio.services`.

Docs/troubleshooting.md

@@ -47,7 +47,7 @@ COSMOS_DB_ENDPOINT=https://<account>.documents.azure.com:443/
 COSMOS_DB__accountEndpoint=https://<account>.documents.azure.com:443/
 COSMOS_DB_KEY=
 COSMOS_DB_DATABASE=ai_memory
-COSMOS_DB_CONTAINER=memories
+COSMOS_DB_MEMORIES_CONTAINER=memories
 COSMOS_DB_COUNTERS_CONTAINER=counter
 COSMOS_DB_LEASE_CONTAINER=leases
 COSMOS_DB_THROUGHPUT_MODE=serverless
@@ -68,7 +68,7 @@ The notebooks and samples pass these values into the client like this:
 |---|---|
 | `COSMOS_DB_ENDPOINT` | `cosmos_endpoint` |
 | `COSMOS_DB_DATABASE` | `cosmos_database` |
-| `COSMOS_DB_CONTAINER` | `cosmos_container` |
+| `COSMOS_DB_MEMORIES_CONTAINER` | `cosmos_container` |
 | `COSMOS_DB_COUNTERS_CONTAINER` | `cosmos_counter_container` |
 | `COSMOS_DB_LEASE_CONTAINER` | `cosmos_lease_container` |
 | `COSMOS_DB_KEY` | `cosmos_key` |
@@ -149,7 +149,7 @@ Automatic processing requires these settings in the Functions app or `local.sett
 "COSMOS_DB__accountEndpoint": "https://<account>.documents.azure.com:443/",
 "COSMOS_DB_ENDPOINT": "https://<account>.documents.azure.com:443/",
 "COSMOS_DB_DATABASE": "ai_memory",
-"COSMOS_DB_CONTAINER": "memories",
+"COSMOS_DB_MEMORIES_CONTAINER": "memories",
 "COSMOS_DB_COUNTERS_CONTAINER": "counter",
 "COSMOS_DB_LEASE_CONTAINER": "leases",
 "AI_FOUNDRY_ENDPOINT": "https://<account>.openai.azure.com/",

README.md

@@ -82,7 +82,7 @@ load_dotenv()
 memory = CosmosMemoryClient(
     cosmos_endpoint=os.environ["COSMOS_DB_ENDPOINT"],
     cosmos_database=os.getenv("COSMOS_DB_DATABASE", "ai_memory"),
-    cosmos_container=os.getenv("COSMOS_DB_CONTAINER", "memories"),
+    cosmos_container=os.getenv("COSMOS_DB_MEMORIES_CONTAINER", "memories"),
     ai_foundry_endpoint=os.environ["AI_FOUNDRY_ENDPOINT"],
     embedding_deployment_name=os.getenv("AI_FOUNDRY_EMBEDDING_DEPLOYMENT_NAME", "text-embedding-3-large"),
     chat_deployment_name=os.getenv("AI_FOUNDRY_CHAT_DEPLOYMENT_NAME", "gpt-4o-mini"),
@@ -137,7 +137,13 @@ See [`Samples/`](Samples/) for end-to-end scenarios (chat memory, RAG, multi-age
 | **Search** | Vector + full-text + filter; returns any of the above | `search_cosmos(...)` |
 | **Process now** | Run the full pipeline (summary → facts → user profile) for recent turns | `process_now(...)`, `process_now_and_wait(...)` |
 
-All memory kinds live in the same Cosmos container, partitioned by `(user_id, thread_id)`, distinguished by a `type` discriminator.
+AgentMemoryToolkit uses 3-container Cosmos topology, all partitioned by hierarchical `(user_id, thread_id)` keys:
+
+| Container | Holds | Notes |
+|---|---|---|
+| `memories_turns` | raw `turn` documents | append-only conversation timeline |
+| `memories` | `fact`, `episodic`, `procedural` documents | vector + full-text retrieval path |
+| `memories_summaries` | thread and user summaries | latest-summary point/read path |
 
 ### Memory Type Taxonomy
 

Samples/Advanced/advanced_memory_lifecycle.py

@@ -54,7 +54,7 @@ def main() -> None:
         cosmos_endpoint=os.environ["COSMOS_DB_ENDPOINT"],
         cosmos_key=os.environ.get("COSMOS_DB_KEY") or None,
         cosmos_database=os.environ.get("COSMOS_DB_DATABASE", "ai_memory"),
-        cosmos_container=os.environ.get("COSMOS_DB_CONTAINER", "memories"),
+        cosmos_container=os.environ.get("COSMOS_DB_MEMORIES_CONTAINER", "memories"),
         ai_foundry_endpoint=os.environ["AI_FOUNDRY_ENDPOINT"],
         ai_foundry_api_key=os.environ.get("AI_FOUNDRY_API_KEY") or None,
         embedding_deployment_name=os.environ.get("AI_FOUNDRY_EMBEDDING_DEPLOYMENT_NAME", "text-embedding-3-large"),

Samples/Advanced/advanced_search_patterns.py

@@ -193,7 +193,7 @@ def main() -> None:
     mem = CosmosMemoryClient(
         cosmos_endpoint=cosmos_endpoint,
         cosmos_database=os.environ.get("COSMOS_DB_DATABASE", "ai_memory"),
-        cosmos_container=os.environ.get("COSMOS_DB_CONTAINER", "memories"),
+        cosmos_container=os.environ.get("COSMOS_DB_MEMORIES_CONTAINER", "memories"),
         cosmos_key=os.environ.get("COSMOS_DB_KEY"),
         ai_foundry_endpoint=ai_foundry_endpoint,
         ai_foundry_api_key=os.environ.get("AI_FOUNDRY_API_KEY"),

Samples/Notebooks/Demo.ipynb

@@ -63,7 +63,7 @@
     "load_dotenv(os.path.join(\"../..\", \".env\"))\n",
     "print(\"COSMOS_DB_ENDPOINT:\", os.getenv(\"COSMOS_DB_ENDPOINT\"))\n",
     "print(\"COSMOS_DB_DATABASE:\", os.getenv(\"COSMOS_DB_DATABASE\"))\n",
-    "print(\"COSMOS_DB_CONTAINER:\", os.getenv(\"COSMOS_DB_CONTAINER\"))\n",
+    "print(\"COSMOS_DB_MEMORIES_CONTAINER:\", os.getenv(\"COSMOS_DB_MEMORIES_CONTAINER\"))\n",
     "print(\"COSMOS_DB_COUNTERS_CONTAINER:\", os.getenv(\"COSMOS_DB_COUNTERS_CONTAINER\", \"counter\"))\n",
     "print(\"COSMOS_DB_LEASE_CONTAINER:\", os.getenv(\"COSMOS_DB_LEASE_CONTAINER\", \"leases\"))\n",
     "print(\"COSMOS_DB_THROUGHPUT_MODE:\", os.getenv(\"COSMOS_DB_THROUGHPUT_MODE\", \"serverless\"))\n",
@@ -94,7 +94,7 @@
     "memory = CosmosMemoryClient(\n",
     "    cosmos_endpoint=os.getenv(\"COSMOS_DB_ENDPOINT\"),\n",
     "    cosmos_database=os.getenv(\"COSMOS_DB_DATABASE\"),\n",
-    "    cosmos_container=os.getenv(\"COSMOS_DB_CONTAINER\"),\n",
+    "    cosmos_container=os.getenv(\"COSMOS_DB_MEMORIES_CONTAINER\"),\n",
     "    cosmos_counter_container=os.getenv(\"COSMOS_DB_COUNTERS_CONTAINER\", \"counter\"),\n",
     "    cosmos_lease_container=os.getenv(\"COSMOS_DB_LEASE_CONTAINER\", \"leases\"),\n",
     "    cosmos_throughput_mode=os.getenv(\"COSMOS_DB_THROUGHPUT_MODE\", \"serverless\"),\n",
@@ -419,7 +419,7 @@
    "outputs": [],
    "source": [
     "# Already connected via constructor — call connect_cosmos() only if you need to reconnect\n",
-    "print(f\"Connected: {memory._container_client is not None}\")"
+    "print(f\"Connected: {memory._memories_container_client is not None}\")"
    ]
   },
   {
@@ -692,7 +692,7 @@
     "2. Optionally keep only the **k most recent** documents (`recent_k`).\n",
     "3. Call the configured AI Foundry LLM to produce a structured summary.\n",
     "4. Generate a vector embedding of the summary.\n",
-    "5. Upsert the result back into Cosmos DB as a memory of type `\"summary\"`.\n",
+    "5. Upsert the result back into Cosmos DB as a memory of type `\"thread_summary\"`.\n",
     "\n",
     "If a prior summary exists, the call performs an **incremental update** that preserves the\n",
     "metadata-tracked `source_count`.\n"