- New extraction prompt.
extract_memories-v3.promptyis now the default. SetAMT_EXTRACT_MEMORIES_PROMPTto use an earlier prompt. See PR:#51 - Duplicates are folded and combined.
reconcile()retires a fact into another that states everything it states (supersede_reason="duplicate", withmerged_fromon the survivor) and combines facts about one specific thing into onesys:combinedfact (supersede_reason="combined"). It returns counts for both passes, andDEDUP_POOL_SIZElimits how many new facts one pass checks. See PR:#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 withconflicts_with(up to two partners, each withid,content,created_atandkind), so an assistant can show both and ask which is right. See PR:#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 - Search slots.
search_cosmos(preference_slot=True, procedure_slot=True)reserves places intop_kfor the user's best-matching preference and situational procedure, so closer-matching facts do not crowd them out. See PR:#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 taggedsys: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 - Time-budgeted passes.
PipelineService.reconcile_memories(),consolidate_memories()andsynthesize_procedural()accept adeadline. The Function App sets it from the newACTIVITY_TIME_BUDGET_SECONDS(default 240), so a run stops before the function timeout and the next one continues. See PR:#51 - Cosmos DB read regions.
cosmos_preferred_locations(orCOSMOS_DB_PREFERRED_REGIONS) sets the regions the SDK reads from, closest first. See PR:#51
reconcile()no longer retires a fact because another contradicts it. The contradiction pass anddedup.promptyare removed, nothing writessupersede_reason="contradict"any more, and thecontradictedcount in the result is nowconflicts. Facts retired by earlier betas stay retired. See PR:#51- Procedural memory is reshaped
procedure_kindis nowinstruction,habitorskill, and a procedure'sstatusfollows from its evidence.scope_type/scope_value,ProcedureScopeTypeandsynthesize_procedural.promptyare removed,synthesize_procedural()works incrementally,build_procedural_context()returns only standing rules (plus the nearest situational rule for atask), andsearch_cosmos()hides procedures that are not active. Delete or ignore procedural documents written by earlier betas. See PR:#51 - Logs and failure messages no longer quote exception text. JSON logs write
exc_detail(type, error code and location) instead ofexc_msg, so update any query or alert that readsexc_msg. A failed Function App activity now reports only<code> (<ExcType>)to Durable Functions. See PR:#51 - Bicep creates
memories_summarieswith a vector and full-text index, ascreate_memory_store()already does, sosearch_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, andazd upover it can fail. See PR:#51
- Procedure learning no longer ignores newer facts and episodes. See PR:#51
- Turns with the same
created_at, as in an imported session, are processed in write order, andrecent_kkeeps the newest. - Empty model replies are retried, and content-filtered or refused replies raise an
LLMErrorthat names the cause instead of being retried on every run. See PR:#51 - The Function App parses boolean settings like the SDK does, and a
MAX_BATCH_SIZEbelow 1 falls back to 20 instead of silently skipping the backlog. See PR:#51
- New prompts
extract_memories-v3,dedup_verifyandcombine_memories;extract_procedureis rewritten. Every memory-writing prompt now tells the model never to write a literal secret. See PR:#51 - Search results include the new fact and procedure fields and
merged_from, andMemoryStore.search()gainscategories,vector_only,active_procedures_only,appliesandquery_embedding. See PR:#51 - Bicep adds the
dedupPoolSize,activityTimeBudgetSeconds,chatCapacityandembeddingCapacityparameters (azd variablesDEDUP_POOL_SIZE,ACTIVITY_TIME_BUDGET_SECONDS,AI_FOUNDRY_CHAT_CAPACITY,AI_FOUNDRY_EMBEDDING_CAPACITY). Newcountercontainers expire their documents 90 days after the last update; existing containers are unchanged. See PR:#51 - The SDK now requires
azure-cosmos>=4.16.3. See PR:#51
- Episodic memory is now a first-class memory type. Bounded experiences are segmented from the turn stream at idle-gap, topic-drift, and max-size boundaries, each captured as an
EpisodicRecordwith a summary, timeline events, an optional outcome, and first-classlessons. See PR:#37 search_cosmos(include_episodes=True)blends facts and episodes into a single ranked query sharing onetop_kbudget, andsearch_episodic_memories()searches episodes directly. See PR:#37- Fact extraction now defaults to the higher-recall v2 prompt (
extract_memories-v2.prompty); setAMT_EXTRACT_MEMORIES_PROMPT=extract_memories.promptyto fall back to v1. See PR:#37 - Procedural memory is now an atomic, retrievable skill and policy library.
ProceduralRecordstores individual procedures (behavioral policies, workflows, decision rules, tool-usage notes, recovery strategies) with scope, activation conditions, steps, status, and source provenance. See PR:#38 - The Durable Functions backend now runs episodic extraction, driven by the Cosmos DB change feed on a per-thread cadence set via
EPISODE_EVAL_EVERY_N(withEPISODE_IDLE_GAP_SECONDS,EPISODE_TOPIC_DRIFT,EPISODE_MAX_TURNS, andEPISODE_MIN_TURNSmirrored on the Functions side). See PR:#38 - New delete helpers on both clients:
delete_turn(),delete_thread_summary(),delete_user_summary(), and bulkdelete_thread()(removes a thread's turns and, by default, its summary; distilled facts, episodes, and procedures are left intact). See PR:#38
- The default fact-extraction cadence is now every 2 turns (
FACT_EXTRACTION_EVERY_N=2) instead of every turn, across the SDK, and the Functions deploy default. See PR:#38 add_cosmos()is renamed toupsert_memory()on both clients and the store; behavior is unchanged (write-or-replace by id). See PR:#38delete_cosmos()is renamed todelete_memory(). See PR:#38- Procedural memory has been reshaped:
ProceduralRecordis now an atomic procedure rather than a single compiled system-prompt document, and the compiled prompt is produced on demand bybuild_procedural_context(). Pre-existing single-prompt procedural documents from earlier betas are not migrated. See PR:#38 - Write-time vector deduplication (in-place fold) has been removed, along with the
DEDUP_VECTOR_ENABLEDand similarity-threshold knobs. Fact dedup is now in-batch hash plus deterministic-id create/409; contradiction reconciliation is unchanged. See PR:#38
- Episode extraction now isolates LLM failures: a transient error leaves the open segment un-stamped for retry, while a non-retryable error (content filter, context-length) quarantines the segment so it can neither wedge the thread nor grow it without bound. See PR:#37
- Out-of-range or non-numeric fact
salience/confidencevalues are clamped instead of aborting the whole extraction batch and stalling the fact watermark. See PR:#37 - Segment time bounds and the open-episode-segment loader now order turns chronologically by parsed timestamp, so mixed UTC offsets and tied timestamps no longer invert episode bounds or destabilize the deterministic episode id. See PR:#37
- Per-turn extraction watermarks are stamped with a single-field conditional patch, so concurrent fact and episode writers no longer clobber each other's watermark field. See PR:#38
parse_llm_jsonnow rejects a non-object JSON root with a typed error instead of letting it surface downstream as a misclassified transient failure. See PR:#37- Threshold environment values of
NaN/infare rejected instead of silently disabling the affected boundary. See PR:#37
- Fact hash-dedup no longer issues a per-extraction query to preload the user's existing fact hashes; exact duplicates are caught in-batch and by the deterministic-id create (409), reducing per-turn latency. See PR:#38
- Searchable summaries: the summaries container now carries a vector index, and
search_summaries()/search_cosmos(include_summaries=True)vector-search across a user's thread + user summaries. See PR:#34 - Agent-sourced facts: extraction can now capture the assistant's own actions and recommendations (not just user statements), tagged
source=agent/sys:agent-factso retrieval can include or exclude them. See PR:#31 - Event time on write:
add_cosmos(..., created_at=...)sets a memory's event time (falls back to ingestion time), enabling time-aware retrieval and temporal reasoning over backfilled conversations. See PR:#31 - Unified retrieval:
search_cosmos(include_turns=True)blends raw conversation turns into results alongside extracted memories. See PR:#31 DEDUP_VECTOR_ENABLEDis now an environment knob (defaultfalse= add-only) instead of a fixed internal constant. See PR:#31- Write-time in-place deduplication: near-duplicate memories fold into the existing record (same id, newer content) instead of creating a new doc. See PR:#26
- Reconciliation now resolves contradictions only, soft-deleting the loser with
superseded_by;get_memory_history()walks that chain. See PR:#26
- Fixed a re-extraction loop that re-extracted the whole conversation every cycle (turns were never stamped
extracted_atwhen vector dedup was on). See PR:#26
- Extraction prompt v3: named attribution (use real names, not a generic "the user", so multi-speaker turns don't blur), stronger temporal grounding (resolve relative dates against the turn's time, never the current clock), and meaning/completeness rules. See PR:#34
- Extraction now sees per-turn timestamps and resolves relative dates ("3 weeks ago") to absolute dates in the fact text (time-range filtering uses the memory's
created_at). See PR:#31 - Reworked the extraction prompt (anti-inference, preserve specifics, topic-grouped memories) and simplified the schema to
fact/episodicwith fixed fact categories. See PR:#26 - Token-bounded extraction batches with per-batch failure isolation; embedding inputs truncated to the model token budget. See PR:#26
- A custom user-agent can now be supplied via the new
user_agentconstructor argument onCosmosMemoryClientandAsyncCosmosMemoryClient. The toolkit's own user-agent (azsdk-python-cosmos-agent-memory/<version>) is always sent to Azure Cosmos DB so usage can be tracked; when a custom value is provided it is prefixed and the toolkit's user-agent is suffixed behind it ("<custom> <toolkit>"). See PR:#30 - Per-turn processing cadence can now be set in-process via the new
cadence_thresholdsconstructor argument onCosmosMemoryClientandAsyncCosmosMemoryClient, instead of only through environment variables. Pass a mapping keyed by the same names as the env vars (e.g.FACT_EXTRACTION_EVERY_N,DEDUP_EVERY_N,THREAD_SUMMARY_EVERY_N,USER_SUMMARY_EVERY_N); any key not present falls back to the environment/defaults, andNonepreserves today's env-only behavior. See PR:#29
- Embeddings and chat clients can now be injected via the new
embeddings_clientandchat_clientconstructor arguments onCosmosMemoryClientandAsyncCosmosMemoryClient. See PR:#27
- Raw conversation turns can now be embedded and vector-searched. Set
enable_turn_embeddings=True(envENABLE_TURN_EMBEDDINGS) to generate an embedding when each turn is written, then callsearch_turns()(sync and async, on both the client and store) to semantically search the raw turn log. See PR:#22
- The memories container's vector index type is now configurable instead of being hard-coded to
diskANN. Set it via thevector_index_typeargument tocreate_memory_store(...)or theAI_FOUNDRY_EMBEDDING_VECTOR_INDEX_TYPEenvironment variable. See PR:#24 ai_foundry_endpointnow accepts a project-scoped Azure AI Foundry URL (https://<resource>.services.ai.azure.com/api/projects/<name>) in addition to the account-level inference endpoint. See PR:#23
- Hardened memory extraction: stops emitting phantom/synthesized facts the user never asserted, stops extracting facts from
[assistant]:turns, stops re-processing already-extracted turns (which previously produced reversedCONTRADICTdecisions and meta-facts like"X is contradicted by Y"), and stops storing near-duplicate episodic memories for the same scope. Episodic memories also now embed the actual content instead of a boilerplate"intent recorded"string. See PR:#20 - Fixed
add_cosmos+process_nowsilently bypassing the cadence subsystem: cadence env vars (THREAD_SUMMARY_EVERY_N,FACT_EXTRACTION_EVERY_N,USER_SUMMARY_EVERY_N, etc.) had no effect, and procedural / user-summary synthesis never ran.add_cosmosnow triggers cadence on turn writes;process_nownow runs the full 5-step pipeline on the in-process processor.See PR:#20
ProcessThreadResultgainsproceduralanduser_summaryfields.extract_memoriesreturns adropped_episodic_countfor monitoring LLM-extraction quality.See PR:#20
Initial public preview release.
This is a beta release. The public surface may evolve in backward-incompatible ways before the 1.0.0 general-availability cut.
Pin a specific version when integrating.
- Sync (
CosmosMemoryClient) and async (AsyncCosmosMemoryClient) clients for storing, retrieving, and transforming agent memories backed by Azure Cosmos DB. - Typed memory record hierarchy (Pydantic):
TurnRecord,FactRecord,EpisodicRecord,ProceduralRecord,ThreadSummaryRecord,UserSummaryRecord. - Vector + full-text + hybrid search over memories with metadata filters, tag filters, and per-type scoping.
- Built-in memory processing pipeline: fact extraction, thread/user summarization, procedural-memory synthesis, contradiction handling, and deduplication - all driven by versioned
.promptyprompts. - Two processor backends:
InProcessProcessor(default, runs in your application process) andDurableFunctionProcessor(offloads work to a sibling Azure Function app via Cosmos DB change feed). - One-command
azd updeployment that provisions Cosmos DB (with vector + full-text search enabled), Azure AI Foundry (chat + embedding deployments), Azure Function app (Flex Consumption), Storage, App Insights, and the User-Assigned Managed Identity wiring all of it together. - Focused exception hierarchy:
AgentMemoryError,ConfigurationError,ValidationError,CosmosNotConnectedError,CosmosOperationError,MemoryNotFoundError,MemoryTypeMismatchError,LLMError. - Structured JSON logging via
azure.cosmos.agent_memory.logging(configure_logging,JsonFormatter).
- Distribution name:
azure-cosmos-agent-memory(PyPI) - Import path:
azure.cosmos.agent_memory