ContextDB
Menu

Home / Memory management for AI agents / AI agent memory architecture

Architecture field guide

By Gaurav Sharma · Reviewed

AI agent memory architecture

An AI agent memory architecture connects sources and authenticated scope to formation, canonical versioned records, derived indexes, authorized retrieval, context assembly, and the agent runtime. Action policy evaluates proposed tool calls, while the customer host and systems of record own authorization and business state. Audit and evaluation observe the path. Each boundary needs a named contract because no single topology fits every workload.

For the wider lifecycle, read the architecture chapter in the full memory guide.

Memory guide topics
On this page

Design contract

What must the architecture define before storage?

Before choosing storage, define the workload, authenticated identities, source authority, permitted actions, authoritative business state, retention and erasure duties, named consistency guarantee, latency budget, and failure behavior. These contracts determine which records, indexes, queues, and hosts are needed. A database choice cannot repair an undefined authority or retry boundary, and different workloads can justify different layouts.

  • Workload: Name the questions, writes, delayed tasks, and proposed side effects.
  • Identity: Derive actor, subject, tenant, project, agent, session, and source scope.
  • Source authority: Record who supplied each claim and which system can correct it.
  • Actions: Separate a model-proposed tool call from host authorization and execution.
  • Business state: Declare the system of record for each mutable operational object.
  • Retention: Set availability periods for canonical data, derivatives, logs, and backups.
  • Erasure: Name covered surfaces, propagation owners, deadlines, and verification checks.
  • Consistency: State partition, version, index, session, and stale-read behavior.
  • Latency: Allocate time for scope resolution, retrieval, hydration, assembly, and fallback.
  • Failure: Define responses for lag, conflict, dependency loss, and ambiguous commit outcomes.

Reference flow

What belongs in an AI agent memory architecture?

The architecture needs an owned path through source admission, identity, formation, canonical records, indexes, retrieval, context, and runtime. Proposed actions need a separate policy and host path. Audit and evaluation cross every stage. This reference decomposition is not a required topology, and business systems remain authoritative for mutable state.

Memory roles affect schemas and retrieval triggers, not store count. Classify them in the memory roles guide.

Illustration This guide-created architecture is not a standard. A01 informs its modular memory and action framing without prescribing this topology A01.

Sequence in reading order

  1. Sources → authenticated scope → formation policy → canonical records.
  2. Canonical records → derived indexes → authorized retrieval → context assembly.
  3. Context assembly → agent runtime → proposed tool call → policy decision.
  4. Policy decision → customer host → system of record → reported receipt.
  5. Audit and evaluation span every path. Sources and indexes are parallel choices.

Boundary ownership

  1. Sources cover conversation, events, tools, documents, and systems.
  2. Identity resolves actor, subject, tenant, project, agent, session, and source.
  3. Formation policy owns admission, extraction, normalization, source binding, and writes.
  4. Canonical storage owns IDs, versions, time, and provenance.
  5. Index workers maintain structured, temporal, lexical, vector, entity, or graph paths.
  6. Retrieval services own authorization, fusion, hydration, and context budgets.
  7. The runtime owns working state, answers, and proposed calls.
  8. Policy and host code separate decisions, enforcement, live state, and execution.
  9. Business systems own mutable objects and accepted effects.
  10. Assurance owners retain audits, traces, evaluations, and erasure evidence.

Scope and host enforcement are trust boundaries covered in the memory security guide. Audit points support tests in the memory evaluation guide. A tool call remains a proposal until the host authenticates, authorizes, checks live state, and applies business rules.

External research W3C PROV-DM is a W3C Recommendation for lineage relations A02, not source truth. PAMSPEC -00 is an individual Internet-Draft and work in progress illustrating an emerging proposal A12, not an IETF standard.

External research Living vendor documentation illustrates LangGraph checkpoint and store patterns A13 and one managed AWS AgentCore design A14. Neither defines a neutral requirement.

Records and access paths

How should records and indexes differ?

A canonical memory record governs lifecycle identity, versions, source, time, status, retention, and authority metadata. An index finds candidates through a declared access method, then returns pointers for canonical hydration. Canonical does not mean objectively true or authoritative for business state. Indexes are rebuildable projections by default, though a design may declare a graph canonical.

Illustration Canonical-record and index responsibility matrix
Question Canonical memory record Memory index
Primary job Govern object lifecycle and the current version. Find object IDs by declared field, keyword, time, vector, entity, or relation.
Identity and time Stable object and version IDs, valid time, record time, and provenance. Pointers, indexed fields, build version, and scope watermark.
Authority Governs memory-service status under the declared contract. Scores and edges do not create authority.
Update Compare-and-set, supersession, contest, retention, or deletion changes state. A worker applies changes and advances its watermark.
Read Hydrates current, historical, or conflicting versions. Returns bounded candidates under scope filters.
Graph boundary A declared canonical graph preserves source, identity, time, and update semantics. Otherwise, graph nodes and edges are lagging, rebuildable views.

Storage patterns follow the contract

