Choose an AI Agent Memory Architecture

The right memory layer depends on the job. A single local operator may need readable files. A shared production system may need transactional records. Semantic retrieval is useful for discovery, but it should not silently become the source of truth.

The four practical patterns

Versioned files

Use Markdown for human-readable policy, decisions, and summaries; use JSON or YAML for structured state. Files are strong when one operator or a small team needs transparent diffs, simple backups, and deliberate curation. They weaken under concurrent writes, large corpora, and complex access control.

Transactional database

Use a database when several processes update shared state, exact filters matter, and a transaction must not partly succeed. Store stable IDs, observation time, source, owner, status, and correction history. The database answers “what is the current record?” better than a pile of summaries.

Retrieval index

Embeddings help locate semantically related material that does not share exact words. They do not guarantee truth, freshness, authority, or permission. Preserve the source record and require retrieved context to cite it. Rebuild or invalidate the index when sources change.

Hybrid memory

Use files or a database as canonical truth, an append-only event log for what happened, and a retrieval index for discovery. The agent retrieves candidates, then resolves current state from the canonical record before acting. This costs more to operate but is usually the safest pattern for shared, growing systems.

Separate five memory jobs

1. Identity and policy: stable instructions, mandate, hard stops, and escalation rules.
2. Current state: active customer, task, configuration, and workflow status.
3. Event history: append-only observations and actions with timestamps.
4. Derived knowledge: summaries, hypotheses, patterns, and forecasts that can be corrected.
5. Retrieval index: pointers that help find records but do not replace them.

Combining these jobs in one ever-growing prompt makes stale facts hard to detect and permissions hard to enforce.

Minimum record contract

Every durable memory record should carry an ID, type, source, observed-at time, created-at time, owner, sensitivity, confidence or verification status, supersedes/superseded-by links, and a last-reviewed time. A correction creates history; it does not invisibly rewrite the past.

The action boundary

Memory is context, not authorization. A record saying “the founder approved refunds” should not give an agent permanent refund authority. The current permission manifest, action value, reversibility, and approval state still decide whether the agent may act.