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
22 changes: 20 additions & 2 deletions .env.template
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,19 @@ COSMOS_DB_SUMMARIES_CONTAINER="memories_summaries"
COSMOS_DB_TURNS_CONTAINER="memories_turns"
COSMOS_DB_COUNTERS_CONTAINER=counter
COSMOS_DB_LEASE_CONTAINER=leases
# Optional. Comma-separated Cosmos DB regions the SDK reads from, closest first
# (for example "West US 3,West US 2"). Leave blank to keep the account's default order.
# The Function App does not read this setting.
COSMOS_DB_PREFERRED_REGIONS=

# ---- Processing thresholds (set to 0 to disable) ----
THREAD_SUMMARY_EVERY_N=10
FACT_EXTRACTION_EVERY_N=2
USER_SUMMARY_EVERY_N=20
# Reconcile (fold duplicates, combine facts, link conflicting facts) runs every DEDUP_EVERY_N
# extractions, so every FACT_EXTRACTION_EVERY_N x DEDUP_EVERY_N turns. 0 also turns off the
# procedure learning that follows it.
DEDUP_EVERY_N=5

# Episodic memory (boundary-based segmentation). EPISODE_EVAL_EVERY_N=0 disables episodic memory.
EPISODE_EVAL_EVERY_N=4
Expand All @@ -31,6 +39,12 @@ EPISODE_TOPIC_DRIFT=0
EPISODE_MAX_TURNS=40
EPISODE_MIN_TURNS=2

# ---- Reconcile and procedure learning ----
# The most facts one automatic reconcile checks (1-500; a larger value is capped at 500).
DEDUP_POOL_SIZE=50
# Learn procedures after each reconcile. Set to false to turn it off.
PROCEDURAL_SYNTHESIS_AUTO=true

# ---- 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.
Expand All @@ -50,8 +64,9 @@ MEMORY_PROCESSOR_OWNER=
# Use the account-level inference endpoint. Both of these forms work:
# https://<your-account>.services.ai.azure.com
# https://<your-account>.openai.azure.com
# A project-scoped Foundry URL (".../api/projects/<name>") is also accepted and
# automatically normalized to the inference base.
# A project-scoped Foundry URL (".../api/projects/<name>") is also accepted by the SDK and
# automatically normalized to the inference base. The Function App does not normalize it,
# so give it the account-level form.
AI_FOUNDRY_ENDPOINT=https://<your-account>.openai.azure.com/
AI_FOUNDRY_API_KEY=
AI_FOUNDRY_EMBEDDING_DEPLOYMENT_NAME=text-embedding-3-large
Expand All @@ -66,3 +81,6 @@ 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=
# Optional. Fact-extraction prompt. Leave blank for the default, extract_memories-v3.prompty;
# extract_memories-v2.prompty and extract_memories.prompty select the earlier prompts.
AMT_EXTRACT_MEMORIES_PROMPT=
2 changes: 1 addition & 1 deletion .github/CODEOWNERS
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
# These owners are required reviewers for all changes
@akataria @jcodella @TheovanKraay
* @aayush3011 @jcodella @TheovanKraay
31 changes: 31 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,36 @@
## Release History

## [Unreleased]