A design may pair canonical records with parallel indexes, materialize a canonical view from source events, declare graph relations canonical, or keep source artifacts in object storage. Each pattern still needs version, lineage, lag, and erasure rules.

External research A peer-reviewed article distinguishes valid time from transaction time A03. A published SIGMOD Record industry article describes SQL:2011 application-time and system-versioned features A04. Both motivate explicit time without requiring SQL.

External research Peer-reviewed ACL papers illustrate APEX-MEM's append-only temporal design with entity resolution A10 and MAGMA's semantic, temporal, causal, and entity graph views A11. Neither makes a graph canonical by default.

Read path

How should retrieval become model context?

Retrieval should resolve authenticated scope, apply authorization and lifecycle filters, gather candidates from declared access paths, hydrate canonical records, expose conflicts, and assemble a bounded context pack. Context assembly means selecting, deduplicating, ordering, labeling, and budgeting evidence before a model call. It cannot guarantee a correct answer or turn untrusted memory into instructions.

  1. Classify the request. Name the subject, task, time basis, required fields, and version floor.
  2. Resolve scope. Derive actor and tenant authority from authenticated server context.
  3. Filter before retrieval. Apply authorization before candidate generation where the store permits it.
  4. Query declared access paths. Structured, temporal, lexical, vector, entity, and graph lookups may run in parallel when their scope semantics match.
  5. Fuse and hydrate. Deduplicate object IDs, fetch canonical versions, and reject missing references.
  6. Apply validity rules. Filter superseded, expired, deleted, or out-of-scope items and expose unresolved conflicts.
  7. Assemble context. Preserve source labels, separate evidence from instructions, order deliberately, and enforce a budget.
  8. Call the model. Pass the context pack with current task state, not retrieval scores as authority.

External research LongMemEval separates indexing, retrieval, and reading in its evaluation setup A08. Lost in the Middle reports position sensitivity in its published tasks A09. Neither result dictates a production context order for every model or workload.

Write and retry contracts

What consistency and retry contracts are required?

Required contracts name scope and guarantees for reads, writes, indexes, sessions, conflicts, duplicate events, retries, and ambiguous outcomes. Read-your-writes applies within a partition. A version floor sets the oldest acceptable commit, while a watermark states index progress. Idempotency means one logical effect under a key contract, not exactly-once infrastructure.

Illustration Named consistency and idempotency contracts
Contract Required rule Declared failure result
Read-your-writes A later partition read sees the acknowledged canonical version. Wait, route to an eligible store, or return unavailable.
Version floor A read requiring version 42 cannot satisfy the request with version 41. Canonical lookup satisfies lag only for an identified object with a declared path. It cannot replace semantic candidate generation. Otherwise wait or return unavailable.
Index watermark Each index reports its highest processed scoped commit. Expose lag rather than treating a stale projection as current.
Monotonic reads A session does not move below an observed version when required. Return a named stale-session or unavailable response.
Compare-and-set An update supplies the expected version before a successor. A version mismatch returns conflict without mutation.
Duplicate source event Source plus event ID identifies a replay and binds its payload. Return the prior outcome, or conflict if the payload differs.
Retry key Define tenant, operation, resource, payload equality, expiry, concurrency, and lookup. A reused key with a different payload returns conflict.
Ambiguous outcome After response loss, look up the operation before retrying. Return committed, in progress, failed, or unknown without blind re-execution.

External research A peer-reviewed PDIS paper supports read-your-writes and monotonic reads A06. CloudEvents 1.0.2 is a stable CNCF specification whose source and event ID support duplicate recognition A07. It does not define memory retry-key behavior.

External research RFC 9110, an IETF Internet Standard, defines method idempotency for repeated identical requests A05. Retry-key and ambiguous-result behavior remain application contracts.

Synthetic correction trace

Cold-chain correction during index lag

Illustration Every identifier, version, timestamp, temperature, decision, and outcome is synthetic. The 6.2 C reading and 4.8 C correction explain contracts and are not safety guidance.

Sequence in reading order

  1. Authenticated sensor sensor-D7-04 emits event E-771 for pallet P-204 at 6.2 C and event time 2026-08-28T09:14:22Z.
  2. The resolver binds the authenticated sensor to depot D7 and pallet P-204. Caller text does not set that scope.
  3. The same source event arrives twice at receipt times 2026-08-28T09:14:29Z and 2026-08-28T09:14:34Z. Source plus event ID identifies the replay.
  4. Canonical version 41 records the reading, event and receipt times, source, calibration reference CAL-D7-118, and unverified status.
  5. Late event E-772 applies calibration reference CAL-D7-119. Version 42 records 4.8 C and supersedes version 41 as current.
  6. Temporal and vector index watermarks remain 41 after the canonical store commits version 42.
  7. A dispatcher asks whether pallet P-204 may leave depot D7 and requires version floor 42. The request identifies the object and the design declares its canonical lookup path, so that lookup may satisfy the floor during index lag. It cannot replace semantic candidate generation. Without both conditions, the path waits within its bound or returns unavailable.
  8. Context assembly excludes version 41 as current. It may retain it as historical evidence, then passes the result to the runtime.
  9. The runtime may propose hold, release, or recheck. The customer host authenticates the actor, checks policy, live state, and handling rules, then asks the warehouse system to apply an accepted side effect.
  10. The warehouse system remains authoritative for dispatch state. Memory stores the host-reported result, assurance records the trace, and the index worker advances to 42.

