This is a knowledge site about memory engineering for agentic software: how an agent keeps durable information (memory) and saved execution state (checkpoints), and why the two must not be confused. It starts from one request that forgets everything and climbs to memory kinds, stores, run identity, checkpoints, safe resume, the outbox, write policy, retrieval, shared memory, security and recovery tests, asking at each step: who wrote this down, and who is allowed to rely on it? It is written for engineers and architects who build agent systems.
One example runs through every page. An insurer receives a broker's request for a quote. An underwriting agent reads it, checks the roof, looks up the guidance and writes a recommendation. A human underwriter decides. The model recommends; a person decides.
What it is and is not#
| It is | It is not |
|---|---|
| A ladder: one idea per step, each word in plain English with a tiny example before it is used | A standard, or the only way to design agent memory |
One running example, twelve cases UW-M01 to UW-M12, built on the series cases UW-001 to UW-010 | A record of any real insurer. The cases, rules, fields, provider and tables are invented |
| A demonstration of mechanism: checkpoints, idempotent writes, the outbox, a write policy, a scope filter | A measurement of any model or product. No page reports how good a real system is |
| Code that was run: standard-library Python with SQLite, with its real output pasted | A framework to install. It is short so it can be read whole, and it leaves things out |
| Tools described from their own documentation, by what each one stores for you | A ranking or a buying guide. No tool is called best, and no price is quoted |
What is original here and what is not#
| Part | Status |
|---|---|
| Working, episodic, semantic and procedural memory | The four kinds named in the CoALA paper, "Cognitive Architectures for Language Agents" (2023), used with its meanings |
| Preference memory as a fifth kind | Added by this site, because its owner and lifetime differ from the other four |
| The two sentences "Memory is information retained for future use. A checkpoint is saved execution state that allows a workflow to resume." | This site's framing of a distinction that workflow engines and agent libraries draw in their own words |
| Idempotency keys, at-least-once delivery, the transactional outbox, inbox tables, sagas, optimistic locking, event sourcing | Established distributed-systems patterns, explained here on the example |
| One trace per attempt, joined by the run id | A design choice of this site, stated on Run identity |
| The source-type confidence table, the ranking weights, the retention numbers | Designs proposed on this site, all illustrative |
| The twelve cases, the policy fixture, the seed memories | Written for this site. All synthetic |
| The example code, its tests, the labs and the diagrams | Written for this site |
Where a page takes an idea from a source, the page says so. Where this site proposes something, it calls it a design.
How the facts were checked#
| Kind of claim | How it was checked |
|---|---|
| A named product, protocol or standard | Read on its own documentation on 2026-11-17 and logged with the page address and the date, one log per page in the repository's docs/facts/. Where the documentation is silent, the page says so. Statements about frameworks live on Frameworks; statements about Claude Code live on Files |
| The example | Run. Every command shown from examples/uw-memory/ was executed in a scratch copy, and the output on the page is the output it printed. The folder has 32 unit tests |
| The labs | They read data generated from the example. Their arithmetic is a second implementation of the Python functions, and a test fails if the two differ |
| Numbers | Synthetic and illustrative unless a source is linked. A number from the example is the result of a script, never a measurement of a model |
| Other code | A block that was not run says how far it was checked, for example "documented shape; not run here" |
| Links and structure | A build step checks every internal link, every diagram and every glossary reference before the site is published |
Documentation changes. Treat every statement about a tool as true on the day it was read, and read the tool's page again before you build on it.
What the example does not show#
The insurance example is an illustrative reconstruction for teaching. It follows the shape of a real project by the author, but the cases, the rules, the fields, the provider, the tables and every number are invented. Nothing here reports the behavior of a real system or model.
The agent here is a scripted stand-in, so these results show how the mechanism works, not how good any model is.
| In the example | What it really is |
|---|---|
| The underwriting agent | A script with fixed answers per case. No model is called. There is no network and no key |
| The roof-data provider | A stand-in that returns what the case file says, counts its calls, and can time out on purpose |
| The store | One SQLite database file, part of Python's standard library |
| The crash | An exception raised at a named point, exactly where a real process would stop |
| The underwriter cockpit | A small class that accepts messages and ignores repeats |
| Relevance in ranking | Word overlap, a stand-in for embedding similarity |
| Times and ids | A fixed clock and ids derived from fixed seeds, so every reader sees the same run |
Sources and reading list#
Each link below was opened on 2026-11-17.
Ideas#
| Source | Why read it |
|---|---|
| Cognitive Architectures for Language Agents, Sumers, Yao, Narasimhan and Griffiths, 2023 | The taxonomy of memory kinds this site uses. Depth for Memory kinds |
| The Idempotency-Key HTTP Header Field, IETF Internet-Draft | A standard in progress for the idempotency key of Failure and resume |
| W3C Trace Context | The format of trace and span ids. Depth for Run identity |
Databases#
| Source | Why read it |
|---|---|
| PostgreSQL: transaction isolation | The isolation levels on Shared memory |
| PostgreSQL: JSON types and SQLite: JSON functions | JSON columns on Stores |
| PostgreSQL: row security policies | Tenant separation in the data layer on Security |
Security and regulation#
| Source | Why read it |
|---|---|
| GDPR Article 17, the right to erasure (text read via gdpr-info.eu because the official page did not load for the fetch tool) | Erasure on Security |
| OWASP LLM04:2025 Data and Model Poisoning | The poisoning risk that this site's memory poisoning applies to a memory store |
| AWS Well-Architected: disaster recovery objectives | Recovery point and recovery time on Advanced |
Tool documentation#
These are entry pages of each tool's own documentation. What each one stores for you is described on Frameworks, and only there; Claude Code on Files.
| Tool | Documentation |
|---|---|
| LangGraph persistence | docs.langchain.com/oss/python/langgraph/persistence |
| Temporal | docs.temporal.io/workflow-execution |
| DBOS | docs.dbos.dev/architecture |
| AWS Step Functions | docs.aws.amazon.com/step-functions/latest/dg/welcome.html |
| Claude memory tool | platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool |
| Mem0 | docs.mem0.ai/overview |
| pgvector | github.com/pgvector/pgvector |
| OpenTelemetry | opentelemetry.io/docs/specs/otel |
| Claude Code memory and checkpointing | code.claude.com/docs/en/memory, code.claude.com/docs/en/checkpointing |
Sister sites#
This site is one of a series on engineering agentic software. Each site answers one question, and none repeats a chapter of another. The ten sites of the series:
| Site | The question it answers |
|---|---|
| Prompt Engineering | How are instructions written, composed, ranked and versioned? |
| Context Engineering | What can the model see now, and how is that working set chosen? |
| Memory Engineering, this site | What is kept after a call and a process end: durable information, and saved execution state? |
| Agent Communication | How do agents send each other messages, and how does A2A differ from MCP? |
| Observability Engineering | What is the evidence of what happened: logs, metrics, traces, audit events? |
| Guardrails Engineering | Which enforceable checks surround a probabilistic agent? |
| Tools Engineering | How are callable capabilities defined, executed and exposed? |
| Structured Output Engineering | How are typed contracts shaped, validated, repaired and evolved? |
| Agent Orchestration | What runs next, under which condition? |
| Agent Reliability | How do outcomes stay acceptable despite failures, retries and load? |
Published earlier, in the same voice: Harness Engineering on the runtime around a model call, Eval Engineering on measuring what an agent does, and Diff to Deploy on shipping a change with coding agents.
Who wrote it#
Sam Muthu, an engineer and architect who builds agent systems and holds Anthropic's Claude Certified Architect credentials (Foundations and Professional). More of his work is at sammuthu.com.
The site is a working version. If a claim is wrong or out of date, the fix is to read the source again and correct the sentence. Every term the pages use is collected in the Glossary.