Repository navigation
Partition memories by [tenant_id, user_id]; thread_id becomes a plain field - #53
Merged
Aayush Kataria (aayush3011) merged 4 commits intoNov 18, 2026
Conversation
… field Every record now lives in the logical partition [tenant_id, user_id] instead of [user_id, thread_id]. user_id is the owner of a memory (a user or an agent) and thread_id is a plain field, so everything one owner knows sits in one partition. - Clients take tenant_id (default "default") and stamp it on every record they write. A client reads and writes only inside its tenant, and the Function App follows the tenant of each changed turn. - Containers are created with the hierarchical key /tenant_id, /user_id (SDK and Bicep). create_memory_store(), validate_topology() and the Function App refuse an existing container with another key. - tenant_id and user_id are validated: non-empty, at most 256 UTF-8 bytes, and no / \ ? # or control characters. - thread_id is removed from update_cosmos, delete_memory, delete_turn, add_tags, remove_tags and get_memory_history, and from MemoryNotFoundError. Record ids are unique per owner across threads. - Function App orchestration instance ids are a fixed-length hash of tenant, owner and thread. - Tests guard that every owner filter names the tenant and that no partition key is built by hand. Breaking: recreate the containers, and leases with them. Existing data is not migrated. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Aayush Kataria (aayush3011)
marked this pull request as ready for review
November 17, 2026 23:57
Aayush Kataria (aayush3011)
requested review from
Theo van Kraay (TheovanKraay) and
James Codella (jcodella)
as code owners
November 17, 2026 23:57
Aayush Kataria (aayush3011)
marked this pull request as draft
November 17, 2026 23:57
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Identifier validation still allows DEL and C1 control characters, and the tenant-scope guard can miss queries without tenant isolation.
2 open issues
What changed in this PR
Changes the memory store’s partition model to [tenant_id, user_id], keeping each owner’s records together while making thread_id a regular field. This is a breaking layout change requiring container recreation; existing data is not migrated.
Changes:
- Centralizes tenant and owner validation, partition keys, and query filters.
- Propagates tenant scope through processing, counters, and Durable Functions, with hashed orchestration IDs.
- Updates infrastructure, regression tests, samples, and documentation for the new layout and APIs.
| File | Description |
|---|---|
tests/unit/test_utils.py |
Tests tenant-scoped memory query construction. |
tests/unit/test_tenant_scope_guard.py |
Adds source guards for tenant filters and partition keys. |
tests/unit/test_search_slots.py |
Checks owner-partition procedure searches. |
tests/unit/test_search_conflicts.py |
Tests tenant-scoped conflict lookups. |
tests/unit/test_reconcile.py |
Adds tenant context to reconciliation fixtures. |
tests/unit/test_query_builder.py |
Tests tenant and owner predicates. |
tests/unit/test_pipeline_confidence.py |
Checks extraction and summary tenant scope. |
tests/unit/test_no_exception_text_in_logs.py |
Updates counter-helper call fixtures. |
tests/unit/test_models.py |
Tests tenant defaults and record serialization. |
tests/unit/test_min_confidence.py |
Supplies tenant context to query tests. |
tests/unit/test_memory_type_multi.py |
Updates multi-type queries for tenant scope. |
tests/unit/test_log_redaction.py |
Adds tenant context to redaction fixtures. |
tests/unit/test_exceptions.py |
Verifies removal of thread context from lookup errors. |
tests/unit/store/test_update_embedding_fallback.py |
Uses owner partitions in update tests. |
tests/unit/store/test_tag_mutation.py |
Removes thread arguments from tag mutations. |
tests/unit/store/test_search_routing.py |
Tests keyword and vector routing with tenants. |
tests/unit/store/test_list_tags.py |
Checks owner-partition tag listing. |
tests/unit/store/test_get_memory_history.py |
Tests history traversal across an owner’s threads. |
tests/unit/services/test_user_summary_topic_tags.py |
Tests summary tenant stamping and rejection. |
tests/unit/services/test_transcript_metadata.py |
Checks tenant propagation into pipelines. |
tests/unit/services/test_secret_redaction_writes.py |
Tests tenant boundaries on sanitized writes. |
tests/unit/services/test_reconcile_passes.py |
Adds tenant-aware reconciliation fixtures. |
tests/unit/services/test_procedures.py |
Tests tenant-scoped procedure queries and records. |
tests/unit/services/test_persist_extracted.py |
Tests tenant stamping and foreign-tenant rejection. |
tests/unit/services/test_mark_turns_extracted.py |
Checks extraction markers use owner partitions. |
tests/unit/services/test_extract_episodes.py |
Tests tenant isolation and cross-thread episode IDs. |
tests/unit/services/test_extract_dry.py |
Makes fake reads partition-aware; tests distinct fact IDs. |
tests/unit/services/test_episodic_retrieval.py |
Checks owner-partition episode retrieval. |
tests/unit/services/test_dedup.py |
Tests tenant-aware deduplication queries and cursors. |
tests/unit/services/test_consolidate_memories.py |
Checks consolidation reads and writes stay scoped. |
tests/unit/services/test_combine.py |
Tests tenant-scoped fact combination. |
tests/unit/services/test_absorbed.py |
Checks cascade deletion within owner partitions. |
tests/unit/processors/test_base.py |
Tests tenant-bound processor construction. |
tests/unit/function_app/test_synthesize_procedural_orchestrator.py |
Tests tenant propagation through procedure orchestration. |
tests/unit/function_app/test_pipeline_factory.py |
Tests per-tenant pipelines and shared clients. |
tests/unit/function_app/test_instance_ids.py |
Tests hashed orchestration ID uniqueness and limits. |
tests/unit/function_app/test_failure_logs.py |
Updates tenant-aware failure-log expectations. |
tests/unit/function_app/test_extract_episodes_orchestrator.py |
Tests tenant-aware episode orchestration. |
tests/unit/function_app/test_error_redaction.py |
Updates tenant-aware orchestration fixtures. |
tests/unit/aio/test_search_slots.py |
Checks async owner-partition procedure searches. |
tests/unit/aio/test_reconcile_passes.py |
Adds tenant scope to async reconciliation tests. |
tests/unit/aio/test_consolidate_memories.py |
Checks async consolidation partition keys. |
tests/unit/aio/test_conflict_links.py |
Updates async conflict tests for owner partitions. |
tests/unit/aio/test_combine.py |
Checks async combination reads and tenant stamping. |
tests/unit/aio/store/test_update_embedding_fallback.py |
Uses owner partitions in async update tests. |
tests/unit/aio/store/test_search_routing.py |
Tests async tenant-aware search routing. |
tests/unit/aio/store/test_get_memory_history.py |
Checks async history uses owner partitions. |
tests/unit/aio/services/test_procedural_retrieval_async.py |
Tests tenant filters in async procedure retrieval. |
tests/unit/aio/services/test_mark_turns_extracted_async.py |
Checks async extraction-marker partition keys. |
tests/unit/aio/services/test_episodic_retrieval_async.py |
Tests tenant-scoped async episode retrieval. |
tests/unit/aio/processors/test_base.py |
Tests async tenant-bound processor construction. |
tests/integration/test_ttl_lifecycle.py |
Uses the integration tenant and revised deletion API. |
tests/integration/test_procedural_pipeline.py |
Scopes procedural tests and cleanup by tenant. |
tests/integration/test_full_pipeline.py |
Updates live queries, cleanup, and mutation calls. |
tests/integration/test_episodic_pipeline.py |
Scopes episodic tests and cleanup by tenant. |
tests/integration/test_changefeed_integration.py |
Adds tenants to turns and counter reads. |
tests/integration/test_async_full_pipeline.py |
Scopes async live queries and cleanup by tenant. |
tests/conftest.py |
Adds a non-default integration tenant fixture. |
Samples/Scenarios/scenario_rag_with_memory.py |
Removes thread arguments from cleanup calls. |
Samples/Scenarios/scenario_memory_reconciliation.py |
Updates reconciliation cleanup calls. |
Samples/Scenarios/scenario_counter_tuning.py |
Updates the counter-scope description only. |
Samples/Quickstarts/quickstart_cosmos.py |
Shows optional tenant configuration and revised mutations. |
Samples/Processing/processing_procedural_memory.py |
Updates procedure cleanup calls. |
Samples/Processing/processing_episodic_memory.py |
Updates episode cleanup calls. |
Samples/Notebooks/Demo.ipynb |
Removes thread arguments from update and delete examples. |
Samples/Notebooks/Demo_async.ipynb |
Updates async mutation examples. |
Samples/Advanced/advanced_memory_lifecycle.py |
Updates turn-deletion calls. |
README.md |
Explains owner partitions and breaking changes. |
infra/README.md |
Documents partition keys and container recreation. |
infra/modules/functions.bicep |
Updates threshold descriptions only. |
infra/modules/cosmos.bicep |
Changes container keys and the summary composite index. |
infra/main.bicep |
Updates tenant-aware cadence descriptions only. |
function_app/shared/pipeline_factory.py |
Caches tenant-bound pipelines with shared clients. |
function_app/shared/instance_ids.py |
Adds deterministic hashed orchestration IDs. |
function_app/shared/counters.py |
Scopes counters and watermarks to owner partitions. |
function_app/orchestrators/user_summary.py |
Propagates tenant scope through user summaries. |
function_app/orchestrators/thread_summary.py |
Propagates tenant scope through thread summaries. |
function_app/orchestrators/synthesize_procedural.py |
Selects the tenant’s procedure pipeline. |
function_app/orchestrators/extract_memories.py |
Adds tenant payloads, scoped watermarks, and hashed IDs. |
function_app/orchestrators/extract_episodes.py |
Selects the tenant’s episode pipeline. |
Docs/troubleshooting.md |
Explains tenant visibility and topology mismatches. |
Docs/README.md |
Updates documentation descriptions. |
Docs/operations.md |
Documents tenant selection and multi-tenant processing. |
Docs/local_testing.md |
Updates local topology and orchestration examples. |
Docs/azure_testing.md |
Documents tenant handling and container recreation. |
Docs/architecture/orchestrators.md |
Explains tenant payloads and hashed instance IDs. |
CHANGELOG.md |
Records tenant partitioning and breaking API changes. |
azure/cosmos/agent_memory/store/_search_helpers.py |
Adds tenant projections and owner-based search routing. |
azure/cosmos/agent_memory/services/_procedures.py |
Makes procedure scope and records tenant-aware. |
azure/cosmos/agent_memory/services/_extraction_context.py |
Adds tenant filters to extraction-context queries. |
azure/cosmos/agent_memory/services/_dedup.py |
Adds tenant scope to deduplication queries and cursors. |
azure/cosmos/agent_memory/services/_absorbed.py |
Performs cascade lookups and deletes within owner partitions. |
azure/cosmos/agent_memory/services/__init__.py |
Documents the protocol’s owner partition key. |
azure/cosmos/agent_memory/processors/inprocess.py |
Constructs tenant-bound stores and pipelines. |
azure/cosmos/agent_memory/models.py |
Adds the record’s tenant field. |
azure/cosmos/agent_memory/exceptions.py |
Removes thread context from memory lookup errors. |
azure/cosmos/agent_memory/auto_trigger.py |
Passes tenant scope to counter operations. |
azure/cosmos/agent_memory/aio/processors/inprocess.py |
Constructs async tenant-bound processing components. |
azure/cosmos/agent_memory/aio/auto_trigger.py |
Passes tenant scope to async counter operations. |
azure/cosmos/agent_memory/_utils.py |
Starts memory queries with tenant and owner filters. |
azure/cosmos/agent_memory/_query_builder.py |
Adds tenant-scoped query initialization. |
azure/cosmos/agent_memory/_partitioning.py |
Centralizes identifiers, scope helpers, and topology checks. |
azure/cosmos/agent_memory/_counters.py |
Moves SDK counters into tenant-owner partitions. |
azure/cosmos/agent_memory/_container_routing.py |
Updates partition-layout documentation only. |
azure/cosmos/agent_memory/_base/base_client.py |
Initializes and exposes the client’s tenant. |
Review effort: Balanced
Aayush Kataria (aayush3011)
marked this pull request as ready for review
November 18, 2026 15:14
Aayush Kataria (aayush3011)
merged commit Nov 18, 2026
bbcac4c
into
AzureCosmosDB:main
8 checks passed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