Bounded product mapping

Current ContextDB mapping

Current ContextDB behavior

Checked against repository snapshot d59c1b9 on August 28, 2026. The pinned Apache SDK is Available, the Cloud gateway is Alpha, and asynchronous Formation is Hosted Alpha.

Current read boundary
Factual evolution returns version and primary write-position data. Token-bearing reads are primary-bound by default. Both configured pools point to the primary.
Current operating boundary
The hosted gateway and Formation process are single-instance and have no service-level agreement. This snapshot does not establish a deployed read replica, worker fleet, high availability, or the full neutral architecture shown in this guide.

Architecture FAQ

Questions about agent memory architecture

What is the canonical record in an agent memory system?

A canonical record is the memory service's lifecycle record for a stable object. It carries version identity, source, valid time, record time, status, retention, and authority metadata. The service uses it to govern memory state. Canonical does not mean objectively true or authoritative for mutable business state.

How should reads behave while a memory index lags?

Compare the requested version floor with the index watermark. A canonical lookup can satisfy lag only when the request identifies the object and a declared canonical path exists. It cannot replace semantic candidate generation. Without both conditions, wait within the bound or return unavailable. Never present a stale candidate as satisfying the floor.

When should memory formation run asynchronously?

Asynchronous formation fits sources arriving after the response, extraction beyond the request budget, or candidates needing quarantine before commit. It adds queues, retries, ordering, and lag. Keep formation synchronous when the next operation requires committed memory and the system can meet that write contract within the request.

What must an idempotency contract define?

An idempotency contract defines key namespace, operation and resource scope, payload comparison, expiry, concurrency, conflict response, result lookup, and post-commit response loss. Replaying the same logical operation should return its established outcome. Reusing a key with a different payload must return conflict without mutating state.

Where should an agent store delayed intentions?

Delayed intentions belong in durable workflow state with identity, trigger, status, owner, retry policy, cancellation, and completion. A retrieved reminder is not a scheduler. Memory may supply the intention and context, while a workflow engine or host owns wake-up, authorization, execution, and final outcome recording.

How should deletion propagate to derived indexes?

Follow lineage from the canonical record to lexical, vector, temporal, entity, and graph projections. Invalidate scoped caches and summaries. Each worker needs a deletion position or tombstone, retry behavior, and verification scan. Backup and provider deadlines need separate checks, so an index update cannot establish immediate erasure closure.

Source ledger

Primary sources and maturity

Each entry states the source's maturity and the boundary used here. A paper or product document can illustrate one design without establishing a standard architecture or a result for another workload.

  1. External research CoALA, Sumers et al., 2024. Peer-reviewed TMLR paper. Supports modular memory and action framing, not a required production topology.
  2. External research W3C PROV-DM. W3C Recommendation. Supports entity, activity, agent, generation, use, attribution, and derivation terms.
  3. External research Snodgrass and Ahn, 1986. Peer-reviewed IEEE Computer paper. Grounds valid-time and transaction-time distinctions.
  4. External research Kulkarni and Michels, 2012. Published SIGMOD Record industry article. Describes application-time and system-versioned temporal features in SQL:2011.
  5. External research HTTP Semantics, RFC 9110 section 9.2.2. IETF Internet Standard. Defines HTTP method idempotency for repeated identical requests, not application retry keys.
  6. External research Terry et al., 1994. Peer-reviewed PDIS paper. Supports named session guarantees, including read-your-writes and monotonic reads.
  7. External research CloudEvents 1.0.2. Stable CNCF specification. Supports source and event ID semantics for duplicate recognition, not memory idempotency.
  8. External research LongMemEval, Wu et al., 2025. Peer-reviewed ICLR paper. Separates indexing, retrieval, and reading in its evaluation setup.
  9. External research Lost in the Middle, Liu et al., 2024. Peer-reviewed TACL paper. Reports position sensitivity in its published tasks, not a universal context rule.
  10. External research APEX-MEM, Banerjee et al., 2026. Peer-reviewed ACL paper. Illustrates temporal records with entity resolution and graph views.
  11. External research MAGMA, Jiang et al., 2026. Peer-reviewed ACL paper. Illustrates semantic, temporal, causal, and entity graph views in the studied system.
  12. External research PAMSPEC -00. Individual Internet-Draft and work in progress. It is an emerging proposal, not an IETF standard or consensus.
  13. External research LangGraph persistence. Living vendor documentation. Illustrates current checkpoint and store patterns without defining a field standard.
  14. External research AWS AgentCore memory. Living vendor documentation. Illustrates one managed design without making its behavior a neutral requirement.

Trace one memory from source to host

Use the public API reference to compare source, scope, decision, and receipt objects with the neutral architecture.

Inspect the ContextDB API