The AI Agent Memory Playbook
Durable agent memory is not a bigger prompt. It is a system for deciding what becomes a record, which record is current, how corrections work, what retrieval may see, and how an agent proves the context it used.
Rick uses files, receipts, decision records, and explicit corrections because autonomous work needs an audit trail. This public playbook turns those principles into three practical resources. It does not claim a benchmark result until a fixed corpus and task set have been run and published.
Start with the job, not a database
Write down the memory-dependent decision in one sentence. Examples:
- retrieve the current product price and cite its approved source;
- remember a customer’s active plan without exposing another customer’s data;
- distinguish a historical revenue receipt from current revenue;
- recall the last failed installation check and propose the smallest repair;
- preserve a founder decision while recording that it was later reversed.
If the task does not require durable state, do not add a memory system. If exact filters solve it, do not begin with embeddings. If an action requires current approval, do not treat remembered precedent as authorization.
The memory stack
| Layer | Job | Safe default |
|---|---|---|
| Policy and identity | Stable mandate, limits, escalation | Versioned human-readable files with explicit owner |
| Current state | What is true now | Structured record with stable ID and updated-at time |
| Event history | What happened | Append-only events with observed-at time and source |
| Derived knowledge | Summaries and hypotheses | Source-linked, correctable, never silently authoritative |
| Retrieval | Find candidate context | Index of pointers; permission-filtered before use |
| Evaluation | Prove behavior | Versioned tasks, expected answers, sources, and failure rules |
Three tools in this playbook
Architecture selector
Choose between versioned files, a transactional database, semantic retrieval, or a hybrid. The result explains what remains canonical and when semantic search is only a discovery layer.
Memory evaluation scorecard
Measure answer accuracy, source citation, and stale-memory use against a fixed task set. Critical privacy and permission tests remain individual release blockers even when the aggregate score passes.
Failure and recovery playbook
Diagnose stale facts, source-free summaries, duplicate records, prompt bloat, retrieval misses, privacy leakage, and remembered permission. Every recovery ends in a regression fixture.
A minimum durable record
{
"id": "decision_pricing_2026_09_01",
"type": "decision",
"subject": "product_price",
"value": {"currency": "USD", "amount": 47},
"source": "approved_offer_manifest",
"observed_at": "2026-09-01T12:00:00Z",
"status": "current",
"sensitivity": "public",
"owner": "product",
"supersedes": "decision_pricing_2026_07_01"
}
The shape matters more than the storage engine. Stable identity prevents duplicates. Observation time separates event truth from current truth. Source and owner make correction possible. Sensitivity creates a retrieval boundary. Supersession preserves history without letting an old record masquerade as current.
What this playbook refuses
- “Unlimited memory” claims without a task and corpus.
- Knowledge-graph claims based only on folders or Markdown links.
- Benchmark numbers without a reproducible method and limitations.
- Embedding secrets, credentials, or unrestricted customer data.
- Silent rewriting of prior records after a correction.
- Letting retrieved context grant external authority.
Release gates
A memory-dependent agent should not move into higher-impact actions until it can retrieve current state, cite the supporting record, abstain when evidence is absent, respect tenant/sensitivity filters, handle superseded facts, and pass a versioned regression set. Latency and cost also need explicit budgets, but neither can compensate for a privacy or permission failure.
This hub is the canonical owner for memory architecture and evaluation. General agent templates belong to the Autonomous Agents Starter Kit; runtime release status and preflight belong to the Rick Self-Hosted Release.