Summary
Partitions every record by
[tenant_id, user_id]instead of[user_id, thread_id], and makesthread_ida plain field. This is a breaking change to the container layout; the version and release are separate (see below).What changed
user_idis the owner of a memory, a user or an agent. Turns, facts, episodes, procedures, summaries and counters for one owner sit in one logical partition, and a query that names the owner reads that partition only.tenant_id(default"default"), stamp it on every record they write, and read and write only inside it. There is no per-call tenant and no environment variable. The Function App reads the tenant from each changed turn and keeps one pipeline per tenant, so one deployment serves every tenant.memories,memories_turns,memories_summariesandcounteruse the hierarchical key/tenant_id,/user_id(create_memory_store()and Bicep);leasesstays/id.connect_cosmos(),validate_topology()and the Function App's first change-feed batch refuse a container that is missing or keyed otherwise, andcreate_memory_store()refuses an existing one keyed otherwise (it creates a missing one), because a container with the earlier key takes writes but reads back empty.connect_cosmos()reads the metadata of the four containers and closes the client when it refuses one.WHEREclause; vector-only searches stay in the owner's partition.get_memories()withoutuser_idcovers every owner in the client's tenant.tenant_id,user_idandthread_idmust be non-empty strings of at most 256 UTF-8 bytes that do not start or end with whitespace and have no/ \ ? #, control characters (DEL, the C1 range and the line and paragraph separators included) or lone surrogates, because they appear in document ids and Cosmos DB refuses one that ends in whitespace.add_local()refuses such an id up front, so a bad record never makes every later push fail. A record id is unique per owner across threads. Function App orchestration instance ids are a fixed-length hash of tenant, owner and thread, so they stay within Durable Functions' 100-character limit.tenant_idparameter, a comment or a scoped neighbouring query does not count), that a_QueryBuilderis made withfor_tenant, and that no partition key is written out by hand. It is a safety net, not a proof: the behaviour tests are what show that one tenant cannot read another's records.tenant_id; a client raisesConfigurationErrorwhen itsprocessorworks in another tenant, and a processor given apipelineand a differenttenant_iddoes too. A pipeline works in the tenant of its store unless given one, and refuses a store of another tenant. AMemoryRecordhas no tenant until it is written, and the client stamps its own.persist_thread_summary()andpersist_user_summary()take the owner from their argument,get_user_summary()raisesValidationErrorfor a bad owner, and the async client always resets its state when closing a refused connection fails.Docs/concepts.md; the README, the API, design-pattern, operations, troubleshooting, testing, architecture and infra docs, the seven affected samples and the two affected notebooks are updated.Breaking changes
memories,memories_turns,memories_summariesandcounter, andleaseswith them so the change feed starts clean. Existing data is not migrated. The README's migration notes give the order: stop every writer, recreate the containers, purge in-flight orchestrations, deploy the Function App before the upgraded writers.thread_idis removed fromupdate_cosmos(),delete_memory(),delete_turn(),add_tags(),remove_tags()andget_memory_history(), and fromMemoryNotFoundError. It still filters reads and names the thread for thread operations.user_idandthread_idare validated with the rules above; anything else raisesValidationError, and a change-feed turn with such an owner or thread is skipped.Validation
ruff checkandruff format --checkare clean.connect_cosmos(), invalid thread ids and records built without a tenant on both clients (19 checks); and a change feed holding turns with an integer, a trailing-space, a DEL and a listthread_idnext to two tenants' valid turns, where the bad turns are skipped and both tenants' counters and thread summaries complete (6 checks). After the last small changes (id validation, pipeline tenant defaults), the two-tenant check, the 24 in-process integration tests and two samples were run again. Azure Monitor shows no throttling.azd up, and an owner near the 20 GB / 10,000 RU/s limit of a logical partition.function_app/requirements.txtandazure.yamlpins, which still name 0.4.0b1. Move them with the release, and merge this together with it. Left for later: a retry policy on the change-feed trigger, a size bound for the Function App's per-tenant pipeline cache, a stored-type check inadd_tags(), a live two-tenant check in the repo, transactional batches (now possible with one partition per owner) and migration tooling.