Skip to content

Partition memories by [tenant_id, user_id]; thread_id becomes a plain field - #53

Merged
Aayush Kataria (aayush3011) merged 4 commits into
AzureCosmosDB:mainfrom
aayush3011:users/akataria/tenant-user-partition-key
Nov 18, 2026
Merged

Aayush Kataria (aayush3011) merged 4 commits into
AzureCosmosDB:mainfrom
aayush3011:users/akataria/tenant-user-partition-key

Conversation

@aayush3011

@aayush3011 Aayush Kataria (aayush3011) commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Partitions every record by [tenant_id, user_id] instead of [user_id, thread_id], and makes thread_id a plain field. This is a breaking change to the container layout; the version and release are separate (see below).

What changed

  • Owner partitions. user_id is 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.
  • Tenants. Both clients take 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.
  • Containers. memories, memories_turns, memories_summaries and counter use the hierarchical key /tenant_id, /user_id (create_memory_store() and Bicep); leases stays /id. connect_cosmos(), validate_topology() and the Function App's first change-feed batch refuse a container that is missing or keyed otherwise, and create_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.
  • Search. Keyword searches still cannot send a partition key (FullTextScore() in ORDER BY clause does not take affect in Cosmos DB NoSQL full-text queries with partition key Azure/azure-sdk-for-python#42241), so they run cross-partition with the tenant and owner in the WHERE clause; vector-only searches stay in the owner's partition. get_memories() without user_id covers every owner in the client's tenant.
  • Ids. tenant_id, user_id and thread_id must 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.
  • Guards. One module builds every key and owner filter. A source test checks each query on its own for the tenant filter (an unused tenant_id parameter, a comment or a scoped neighbouring query does not count), that a _QueryBuilder is made with for_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.
  • Hardening. In the Function App, a turn whose tenant, owner or thread id is not valid is skipped, and a failure for one thread or owner no longer stops the rest of its batch (one bad turn used to lose every tenant's counts in that batch). The in-process processors expose tenant_id; a client raises ConfigurationError when its processor works in another tenant, and a processor given a pipeline and a different tenant_id does too. A pipeline works in the tenant of its store unless given one, and refuses a store of another tenant. A MemoryRecord has no tenant until it is written, and the client stamps its own. persist_thread_summary() and persist_user_summary() take the owner from their argument, get_user_summary() raises ValidationError for a bad owner, and the async client always resets its state when closing a refused connection fails.
  • Docs, samples, notebooks. New "Tenants and Owners" section in 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

  • New partition key, no migration. A partition key cannot change in place: recreate memories, memories_turns, memories_summaries and counter, and leases with 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.
  • Record ids are unique per owner across threads, not per thread.
  • thread_id is removed from update_cosmos(), delete_memory(), delete_turn(), add_tags(), remove_tags() and get_memory_history(), and from MemoryNotFoundError. It still filters reads and names the thread for thread operations.
  • user_id and thread_id are validated with the rules above; anything else raises ValidationError, and a change-feed turn with such an owner or thread is skipped.

Validation

  • 3,478 unit tests pass; ruff check and ruff format --check are clean.
  • Run live against a Cosmos DB account and Azure OpenAI with Entra ID, with the containers created from the Bicep definitions: all 25 integration tests (24 in process, and the change-feed test against a local Functions host), all 18 samples and 4 notebooks, and every Function App function succeeding with no failures. Also passing: a two-tenant isolation check (26 checks); a check that a container with the earlier key is refused by the sync client, the async client and the Function App (21 checks); a check of 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 list thread_id next 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.
  • Not checked: a deployed (not local) Function App through azd up, and an owner near the 20 GB / 10,000 RU/s limit of a logical partition.
  • Not in this PR: the SDK version, and the function_app/requirements.txt and azure.yaml pins, 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 in add_tags(), a live two-tenant check in the repo, transactional batches (now possible with one partition per owner) and migration tooling.

… 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>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Comment thread tests/unit/test_tenant_scope_guard.py Resolved
@aayush3011
Aayush Kataria (aayush3011) marked this pull request as ready for review November 18, 2026 15:14
@aayush3011
Aayush Kataria (aayush3011) merged commit bbcac4c into AzureCosmosDB:main Nov 18, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants