Chapter 4: Memory: What your agent remembers shapes what it becomes
The introduction defines agent memory as a policy for carrying information across boundaries, using a decision ledger to show why stored history must be separated from current authority.
After this chapter you will be able to
- Decision history and current authority. Explain why a superseded decision should remain in the record without continuing to guide execution, and how the ledger distinguishes history from the current accepted decision.
- Memory as boundary policy. Describe agent memory as a policy for what information survives boundaries, rather than simply a store of conversations or documents.
- Persistence versus admitted learning. Distinguish a stored trace or proposed lesson from information validated for reuse, and state where current operational authority resides.
- Memory and two selection points. Explain that memory preserves selected information for a later decision, with selection both when information is retained and when it returns to active context.
- State and evidence responsibilities. Distinguish state persistence, which keeps what is needed to resume interrupted work, from evidence retrieval, which finds current, permitted, relevant material outside the active context.
- Experience capture and admission. Explain why preserving failure facts and proposed lessons does not, by itself, authorize their use in a later task.
- Multiple dimensions of agent memory. Explain why an engineering memory hierarchy needs dimensions beyond the three-tier analogy, including scope, function, access, lifetime, and authority.
- Access cost versus authority. Explain why moving information nearer the model affects availability and token cost but does not make it more authoritative, and describe the checks retained for each tier.
- Selective memory lifecycle. Describe the operations selected information may pass through and explain that a memory design implements only the operations it needs.
- Superseding team decisions. Distinguish superseding an older decision from forgetting it, and describe what memory and the control plane each provide in the game-team example.
- Persistent context authority. Distinguish context supplied to an agent from rules that are enforced, using Claude Code’s instruction files and auto memory as examples.
- Dedicated memory layer choice. Justify when to rely on existing authoritative sources and when to add a dedicated memory layer.
- Decision-based retrieval utility. Explain why memory quality is judged by decisions after retrieval rather than store size, and describe how to check whether retrieved items were cited, verified, or changed an action.
- Baseline and boundary tracing. Describe how to set memory-quality thresholds and trace one item from its source to a later decision to find the first broken boundary.
- Tier policies and transitions. Explain that Hierarchical Retention assigns information to tiers by scope, function, access, and lifetime, with policies for which sources enter and when information is promoted, evicted, invalidated, or superseded.
- Authority over memory popularity. Distinguish frequently used or inferred preferences from authoritative human-owned rules, and explain why candidate memories must not automatically become active instructions.
- Retention tiers and transition rules. Explain that the teaching implementation uses three storage tiers with configurable promotion and eviction rules, while a production design can use different tiers if ownership and supersession remain explicit. Describe how scope, function, access, ownership, and admission shape what a stored item may become and when it may return, and why the table’s transition policies are examples to calibrate rather than universal defaults.
- Model-written memory status. Explain that auto memory can preserve project notes across sessions for continuity, but those notes remain candidate context rather than a path for silently changing managed policies or human-owned rules.
- Source scope and provenance. Describe why organization, user, project, local, rule, and auto-memory sources should remain distinguishable: they have different owners and sharing boundaries, which matter for provenance and resolving conflicts.
- Context versus enforceable rules. Distinguish CLAUDE.md and auto-memory content, which shape choices as model context, from managed settings, sandbox restrictions, and hooks, which are appropriate for rules that must not be bypassed. Explain why inferred notes may be revised or retired automatically while hard rules require their human owner.
- Durable Memory Promotion. Describe how retrieval moves an entry from durable memory into working context, and distinguish the example's use of vector-search relevance for eviction priority from a judgment of validity or authority.
- Configurable Memory Eviction. Explain how the teaching implementation combines importance, recency, and access frequency to enforce a memory budget, and why its settings must be calibrated to the workload.
- Governed Memory Boundaries. Distinguish the teaching model's recorded fields from the additional controls a production entry needs, and explain why human-owned rules and model reflections should not be automatically demoted or admitted as authoritative memory.
- Evidence-preserving memory eviction. Explain why the example retains the error trace while allowing reproducible output to be regenerated, and describe how to judge whether the eviction policy works.
- Argus review memory integration. Explain that Argus uses HierarchicalMemory to store review findings for retrieval in later sessions, and distinguish this integration from memory governance it does not yet implement.
- Authority over retained memory. Explain why retained entries cannot establish correctness on their own and how to ground a high-risk decision in an authoritative source.
- Two paths of RAG. Describe how a write or compile path prepares sources and indexes, while a read or assemble path retrieves an evidence package for a particular decision.
- Decision-specific evidence requirements. Explain why retrieved evidence must account for source authority, permissions, versions, and the possibility that the agent should abstain, rather than merely match similar text.
- Compile and assemble paths. Distinguish the compile path’s preparation of a governed corpus from the assemble path’s retrieval and packaging of cited evidence. State that the teaching listing implements only part of this broader contract.
- Agentic retrieval tradeoff. Explain what the model can decide in the agentic RAG example and why an exact-key task may instead favor deterministic lookup.
- Repository as retrieval structure. Explain how Claude Code uses Grep, Glob, Read, and web tools to retrieve repository information while the model selects and refines queries, without requiring a separate memory product.
- Retrieved evidence provenance. Explain why reading the current working tree does not guarantee complete or authoritative evidence, and why an evidence package should name the source and version actually read.
- Source-matched retrieval methods. Describe how the retrieval approach should vary with the source: direct lookup for exact identifiers, lexical or semantic search for prose, structural or dependency-aware search for code, and temporal or provenance filters for decisions and incidents.
- Reciprocal Rank Fusion Scoring. Explain how RRF merges search-result rankings when their raw scores cannot be compared directly.
- Hybrid Search Recall Tradeoff. Explain why combining semantic and keyword search may improve recall, and why that improvement must be measured for the task and corpus.
- Silent retrieval failures. Explain how a retrieved package can look relevant yet omit a controlling source, and describe the retrieval conditions that can cause this.
- Retrieval suitability and evaluation. Describe when RAG is worth using and how to compare candidate pipelines against the cost and risk of retrieval.
- Resumable checkpoint contract. Explain when Progress Tracking is useful and what a checkpoint must preserve for work to resume rather than restart.
- Inspectable session handoff. Describe how the long-running-agent example lets a fresh session establish where to continue.
- Progress tracking approaches. Distinguish Manus’s maintained checklist, the Anthropic harness’s inspectable artifacts, and LangGraph’s framework-managed graph state. Explain what makes a checklist a checkpoint rather than just a record of intended work.
- Persistence and application responsibility. Explain what LangGraph checkpointers can preserve across execution steps and failures, and what remains the application’s responsibility.
- Durable progress and recovery. Explain that ProgressTracker writes task status to JSON after each change and uses it to reconstruct completed, pending, and failed items. Distinguish this demonstration of durable storage from a production recovery record, which needs fields required by its recovery contract.
- Effect-aware checkpoint recovery. Explain why a prose recap is insufficient after an agent has changed files, run a migration, or opened an external review, and describe the evidence needed before resuming.
- Failure facts and lessons. Distinguish an immutable failure fact and its execution evidence from a revisable candidate diagnosis and a published lesson. Explain why preserving the original evidence matters when an explanation changes.
- Lesson publication boundary. Explain why finding a similar failure does not by itself authorize a candidate lesson for reuse. Describe the separation between observed failures, candidate guidance, and reviewed published guidance.
- Failure journal admission boundary. Trace how an immutable failure entry can support a candidate lesson that undergoes independent admission before scoped reuse and later effect observation. Explain why finding a similar entry or generating a verbal lesson does not validate or publish it.
- Candidate failure memory safeguards. Explain why a model-written note about a failed approach is only candidate failure memory, and describe the safeguards a dedicated Failure Journal adds before a lesson is published.
- Failure capture and storage. Trace how the record method captures raw failure context, generates a candidate heuristic, and writes a structured entry to both an append-only file and a search index. Explain why production code must handle partial writes and preserve provenance.
- Candidate recall boundary. Distinguish consulting candidate heuristics from admitting them to active recall. Explain that retrieval returns candidates for review, while independent evaluation, admission evidence, and observed outcomes determine whether a candidate can be used later.
- Failure journal reliability risks. Explain why durable capture alone does not make a failure journal reliable, and describe the ways its lessons can mislead later tasks.
- Journal value and conditions. Describe the conditions in which a failure journal works well and how to assess whether it is worth its cost.
- Failure Driven Pattern Selection. Explain why the four memory patterns are selected by observed failure rather than installed in a fixed order, and describe the distinct boundary each governs.
- Stored Memory Validity Gates. Explain what must be checked before a stored item returns to active context and why its age alone cannot determine whether to retain or use it.
- Memory Composition Acceptance Test. Describe when to combine memory patterns and how to decide whether the combined design is worth keeping.
- Memory and collaboration responsibilities. Distinguish memory’s persistence and retrieval policy from collaboration’s decisions about tasks, roles, handoffs, communication, and integration, even when both use the same store.
- Argus later-review recovery. Trace what the Argus scenario preserves across reviews: candidate evidence and a checkpoint are written, then a fresh adapter reconnects and reconstructs completed work, pending verification, and related candidate guidance. State the demonstrated limits without treating the checks as production guarantees.
- Memory policy at decision time. Explain why items in the same store can have different authority and how to judge a memory policy at the next decision. Distinguish useful, valid recall and safe recovery from merely increasing store size or recall count.
What it builds on
- Set trust boundaries before granting autonomy (chapter 2) · The need to set trust boundaries before granting an agent autonomy.
- The context window as a treatment budget (chapter 3) · The context window as a limited boundary for information available to the agent.
- Context triage in Claude Code (chapter 3) · Claude Code’s memory sources as context-loading inputs.
Section by section
Introduction
The introduction defines agent memory as a policy for carrying information across boundaries, using a decision ledger to show why stored history must be separated from current authority.
- Decision history and current authority: Explain why a superseded decision should remain in the record without continuing to guide execution, and how the ledger distinguishes history from the current accepted decision.
Why it matters: An agent can retain useful history without acting on obsolete instructions. - Memory as boundary policy: Describe agent memory as a policy for what information survives boundaries, rather than simply a store of conversations or documents.
Why it matters: Choosing what to retain is not enough; an agent also needs rules for when retained information may be used. - Persistence versus admitted learning: Distinguish a stored trace or proposed lesson from information validated for reuse, and state where current operational authority resides.
Why it matters: A saved experience should not silently become a rule for future actions.
Key terms: append-only ledger, superseded, current accepted decision, control plane, agent memory, boundary, policy, live decision, persistence, candidate lesson
4.1 What is memory? State, persistence, and knowledge across sessions
The section defines agent memory as selected information carried across a boundary and distinguishes its roles in resuming work, retrieving evidence, and carrying experience into later tasks.
- Memory and two selection points: Explain that memory preserves selected information for a later decision, with selection both when information is retained and when it returns to active context.
Why it matters: Treating retention and recall as separate choices helps explain why stored information need not appear in every decision. - State and evidence responsibilities: Distinguish state persistence, which keeps what is needed to resume interrupted work, from evidence retrieval, which finds current, permitted, relevant material outside the active context.
Why it matters: An agent needs different remembered information to pick up unfinished work than to find supporting material. - Experience capture and admission: Explain why preserving failure facts and proposed lessons does not, by itself, authorize their use in a later task.
Why it matters: A stored lesson should not shape future behavior merely because it was recorded.
Key terms: memory, active context, state persistence, evidence retrieval, experience capture, failure facts, proposed lessons, provenance, validation, admission
4.1.1 The memory hierarchy analogy
This section uses a cognitive memory analogy to explain how agent memory differs by purpose, access cost, lifetime, and authority.
- Three cognitive memory tiers: Distinguish working, episodic, and semantic memory as the analogy for different kinds of agent memory.
Why it matters: The analogy gives you a starting vocabulary for what an agent keeps close and what it remembers from elsewhere. - Multiple dimensions of agent memory: Explain why an engineering memory hierarchy needs dimensions beyond the three-tier analogy, including scope, function, access, lifetime, and authority.
Why it matters: These dimensions prevent a single memory tier from standing in for every design decision about an item. - Access cost versus authority: Explain why moving information nearer the model affects availability and token cost but does not make it more authoritative, and describe the checks retained for each tier.
Why it matters: Keeping access separate from authority helps an agent use scarce context without treating convenient or recent information as more trustworthy.
Key terms: working memory, episodic memory, semantic memory, scope, function, access, lifetime, authority, access-cost analogy, provenance
4.1.2 The memory lifecycle
This section outlines possible memory lifecycle operations and explains why retention, retrieval, and updates require decisions about policy and authority.
- Selective memory lifecycle: Describe the operations selected information may pass through and explain that a memory design implements only the operations it needs.
Why it matters: The lifecycle gives you a way to consider what happens to information without assuming every memory system needs the same features. - Memory policy and authority: Explain what the two analogies illustrate and why neither determines which information should be authoritative.
Why it matters: Convenience and retention alone cannot decide which remembered information an agent should trust. - Superseding team decisions: Distinguish superseding an older decision from forgetting it, and describe what memory and the control plane each provide in the game-team example.
Why it matters: Keeping the decision history need not leave execution uncertain about which decision currently applies.
Key terms: capture, organization, retrieval, update or supersession, sharing, forgetting, authority, proximity, supersession, memory
4.1.3 How production agents handle memory today
This section compares how production agents persist context and gives a rule for deciding when a dedicated memory layer is warranted.
- Persistent context authority: Distinguish context supplied to an agent from rules that are enforced, using Claude Code’s instruction files and auto memory as examples.
Why it matters: Remembered text can inform an agent without being a trustworthy way to enforce policy. - File-based session continuity: Describe how Cline and Manus use persistent files to carry useful information beyond a conversation or session.
Why it matters: These examples show that useful memory can be ordinary maintained files or saved work artifacts. - Dedicated memory layer choice: Justify when to rely on existing authoritative sources and when to add a dedicated memory layer.
Why it matters: A separate memory service adds complexity and control requirements, so it should solve a continuity problem existing sources cannot.
Key terms: user-written instruction files, auto memory, provenance, authoritative policy store, Memory Bank, externalized working memory, checkpoint files, authoritative sources, dedicated layer, control surface
4.1.4 Measuring memory quality
This section shows how to judge memory by its effect on later decisions and how to trace a memory item to find where its usefulness breaks down.
- Decision-based retrieval utility: Explain why memory quality is judged by decisions after retrieval rather than store size, and describe how to check whether retrieved items were cited, verified, or changed an action.
Why it matters: A large memory store or a good-looking hit rate does not show that memory helped the agent decide well. - Repeated-mistake diagnosis: Describe what to check when a related failure recurs, and distinguish failure to capture, retrieve, admit, or apply a lesson.
Why it matters: Locating the failed stage points to a more useful fix than merely adding more memories. - Staleness and publication signals: Explain how to assess a retrieved item's validity and describe what the publication ratio reveals about memory maintenance.
Why it matters: Memory can be plentiful yet misleading if obsolete items remain authoritative or unreviewed observations accumulate. - Baseline and boundary tracing: Describe how to set memory-quality thresholds and trace one item from its source to a later decision to find the first broken boundary.
Why it matters: Tracing a real item ties measurement and pattern selection to the boundary that actually failed.
Key terms: retrieval utility, precision, coverage, risk class, repeated-mistake rate, capture, retrieval, admission, application, memory staleness
4.2 Pattern: Hierarchical Retention
Introduces Hierarchical Retention as a way to keep information at the right scope and lifetime while preserving the authority of human-owned rules.
- Tier policies and transitions: Explain that Hierarchical Retention assigns information to tiers by scope, function, access, and lifetime, with policies for which sources enter and when information is promoted, evicted, invalidated, or superseded.
Why it matters: Those policies determine which memories are available for a decision and which have become stale. - Decision driven retention: Explain why retention periods depend on the decisions a product must make, using the camera and companion examples.
Why it matters: A useful retention policy preserves relevant context without keeping data that adds cost or privacy risk. - Authority over memory popularity: Distinguish frequently used or inferred preferences from authoritative human-owned rules, and explain why candidate memories must not automatically become active instructions.
Why it matters: Without an authority boundary, an inferred habit could override a person's explicit instruction.
Key terms: Hierarchical Retention, tiers, promotion, eviction, invalidation, retention, lifetime, AI camera, companion system, authority
4.2.1 Three tiers and the eviction question
This subsection frames three-tier retention as a configurable design whose transitions depend on broader rules about stored items.
- Retention tiers and transition rules: Explain that the teaching implementation uses three storage tiers with configurable promotion and eviction rules, while a production design can use different tiers if ownership and supersession remain explicit. Describe how scope, function, access, ownership, and admission shape what a stored item may become and when it may return, and why the table’s transition policies are examples to calibrate rather than universal defaults.
Why it matters: It helps you treat retention as a governed design choice, not a fixed three-tier recipe.
Key terms: storage tiers, promotion, eviction, scope, function, access
4.2.2 In production: Claude Code's scoped memory sources
This section explains how Claude Code’s memory sources differ in ownership and retention, and why model context must not be mistaken for an enforceable rule.
- Model-written memory status: Explain that auto memory can preserve project notes across sessions for continuity, but those notes remain candidate context rather than a path for silently changing managed policies or human-owned rules.
Why it matters: Continuity is useful only if model-written notes cannot quietly become authoritative rules. - Source scope and provenance: Describe why organization, user, project, local, rule, and auto-memory sources should remain distinguishable: they have different owners and sharing boundaries, which matter for provenance and resolving conflicts.
Why it matters: An agent needs to tell where an instruction came from before it can handle conflicting sources. - Context versus enforceable rules: Distinguish CLAUDE.md and auto-memory content, which shape choices as model context, from managed settings, sandbox restrictions, and hooks, which are appropriate for rules that must not be bypassed. Explain why inferred notes may be revised or retired automatically while hard rules require their human owner.
Why it matters: Putting a rule in model context does not provide the protection that an enforced boundary does.
Key terms: auto memory, candidate context, managed policy, human-owned project rule, scope-addressed sources, sharing boundaries, provenance, conflict resolution, CLAUDE.md, model context
4.2.3 Building it
This section uses a compact three-tier memory implementation to explain retrieval, eviction, and the safeguards needed before using those mechanisms in production.
- Durable Memory Promotion: Describe how retrieval moves an entry from durable memory into working context, and distinguish the example's use of vector-search relevance for eviction priority from a judgment of validity or authority.
Why it matters: A relevant memory can be useful to retrieve without becoming an authoritative one. - Configurable Memory Eviction: Explain how the teaching implementation combines importance, recency, and access frequency to enforce a memory budget, and why its settings must be calibrated to the workload.
Why it matters: A budget policy can discard the wrong memories if its signals are mistaken for quality or left uncalibrated. - Governed Memory Boundaries: Distinguish the teaching model's recorded fields from the additional controls a production entry needs, and explain why human-owned rules and model reflections should not be automatically demoted or admitted as authoritative memory.
Why it matters: Memory management must not silently discard authoritative rules or turn a model's reflection into an approved lesson.
Key terms: durable tier, working context, vector-search relevance score, eviction priority, _enforce_budget, importance, recency, access frequency, eviction policy, owner
4.2.4 Before and after: What eviction looks like
The section illustrates an eviction policy that restores the working budget while retaining evidence needed for reliable decisions.
- Evidence-preserving memory eviction: Explain why the example retains the error trace while allowing reproducible output to be regenerated, and describe how to judge whether the eviction policy works.
Why it matters: Freeing space is only useful if the agent keeps the evidence it needs to make sound decisions.
Key terms: eviction policy, working budget, error trace, high importance, stale-read incidents
4.2.5 Argus integration
Argus connects hierarchical memory to its review workflow so findings can be retrieved in later sessions, while leaving memory governance unimplemented.
- Argus review memory integration: Explain that Argus uses HierarchicalMemory to store review findings for retrieval in later sessions, and distinguish this integration from memory governance it does not yet implement.
Why it matters: It separates remembering past findings from deciding which memories should be accepted or replaced.
Key terms: Argus, HierarchicalMemory, candidate admission, policy ownership, supersession
4.2.6 When it breaks
Explains when hierarchical retention is useful, where it can fail, and how to keep authoritative sources in control of memory-driven decisions.
- Hierarchy fit and visibility: Explain when hierarchical retention is useful and what it makes easier to see.
Why it matters: A hierarchy helps only when its distinctions and sources are meaningful. - Authority over retained memory: Explain why retained entries cannot establish correctness on their own and how to ground a high-risk decision in an authoritative source.
Why it matters: This keeps remembered information from silently overruling the source that actually governs an action.
Key terms: hierarchy, promotion, eviction, invalidation, scope, lifetime, authority policy, precedence rule, control-plane source, model-written notes
4.3 Pattern: RAG Pipeline
This section introduces RAG as a governed pipeline that prepares external sources and assembles decision-specific evidence for an agent.
- Two paths of RAG: Describe how a write or compile path prepares sources and indexes, while a read or assemble path retrieves an evidence package for a particular decision.
Why it matters: The evidence an agent can retrieve depends on how its sources were prepared. - Decision-specific evidence requirements: Explain why retrieved evidence must account for source authority, permissions, versions, and the possibility that the agent should abstain, rather than merely match similar text.
Why it matters: A plausible citation is not enough if the pipeline omitted evidence that should change the answer. - RAG suitability and evaluation: State when RAG is useful and describe the measures that should be considered together when evaluating it.
Why it matters: Retrieval has to deliver useful evidence without ignoring the time and context it consumes.
Key terms: RAG Pipeline, write or compile path, read or assemble path, evidence package, source authority, permission, version, abstention, incomplete retrieval, source corpus
4.3.1 Two governed paths: Compile and assemble
The section distinguishes RAG’s compile and assemble paths and explains when agent-directed retrieval is worth its added cost.
- Compile and assemble paths: Distinguish the compile path’s preparation of a governed corpus from the assemble path’s retrieval and packaging of cited evidence. State that the teaching listing implements only part of this broader contract.
Why it matters: The distinction keeps retrieval logic from being mistaken for the whole RAG pipeline. - Agentic retrieval tradeoff: Explain what the model can decide in the agentic RAG example and why an exact-key task may instead favor deterministic lookup.
Why it matters: Agentic flexibility should earn its added cost and verification burden.
Key terms: compile path, assemble path, provenance, permissions, versions, citations, agentic form of RAG, deterministic lookup, exact key, verification surface
4.3.2 In production: Claude Code's tool-based retrieval
Shows how Claude Code retrieves repository evidence with tools, why that evidence needs source and version context, and how retrieval methods should fit the source.
- Repository as retrieval structure: Explain how Claude Code uses Grep, Glob, Read, and web tools to retrieve repository information while the model selects and refines queries, without requiring a separate memory product.
Why it matters: You can use structures the repository already has instead of assuming retrieval requires a new memory system. - Retrieved evidence provenance: Explain why reading the current working tree does not guarantee complete or authoritative evidence, and why an evidence package should name the source and version actually read.
Why it matters: Naming the source and version keeps a retrieved result from being mistaken for a complete, authoritative view. - Source-matched retrieval methods: Describe how the retrieval approach should vary with the source: direct lookup for exact identifiers, lexical or semantic search for prose, structural or dependency-aware search for code, and temporal or provenance filters for decisions and incidents.
Why it matters: Matching the search method to the source makes retrieval more useful without imposing one product architecture.
Key terms: tool-based retrieval, Grep, Glob, Read, retrieval structures, current working tree, evidence package, source and version, direct lookup, lexical and semantic search
4.3.3 Building it
This section describes a RAG retrieval implementation that combines query rewriting and hybrid search, explains how RRF merges results, and cautions that retrieval gains must be measured.
- RAG Pipeline Components: Describe the implementation as combining query rewriting, semantic search, keyword search, and RRF, while leaving authority and coverage checks to the application.
Why it matters: This distinguishes the retrieval components shown here from checks an application must define for itself. - Reciprocal Rank Fusion Scoring: Explain how RRF merges search-result rankings when their raw scores cannot be compared directly.
Why it matters: Rank-based fusion lets the pipeline combine results without treating unlike search scores as equivalent. - Hybrid Search Recall Tradeoff: Explain why combining semantic and keyword search may improve recall, and why that improvement must be measured for the task and corpus.
Why it matters: Complementary retrieval is useful only if it improves results on the material and tasks the agent actually faces.
Key terms: query rewriting, semantic search, keyword search, Reciprocal Rank Fusion, authority and coverage checks, RRF, rank, k, recall, corpus
4.3.4 When it breaks
Explains when a RAG pipeline is useful, how it can fail despite apparently relevant retrieval, and how to test and verify its answers.
- Silent retrieval failures: Explain how a retrieved package can look relevant yet omit a controlling source, and describe the retrieval conditions that can cause this.
Why it matters: An answer can appear well supported while missing the source that would change it. - Retrieval suitability and evaluation: Describe when RAG is worth using and how to compare candidate pipelines against the cost and risk of retrieval.
Why it matters: Retrieval should improve acceptable answers enough to justify its cost and failure risks. - Answer verification after retrieval: Explain why retrieving sources does not by itself validate the agent's answer, and describe the safeguards the section recommends.
Why it matters: Citations and proportionate review help catch errors that successful retrieval alone cannot prevent.
Key terms: RAG, retrieved package, controlling source, chunk boundaries, index, accepted outcomes, injected tokens, citation coverage, missed-authority failures, source citations
4.4 Pattern: Progress tracking
Progress Tracking preserves inspectable task state so an agent can resume bounded work after a reset, session break, or handoff instead of starting over.
- Resumable checkpoint contract: Explain when Progress Tracking is useful and what a checkpoint must preserve for work to resume rather than restart.
Why it matters: Preserving the task contract and its evidence lets the next worker continue without guessing what is done or repeating an effect. - Inspectable session handoff: Describe how the long-running-agent example lets a fresh session establish where to continue.
Why it matters: Inspectable artifacts let a successor check the recorded progress before relying on it. - Progress tracking quality measures: State how the section proposes judging whether Progress Tracking supports recovery.
Why it matters: These measures reveal whether saved progress actually prevents costly or unsafe repetition.
Key terms: Progress Tracking, checkpoint, acceptance condition, side-effect receipts, idempotency keys, progress log, JSON feature list, version-control history, recovery contract, duplicated work
4.4.1 The checkpoint chain
4.4.2 In Production: Three approaches compared
The section compares three production approaches to progress tracking and explains why persisted progress still needs evidence and application-level safeguards.
- Progress tracking approaches: Distinguish Manus’s maintained checklist, the Anthropic harness’s inspectable artifacts, and LangGraph’s framework-managed graph state. Explain what makes a checklist a checkpoint rather than just a record of intended work.
Why it matters: The form of saved progress affects what a fresh process can inspect and whether it can trust a reported completion. - Persistence and application responsibility: Explain what LangGraph checkpointers can preserve across execution steps and failures, and what remains the application’s responsibility.
Why it matters: Saving execution state does not by itself prove success or make retries of external effects safe.
Key terms: todo.md, checklist, checkpoint, progress log, feature list, version history, checkpointers, graph state, pending writes, acceptance condition
4.4.3 Building it
The section shows how a ProgressTracker persists task status and explains why production recovery needs a richer record.
- Durable progress and recovery: Explain that ProgressTracker writes task status to JSON after each change and uses it to reconstruct completed, pending, and failed items. Distinguish this demonstration of durable storage from a production recovery record, which needs fields required by its recovery contract.
Why it matters: A saved task status helps an agent resume, but production recovery may require more evidence about what happened.
Key terms: ProgressTracker, JSON, recovery contract
4.4.4 When it breaks
This section explains when progress tracking supports safe recovery, how it fails, and how to measure and implement it.
- Effect-aware checkpoint recovery: Explain why a prose recap is insufficient after an agent has changed files, run a migration, or opened an external review, and describe the evidence needed before resuming.
Why it matters: Verifying what already happened prevents a resumed agent from duplicating consequential work. - Checkpoint conflicts and settled decisions: Explain how missing decision evidence and concurrent updates can make a checkpoint unreliable.
Why it matters: Otherwise a resumed worker may reopen a settled decision or rely on conflicting progress records. - Recovery measurement baseline: Describe how to compare checkpoint recovery with a baseline and what context to report with an improvement claim.
Why it matters: A checkpoint is useful only if recovery improves on a meaningful baseline without hiding duplicated effects. - Memory and implementation boundaries: Distinguish preserved checkpoint state from what Perception places in the current view, and describe when simple project files suffice instead of a dedicated service.
Why it matters: Keeping these responsibilities separate avoids mistaking attention placement for durable state or adding infrastructure without a need.
Key terms: progress tracking, checkpoint, artifact versions, verification results, acceptance evidence, authoritative versions, conflict detection, baseline, orientation tokens, latency
4.5 Pattern: Failure journals
This section introduces Failure Journals as a way to preserve evidence of recurring failures while controlling which lessons can influence later tasks.
- Failure facts and lessons: Distinguish an immutable failure fact and its execution evidence from a revisable candidate diagnosis and a published lesson. Explain why preserving the original evidence matters when an explanation changes.
Why it matters: Keeping evidence separate from interpretation lets the agent revisit a failure without treating its first diagnosis as fact. - Lesson publication boundary: Explain why finding a similar failure does not by itself authorize a candidate lesson for reuse. Describe the separation between observed failures, candidate guidance, and reviewed published guidance.
Why it matters: A plausible match to an old failure should not silently turn an unreviewed explanation into guidance or policy. - Recurring failure signals: Describe when a Failure Journal is useful and what two recurring symptoms suggest about its design: re-debugging the same cause and applying an old lesson to the wrong case.
Why it matters: These symptoms help distinguish a journal that fails to recall useful history from one that reuses history too broadly.
Key terms: Failure Journal, failure fact, execution evidence, candidate diagnosis, published lesson, publication boundary, candidate lesson, admission, hard rule, capture
4.5.1 Failure fact, candidate lesson, published lesson
The section distinguishes recorded failures and candidate lessons from lessons independently admitted for reuse.
- Failure journal admission boundary: Trace how an immutable failure entry can support a candidate lesson that undergoes independent admission before scoped reuse and later effect observation. Explain why finding a similar entry or generating a verbal lesson does not validate or publish it.
Why it matters: Keeping evidence separate from admitted lessons helps prevent an appealing but unsupported generalization from becoming reusable guidance.
Key terms: failure journal, immutable evidence, candidate lesson, independent admission, scoped reuse
4.5.2 In production: Model-written notes as candidate memory
This section distinguishes model-written failure notes from verified lessons and explains how an index can organize a growing Failure Journal without validating its contents.
- Candidate failure memory safeguards: Explain why a model-written note about a failed approach is only candidate failure memory, and describe the safeguards a dedicated Failure Journal adds before a lesson is published.
Why it matters: Keeping candidate notes separate from verified lessons prevents a failed attempt from becoming an unchecked rule. - Journal index limits: Describe how an index can organize a growing Failure Journal and what it cannot establish about its lessons.
Why it matters: An easier-to-browse journal still needs its lessons checked for validity and currency.
Key terms: auto memory, candidate failure memory, Failure Journal, raw evidence, index, topic files, Hierarchical Retention
4.5.3 Building it
Shows how a failure journal records failures and retrieves proposed lessons for review without treating them as admitted memory.
- Failure capture and storage: Trace how the record method captures raw failure context, generates a candidate heuristic, and writes a structured entry to both an append-only file and a search index. Explain why production code must handle partial writes and preserve provenance.
Why it matters: A searchable lesson is not a reliable record if a failed write leaves its source or status unclear. - Candidate recall boundary: Distinguish consulting candidate heuristics from admitting them to active recall. Explain that retrieval returns candidates for review, while independent evaluation, admission evidence, and observed outcomes determine whether a candidate can be used later.
Why it matters: Keeping proposals separate from admitted memory prevents an unverified lesson from shaping later work.
Key terms: record method, raw failure context, candidate heuristic, append-only file, search index, provenance, candidate, candidate consultation, active recall, independent evaluation
4.5.4 When it breaks
This section explains when failure journals are useful, how they can mislead later tasks, and how to judge whether they earn their cost.
- Failure journal reliability risks: Explain why durable capture alone does not make a failure journal reliable, and describe the ways its lessons can mislead later tasks.
Why it matters: A remembered lesson is only useful if it remains grounded in evidence and applies to the task at hand. - Journal value and conditions: Describe the conditions in which a failure journal works well and how to assess whether it is worth its cost.
Why it matters: Counting saved work alone can hide the damage caused by applying a lesson to the wrong task.
Key terms: durable capture, causal attribution, scope, admission, expiry, retrieval, execution evidence, separate review path, verified lesson, avoided rework
4.6 Composing memory patterns
The section shows how to select, combine, and test memory patterns so that only valid stored information returns to an agent’s decisions.
- Failure Driven Pattern Selection: Explain why the four memory patterns are selected by observed failure rather than installed in a fixed order, and describe the distinct boundary each governs.
Why it matters: Choosing by failure avoids adding memory machinery that does not repair the problem you observed. - Stored Memory Validity Gates: Explain what must be checked before a stored item returns to active context and why its age alone cannot determine whether to retain or use it.
Why it matters: Keeping a memory is not the same as establishing that it is safe to use in the current decision. - Memory Composition Acceptance Test: Describe when to combine memory patterns and how to decide whether the combined design is worth keeping.
Why it matters: A combination should earn its added complexity through measured improvement without losing safeguards. - Regression Boundary Scenarios: Describe the concrete failure scenarios used to check that a memory composition preserves authority, retrieved evidence, external effects, and lesson admission.
Why it matters: These scenarios expose regressions that an ordinary successful run may not reveal.
Key terms: Hierarchical Retention, RAG Pipeline, Progress Tracking, Failure Journals, validity gates, active context, authority, supersession, retention policy, composition
4.7 Memory and collaboration: A boundary
The section distinguishes memory’s responsibility for carrying information across boundaries from collaboration’s responsibility for assigning and integrating work.
- Memory and collaboration responsibilities: Distinguish memory’s persistence and retrieval policy from collaboration’s decisions about tasks, roles, handoffs, communication, and integration, even when both use the same store.
Why it matters: Separating these responsibilities clarifies which part of an agent system should decide what is retained versus who does the work. - Delegated worker handoff context: Explain why a delegated worker need not inherit its parent’s conversation or tool history, and describe the distinct contributions of memory and collaboration to its handoff.
Why it matters: A handoff can provide relevant, traceable context without treating a parent agent’s entire history as the worker’s memory.
Key terms: Memory, Collaboration, persistence, retrieval policy, delegated worker, versioned findings, source references, handoff
4.8 Argus checkpoint: What Argus can do now
This checkpoint shows what Argus’s memory patterns can carry into a later review and argues that memory should be judged by the authority and usefulness of what returns, not by how much is stored.
- Argus later-review recovery: Trace what the Argus scenario preserves across reviews: candidate evidence and a checkpoint are written, then a fresh adapter reconnects and reconstructs completed work, pending verification, and related candidate guidance. State the demonstrated limits without treating the checks as production guarantees.
Why it matters: A later review must recover useful state without mistaking candidate material or a focused check for a production guarantee. - Memory policy at decision time: Explain why items in the same store can have different authority and how to judge a memory policy at the next decision. Distinguish useful, valid recall and safe recovery from merely increasing store size or recall count.
Why it matters: Remembering more is not helpful if the agent recalls the wrong authority, repeats an effect, or treats an unverified candidate as established.
Key terms: Argus, Hierarchical Retention, Progress Tracking, Failure Journals, review_candidate, checkpoint, memory policy, authority, reverified, valid source
4.9 Summary
4.10 References
This section lists references for the chapter on agent memory without explaining any assessable concepts or procedures.
Where this is used later
- Record, admit, and recall (chapter 7) · Recording, admitting, and recalling experience builds on the distinction between persistence and validated reuse.
- Argus as a composition self-test (chapter 10) · The memory lifecycle
- Layer 2: Execution isolation (sandboxing) (chapter 9) · Sandboxing provides an enforcement mechanism rather than relying on model context alone.
- Two operating mismatches changed the design (chapter 11) · The RAG Pipeline pattern provides retrieved material.
- Persist before asking the model to remember (chapter 6) · Uses persisted state rather than asking the model to remember a plan.
- Start with the model behind the picture (chapter 11) · Progress tracking as a way to preserve work across interruptions
- Recover effects before retrying calls (chapter 6) · Supports the distinction between recovering recorded progress and safely retrying effects.
- What collaboration changes (chapter 8) · Collaboration introduces multiple workers that may need to coordinate shared state.
Concepts explained in this chapter
- source of truthA source of truth is the authoritative source for a particular piece of information.
- checkpointingThe practice of recording execution state at checkpoints so a workflow can resume after interruption.
- auto memoryClaude Code's agent-authored memory facility, which loads selected indexed content at session start and makes detailed topic files available for retrieval.
- control planeA control plane is the part of a system that governs its operation by managing authoritative decisions, policies, or configuration.
- progress trackingA persistence pattern that records task state and completed work so an interrupted agent can resume execution.
- retrieval-augmented generationA technique that retrieves relevant information from an external corpus and supplies it to a language model to inform generation.
- memory hierarchyAn organized set of memory stores with different capacities, persistence, and access costs.
- memory bank methodologyA structured practice of maintaining project context in a collection of persistent Markdown files for agent sessions.
- memoryAn agent capability for retaining or retrieving information across or within tasks.
- context windowThe bounded sequence of tokens that a language model can attend to during an interaction.
- semantic memorySemantic memory is persistent memory for general facts, concepts, and their relationships rather than specific events.
- working memoryThe limited information temporarily available to an agent or model while it performs a task.
- evaluationEvaluation is the systematic assessment of a result against criteria for quality, correctness, or suitability.
- heuristicA practical rule or strategy for proposing a solution without guaranteeing an optimal result.
- agentic RAGRetrieval-augmented generation in which an agent can make decisions about whether and how to retrieve information.
- collaborationAn agent capability for coordinating information or activity with other agents or humans.
- validationValidation is the process of assessing whether a candidate lesson is suitable to influence a later task.
- admissionTool admission is a check that a proposed tool operation remains authorized and appropriate given current authority, provenance, and state freshness.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
