All chapters
  1. Start hereMemory is what you keep. A checkpoint is where you stopped
  2. Memory · 1The stateless request: why anything has to be stored at all
  3. Memory · 2Five kinds of memory: working, episodic, semantic, procedural and preference
  4. Memory · 3Conversation history, summaries, retrieval and durable facts
  5. Memory · 4Files as memory in coding agents: instructions, journals, artifacts and checkpoints
  6. Memory · 5Database stores: tables, JSON, documents, objects and vectors
  7. State · 6Run identity: run_id, thread_id, trace_id, correlation_id and task_id
  8. State · 7State machines, checkpoints, event sourcing and where replay must stop
  9. State · 8Failure and resume: idempotency keys, retry policy and the exactly-once illusion
  10. State · 9The transactional outbox: side effects, compensation and deduplication
  11. Policy · 10Memory write policy: extraction, confidence, provenance, expiry and deletion
  12. Policy · 11Retrieval and ranking: relevance, recency, salience and scope
  13. Policy · 12Shared memory between agents: consistency, isolation, ownership and races
  14. Policy · 13Security: tenant separation, personal data, secrets, consent and retention
  15. Practice · 14Evaluation: memory correctness, stale facts, contamination and recovery tests
  16. Practice · 15Frameworks and standards: what each one stores for you
  17. Practice · 16The insurance lab: one run that fails, resumes and remembers, end to end
  18. Practice · 17Advanced: migration, conflict resolution, forgetting, summary drift and disaster recovery
  19. ReferenceGlossary
  20. AboutAbout this site and its sources
About

About this site and its sources

What this site is, what it is not, the sister sites in the series, where its ideas come from, and how the facts were checked.

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 isIt is not
A ladder: one idea per step, each word in plain English with a tiny example before it is usedA 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-010A 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 filterA 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 pastedA 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 youA ranking or a buying guide. No tool is called best, and no price is quoted

What is original here and what is not#

PartStatus
Working, episodic, semantic and procedural memoryThe four kinds named in the CoALA paper, "Cognitive Architectures for Language Agents" (2023), used with its meanings
Preference memory as a fifth kindAdded 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 sourcingEstablished distributed-systems patterns, explained here on the example
One trace per attempt, joined by the run idA design choice of this site, stated on Run identity
The source-type confidence table, the ranking weights, the retention numbersDesigns proposed on this site, all illustrative
The twelve cases, the policy fixture, the seed memoriesWritten for this site. All synthetic
The example code, its tests, the labs and the diagramsWritten 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 claimHow it was checked
A named product, protocol or standardRead 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 exampleRun. 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 labsThey read data generated from the example. Their arithmetic is a second implementation of the Python functions, and a test fails if the two differ
NumbersSynthetic 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 codeA block that was not run says how far it was checked, for example "documented shape; not run here"
Links and structureA 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 exampleWhat it really is
The underwriting agentA script with fixed answers per case. No model is called. There is no network and no key
The roof-data providerA stand-in that returns what the case file says, counts its calls, and can time out on purpose
The storeOne SQLite database file, part of Python's standard library
The crashAn exception raised at a named point, exactly where a real process would stop
The underwriter cockpitA small class that accepts messages and ignores repeats
Relevance in rankingWord overlap, a stand-in for embedding similarity
Times and idsA 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#

SourceWhy read it
Cognitive Architectures for Language Agents, Sumers, Yao, Narasimhan and Griffiths, 2023The taxonomy of memory kinds this site uses. Depth for Memory kinds
The Idempotency-Key HTTP Header Field, IETF Internet-DraftA standard in progress for the idempotency key of Failure and resume
W3C Trace ContextThe format of trace and span ids. Depth for Run identity

Databases#

SourceWhy read it
PostgreSQL: transaction isolationThe isolation levels on Shared memory
PostgreSQL: JSON types and SQLite: JSON functionsJSON columns on Stores
PostgreSQL: row security policiesTenant separation in the data layer on Security

Security and regulation#

SourceWhy 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 PoisoningThe poisoning risk that this site's memory poisoning applies to a memory store
AWS Well-Architected: disaster recovery objectivesRecovery 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.

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:

SiteThe question it answers
Prompt EngineeringHow are instructions written, composed, ranked and versioned?
Context EngineeringWhat can the model see now, and how is that working set chosen?
Memory Engineering, this siteWhat is kept after a call and a process end: durable information, and saved execution state?
Agent CommunicationHow do agents send each other messages, and how does A2A differ from MCP?
Observability EngineeringWhat is the evidence of what happened: logs, metrics, traces, audit events?
Guardrails EngineeringWhich enforceable checks surround a probabilistic agent?
Tools EngineeringHow are callable capabilities defined, executed and exposed?
Structured Output EngineeringHow are typed contracts shaped, validated, repaired and evolved?
Agent OrchestrationWhat runs next, under which condition?
Agent ReliabilityHow 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.