#### Features Added
* **New extraction prompt.** `extract_memories-v3.prompty` is now the default. Set `AMT_EXTRACT_MEMORIES_PROMPT` to use an earlier prompt. See [PR:#51](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/51)
* **Duplicates are folded and combined.** `reconcile()` retires a fact into another that states everything it states (`supersede_reason="duplicate"`, with `merged_from` on the survivor) and combines facts about one specific thing into one `sys:combined` fact (`supersede_reason="combined"`). It returns counts for both passes, and `DEDUP_POOL_SIZE` limits how many new facts one pass checks. See [PR:#51](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/51)
* **Conflicting facts are linked, not retired.** When `reconcile()` finds a fact that updates or contradicts another, both stay active and are linked. `search_cosmos(user_id=...)` returns each with `conflicts_with` (up to two partners, each with `id`, `content`, `created_at` and `kind`), so an assistant can show both and ask which is right. See [PR:#51](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/51)
* **Procedural memory is learned from conversations.** The toolkit learns standing instructions, habits and skills from what users teach and correct, and `build_procedural_context(user_id, task=None)` returns the rules to add to a prompt. See [PR:#51](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/51)
* **Search slots.** `search_cosmos(preference_slot=True, procedure_slot=True)` reserves places in `top_k` for the user's best-matching preference and situational procedure, so closer-matching facts do not crowd them out. See [PR:#51](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/51)
* **Secrets are redacted on write.** Common credential formats (keys, tokens, connection strings, private keys, passwords in URLs) are replaced with `[REDACTED-SECRET]` before text is embedded or stored, and the record is tagged `sys:secret`.
* **Deleting a memory removes what was folded into it.** `delete_memory()` also deletes the records retired into the deleted fact or procedure. See [PR:#51](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/51)
* **Time-budgeted passes.** `PipelineService.reconcile_memories()`, `consolidate_memories()` and `synthesize_procedural()` accept a `deadline`. The Function App sets it from the new `ACTIVITY_TIME_BUDGET_SECONDS` (default 240), so a run stops before the function timeout and the next one continues. See [PR:#51](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/51)
* **Cosmos DB read regions.** `cosmos_preferred_locations` (or `COSMOS_DB_PREFERRED_REGIONS`) sets the regions the SDK reads from, closest first. See [PR:#51](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/51)

#### Breaking Changes
* **`reconcile()` no longer retires a fact because another contradicts it.** The contradiction pass and `dedup.prompty` are removed, nothing writes `supersede_reason="contradict"` any more, and the `contradicted` count in the result is now `conflicts`. Facts retired by earlier betas stay retired. See [PR:#51](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/51)
* **Procedural memory is reshaped** `procedure_kind` is now `instruction`, `habit` or `skill`, and a procedure's `status` follows from its evidence. `scope_type` / `scope_value`, `ProcedureScopeType` and `synthesize_procedural.prompty` are removed, `synthesize_procedural()` works incrementally, `build_procedural_context()` returns only standing rules (plus the nearest situational rule for a `task`), and `search_cosmos()` hides procedures that are not active. Delete or ignore procedural documents written by earlier betas. See [PR:#51](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/51)
* **Logs and failure messages no longer quote exception text.** JSON logs write `exc_detail` (type, error code and location) instead of `exc_msg`, so update any query or alert that reads `exc_msg`. A failed Function App activity now reports only `<code> (<ExcType>)` to Durable Functions. See [PR:#51](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/51)
* **Bicep creates `memories_summaries` with a vector and full-text index**, as `create_memory_store()` already does, so `search_summaries()` works on a deployment from the template. Cosmos DB sets a vector policy only when a container is created: an environment provisioned from an earlier template needs that container created again, and `azd up` over it can fail. See [PR:#51](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/51)

#### Bugs Fixed
* Procedure learning no longer ignores newer facts and episodes. See [PR:#51](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/51)
* Turns with the same `created_at`, as in an imported session, are processed in write order, and `recent_k` keeps the newest.
* Empty model replies are retried, and content-filtered or refused replies raise an `LLMError` that names the cause instead of being retried on every run. See [PR:#51](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/51)
* The Function App parses boolean settings like the SDK does, and a `MAX_BATCH_SIZE` below 1 falls back to 20 instead of silently skipping the backlog. See [PR:#51](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/51)

#### Other Changes
* New prompts `extract_memories-v3`, `dedup_verify` and `combine_memories`; `extract_procedure` is rewritten. Every memory-writing prompt now tells the model never to write a literal secret. See [PR:#51](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/51)
* Search results include the new fact and procedure fields and `merged_from`, and `MemoryStore.search()` gains `categories`, `vector_only`, `active_procedures_only`, `applies` and `query_embedding`. See [PR:#51](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/51)
* Bicep adds the `dedupPoolSize`, `activityTimeBudgetSeconds`, `chatCapacity` and `embeddingCapacity` parameters (azd variables `DEDUP_POOL_SIZE`, `ACTIVITY_TIME_BUDGET_SECONDS`, `AI_FOUNDRY_CHAT_CAPACITY`, `AI_FOUNDRY_EMBEDDING_CAPACITY`). New `counter` containers expire their documents 90 days after the last update; existing containers are unchanged. See [PR:#51](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/51)
* The SDK now requires `azure-cosmos>=4.16.3`. See [PR:#51](https://github.com/AzureCosmosDB/AgentMemoryToolkit/pull/51)

## [0.3.0b2] (2026-08-17)

#### Features Added
Expand Down
14 changes: 10 additions & 4 deletions Docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,22 @@ 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, the processing pipeline, 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), 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, and memory retrieval in chat and multi-agent applications, including automatic processing via the change feed. |
| [troubleshooting.md](troubleshooting.md) | Helps diagnose common setup, authentication, Cosmos DB, embeddings, Durable Functions, vector search, and change feed issues. |
| [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. |
| [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. |
| [troubleshooting.md](troubleshooting.md) | Helps diagnose common setup, authentication, Cosmos DB, embeddings, vector search (including hidden records, result slots and conflicting facts), Durable Functions (including failed activities and logs), change feed, and async client issues. |
| [RELEASING.md](RELEASING.md) | Maintainer runbook for versioning, the pre-flight checklist, cutting a release, the namespace package check, and yanking a bad release. |

## Recommended Reading Order

1. Start with [concepts.md](concepts.md) to understand the data model and memory lifecycle.
2. Use [local_testing.md](local_testing.md) to get the toolkit running and validated on your machine.
3. Use [azure_testing.md](azure_testing.md) when you are ready to deploy or validate the full stack in Azure.
4. See [design_patterns.md](design_patterns.md) for integration patterns in real applications.
5. Use [troubleshooting.md](troubleshooting.md) when setup, processing, search, or automatic change feed behavior does not work as expected.
5. Keep [public_api.md](public_api.md) at hand for client methods and fields, and use [operations.md](operations.md) to tune TTLs and runtime settings.
6. Read [architecture/orchestrators.md](architecture/orchestrators.md) to see how the Function App chains its processing activities.
7. Use [troubleshooting.md](troubleshooting.md) when setup, processing, search, or automatic change feed behavior does not work as expected.
27 changes: 17 additions & 10 deletions Docs/RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,9 @@ This project uses [PEP 440](https://peps.python.org/pep-0440/) versioning:

Before cutting a release:

1. **CI green on `main`** - every workflow in `.github/workflows/` passes.
1. **CI green on `main`** - the `CI` workflow (`.github/workflows/ci.yml`:
lint, unit tests on Python 3.11-3.13, and the Function app import smoke
test) passes.
2. **Unit tests pass locally** in a fresh venv:
```bash
python -m venv /tmp/release-venv
Expand All @@ -32,23 +34,28 @@ Before cutting a release:
```bash
AGENT_MEMORY_RUN_INTEGRATION=true pytest tests/integration -q
```
The change-feed test also needs `AGENT_MEMORY_RUN_CHANGEFEED=true` and a
running Functions host; without it the test is skipped.
4. **Samples and notebooks work** - every script under `Samples/` runs to
completion against the live environment.
5. **No uncommitted local changes** - `git status` clean.

## Cutting a release

1. **Bump the version** in `pyproject.toml`:
2. **Update `CHANGELOG.md`** - add a new section with the version, the
date, and a summary of changes. Move entries from the unreleased
section if you keep one.
1. **Bump the version** in `pyproject.toml`, in the `metadata.template` line
of `azure.yaml` (`azure-cosmos-agent-memory@<NEW_VERSION>`), and in
`uv.lock` (run `uv lock` to refresh the package's own entry).
2. **Update `CHANGELOG.md`** - rename the unreleased section to
`## [<NEW_VERSION>] (<date>)`, or add a new section with the version, the
date, and a summary of changes if there is none.
3. **Bump the Function app's SDK pin** in `function_app/requirements.txt`
to match - `azure-cosmos-agent-memory==<NEW_VERSION>`. The FA installs
the SDK from PyPI, so the pin must move in lockstep with the SDK
release. (If the release workflow fails after merge, the FA will be
pinned to a non-existent version until you cut a follow-up patch -
coordinate the merge + release-workflow run together.)
4. **Open a PR** with the version bump + CHANGELOG + updated FA pin.
4. **Open a PR** with the version bump (`pyproject.toml`, `azure.yaml`,
`uv.lock`) + CHANGELOG + updated FA pin.
Suggested title: `Release v<NEW_VERSION>`. Get it reviewed and merged
to `main`.
5. **Trigger the release workflow**:
Expand Down Expand Up @@ -86,10 +93,10 @@ but never the standalone `azure/__init__.py` or `azure/cosmos/__init__.py`.

If a release ships a regression:

1. **Yank** the version on PyPI (does not delete; marks installs as a warning):
```bash
twine yank azure-cosmos-agent-memory --version <BAD_VERSION>
```
1. **Yank** the version on PyPI (does not delete; installers skip it unless
it is pinned exactly). `twine` has no yank command, so use the web UI: open
<https://pypi.org/manage/project/azure-cosmos-agent-memory/releases/>,
choose **Options → Yank** next to `<BAD_VERSION>`, and give a reason.
2. **Cut a new patch release** with the fix and updated CHANGELOG.
3. Add a deprecation note to the GitHub Release pointing at the
replacement version.
Expand Down
Loading
Loading