Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,16 @@
## Release History

## [Unreleased]

#### Features Added
* **Memories are keyed by tenant and owner.** Every record lives in the partition `[tenant_id, user_id]`, where `user_id` is the owner of the memory, a user or an agent, and `thread_id` is a plain field. Everything one owner knows now sits in one partition. Pass `tenant_id` to the client (default `"default"`) to keep several apps or customers apart in the same containers; it separates data but is not an access-control boundary. `InProcessProcessor` and `AsyncInProcessProcessor` expose a read-only `tenant_id`, and a client raises `ConfigurationError` when its `processor` works in another tenant. The Function App follows the tenant of each record, and a failure for one thread or owner no longer stops the rest of its batch. See [PR:#53](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/53)

#### Breaking Changes
* **The containers use a new partition key.** `memories`, `memories_turns`, `memories_summaries` and `counter` are keyed `[/tenant_id, /user_id]` instead of `[/user_id, /thread_id]` (the Bicep template and `create_memory_store()`). A partition key can't change in place, so recreate those containers and `leases`, in the order given in the [migration notes](README.md#migration-notes) (every writer stopped, in-flight orchestrations purged, the Function App deployed before the upgraded writers); existing data is not migrated. Record ids must now be unique per owner across threads, not per thread. See [PR:#53](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/53)

#### Other Changes
* Orchestration instance ids in the Function App are now `<kind>:<digest>[:<count>]`, where the digest is a fixed-length hash of the tenant, owner and thread. They stay within Durable Functions' 100-character limit and no longer contain user ids. See [PR:#53](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/53)

## [0.4.0b1] (2026-11-16)

#### Features Added
Expand Down
4 changes: 2 additions & 2 deletions Docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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, episodic, procedural, user summary), threads, roles, embeddings and search (result slots, conflicting facts), the processing pipeline and fact extraction, secret redaction, reconciliation, automatic change feed processing, and shared Cosmos throughput configuration. |
| [concepts.md](concepts.md) | Explains the core memory model, including memory types (turn, summary, fact, episodic, procedural, user summary), tenants and owners (the `[tenant_id, user_id]` partition key), threads, roles, embeddings and search (result slots, conflicting facts), the processing pipeline and fact extraction, secret redaction, reconciliation, automatic change feed processing, and shared Cosmos throughput configuration. |
| [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 with serverless or autoscale container provisioning. |
| [azure_testing.md](azure_testing.md) | Covers Azure deployment, cloud configuration, required services, change feed settings, throughput mode configuration, 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, memory retrieval and search slots, procedures and standing instructions, reconciliation and conflicting facts, and secret handling and deletion in chat and multi-agent applications, including automatic processing via the change feed. |
| [design_patterns.md](design_patterns.md) | Shows when and how to call CRUD operations, summarization, fact extraction, memory retrieval and search slots, procedures and standing instructions, reconciliation and conflicting facts, secret handling and deletion, and tenants and agent-owned memory in chat and multi-agent applications, including automatic processing via the change feed. |
| [public_api.md](public_api.md) | Documents the `CosmosMemoryClient` and `AsyncCosmosMemoryClient` methods (connection, CRUD, retrieval, processing, tagging), fact and procedure fields, secret redaction, topology validation, and extension points. |
| [operations.md](operations.md) | Covers runtime settings for a deployment: memory TTLs, counter-based trigger thresholds, and reconcile, procedure, extraction prompt and Cosmos DB region settings. |
| [architecture/orchestrators.md](architecture/orchestrators.md) | Describes the Function App's Durable orchestrators and their activity chains, the time-budgeted reconcile and procedure activities, and how failed activities are reported without exposing message text. |
Expand Down
2 changes: 2 additions & 0 deletions Docs/architecture/orchestrators.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ SynthesizeProceduralOrchestrator

A batch whose model call fails with a retryable error yields no facts and is counted in `deferred_turn_count`. `em_AdvanceExtractWatermark` still moves past its turns, so the Function App does not retry them (the in-process backend does).

Every orchestration input and activity payload carries `tenant_id`, which the change feed trigger reads from the changed turn, and each activity runs the pipeline of that tenant (one per tenant, sharing the Cosmos DB and model clients), so one Function App serves every tenant. An orchestration instance ID is `{kind}:{digest}:{count}`, where `kind` is `extract`, `episode`, `thread_summary`, `user_summary` or `procedural` and `digest` is a fixed-length digest of the tenant, owner and (where there is one) thread, so IDs stay within the 100-character limit and hold no user IDs.

Fact IDs are deterministic from user, thread, and normalized content, and episode IDs from user, thread, the segment's first and last turn and the episode's position in it. Thread and user summaries keep their deterministic summary IDs. Procedure IDs derive from the user, kind and name, and a combined fact's ID from the user and its source IDs, so a retried activity finds the record it already wrote (409) instead of writing a second one.

`UserSummaryOrchestrator` can start before extraction has persisted anything for a new user. `us_Extract` then returns `no_memories_yet` instead of failing, and the orchestrator polls on a durable timer (App Settings `USER_SUMMARY_WAIT_SECONDS`, default `120`, every `USER_SUMMARY_WAIT_INTERVAL_SECONDS`, default `10`) before it skips that cadence; the next user-summary threshold tries again. `USER_SUMMARY_WAIT_SECONDS=0` makes it a single attempt.
Expand Down
6 changes: 3 additions & 3 deletions Docs/azure_testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,7 @@ az functionapp config appsettings set \
USER_SUMMARY_EVERY_N="10"
```

Set any threshold to `"0"` to disable that processing type.
Set any threshold to `"0"` to disable that processing type. There is no tenant setting: the Function App processes each turn in the tenant stored on it, which is the `tenant_id` of the client that wrote it (`"default"` unless set).

The `leases` container is provisioned by `create_memory_store()` alongside the other containers, so the Function App should be configured to use that existing lease container.

Expand Down Expand Up @@ -255,11 +255,11 @@ memory = AsyncCosmosMemoryClient(
cosmos_credential=AsyncDefaultAzureCredential(),
)

await memory.connect_cosmos()
await memory.create_memory_store()
await memory.connect_cosmos()
```

This provisions the `memories`, `memories_turns`, `memories_summaries`, `counter`, and `leases` containers. `serverless` is the default throughput mode; if you set `COSMOS_DB_THROUGHPUT_MODE=autoscale`, the shared `COSMOS_DB_AUTOSCALE_MAX_RU` value is applied to all five containers. The Function App does not read either variable.
This provisions the `memories`, `memories_turns`, `memories_summaries`, `counter`, and `leases` containers. The first four get the hierarchical partition key `/tenant_id`, `/user_id` (`leases` uses `/id`); an existing container keeps its key, and `create_memory_store()` and `connect_cosmos()` refuse one that is not keyed `[/tenant_id, /user_id]`, so recreate the containers that an earlier version created with `[/user_id, /thread_id]`, and `leases` with them (the README's [migration notes](../README.md#migration-notes) give the steps in order). `serverless` is the default throughput mode; if you set `COSMOS_DB_THROUGHPUT_MODE=autoscale`, the shared `COSMOS_DB_AUTOSCALE_MAX_RU` value is applied to all five containers. The Function App does not read either variable. On a new database, create the store before connecting, because `connect_cosmos()` refuses a container that does not exist.

---

Expand Down
Loading
Loading