14 Built-in Memory for Claude Managed Agents

14.1 Agents That Remember

On April 23, 2026, Anthropic announced built-in memory for Claude Managed Agents — an intelligence-optimized memory layer that lets agents learn from every session and carry knowledge forward across interactions. The feature addressed a fundamental limitation of stateless agents: every session started from scratch, forcing users to re-explain context, re-establish preferences, and re-provide information the agent had already encountered.

With built-in memory, an agent that learned your codebase conventions in one session applies them in the next. An agent that discovered a quirk in your API remembers it. An agent that developed an effective approach to a recurring task reuses it. Memory transforms agents from stateless tools into accumulating intelligence.

This chapter covers what the memory layer is, how it works, its features, and how to use it effectively.

14.2 What the Memory Layer Does

The built-in memory layer provides persistent, structured storage for information an agent learns across sessions. It’s distinct from the agent’s context window (which holds the current session’s working memory) and from state (which tracks the current task’s progress). Memory is the agent’s long-term knowledge — what it has learned that will be useful in the future.

Layer	Scope	Lifetime	Example
Context window	Current session	Session	The files and conversation in the current turn
State	Current task	Task	Progress on the current migration
Memory	Cross-session	Persistent	“This project uses tabs, not spaces”

Note

The distinction between context, state, and memory is important. Context is ephemeral working memory (the current session). State is task progress (where we are in the current job). Memory is durable knowledge (what we’ve learned that applies going forward). Built-in memory addresses the third layer — the one that was missing.

14.3 How Memory Works

14.3.1 Filesystem-Based

Memory is implemented as a filesystem-based store. Memories are stored as files — structured, readable, and exportable. This design choice has several advantages:

Transparency: You can inspect what the agent has learned by reading the memory files.
Portability: Memory files can be exported, shared, and moved between agents.
Versioning: File-based storage integrates naturally with version control and audit systems.
Debuggability: When an agent behaves unexpectedly, you can inspect its memory to understand why.

14.3.2 Intelligence-Optimized

The memory layer is optimized for how agents use knowledge, not for arbitrary data storage. It’s structured around the kinds of information agents actually need: preferences, conventions, facts about the environment, effective approaches to task types, corrections from past mistakes.

The memory system decides what to store (and what to discard) based on utility for future work. A one-off detail that won’t be relevant again may not be stored; a convention that will apply to every future task will be.

14.4 Key Features

14.4.1 Scoped Permissions

Memory stores have scoped permissions — not every agent (or every user) can read or write every memory. You control which agents can access which memories, enabling:

Agent-specific memory: An agent’s private knowledge, not shared with others.
Team-shared memory: Knowledge shared across a team’s agents.
Project-scoped memory: Knowledge specific to a project, accessible to agents working on it.

Scoping ensures that sensitive information stays controlled and that agents don’t interfere with each other’s knowledge.

14.4.2 Audit Logs

Every change to memory — creation, update, deletion — is recorded in an audit log. The audit log captures:

What changed (the memory content before and after).
When it changed.
Who changed it (which agent, which session).

This provides full traceability for regulated environments and for debugging (“why does the agent think X?”).

14.4.3 Programmatic Control

Memory is fully programmatically controllable via APIs. You can:

Read memories (programmatically, not just by the agent).
Write memories directly (to seed an agent with knowledge).
Update memories (to correct or refine).
Delete memories (to remove outdated or incorrect knowledge).
Search memories (to find relevant knowledge for a task).

# Conceptual memory API usage
memory = agent.memory

# Write a memory
memory.write(
    key="codebase-conventions",
    content="This project uses 2-space indentation and camelCase naming."
)

# Search for relevant memories
relevant = memory.search(query="naming conventions")

# The agent automatically loads relevant memories at session start

14.4.4 Shared Stores Across Agents

Memory stores can be shared across agents. Multiple agents working on the same project can draw from a common knowledge base, ensuring consistency. A coding agent and a documentation agent sharing a memory store would both know the project’s conventions.

14.4.5 Exportable Memories

Because memories are files, they’re exportable. You can export an agent’s memory to:

Back it up (for disaster recovery).
Share it with another team or agent.
Migrate it to a different agent or platform.
Audit it for compliance.

14.4.6 Rollback and Redo

Memory changes are tracked with the audit log, enabling rollback (revert to a previous state) and redo (reapply a change that was rolled back). This is valuable when:

An agent learns something incorrect (rollback the bad memory).
You want to experiment with different memory states (rollback and redo freely).
A bug corrupted memory (rollback to a known-good state).

Tip

Rollback is a safety net for agent learning. If an agent picks up a bad habit or incorrect belief, you don’t have to live with it — rollback the memory to before the error and let the agent re-learn correctly. This makes agent memory experimentable and correctable, not a one-way ratchet.

14.5 Use Cases

14.5.1 Learning User Preferences

An agent that works with a specific user can learn their preferences over time: preferred coding style, communication tone, priorities, recurring tasks. Memory captures these, so the agent’s behavior adapts without explicit re-configuration.

14.5.2 Accumating Codebase Knowledge

An agent working on a codebase accumulates knowledge about its architecture, conventions, quirks, and history. This knowledge makes subsequent work more efficient — the agent doesn’t have to re-discover what it already knows.

14.5.4 Compliance and Audit

In regulated environments, the audit log provides the traceability required for compliance. Every piece of knowledge an agent holds is traceable to when and how it was acquired.

14.6 Memory vs. CLAUDE.md

It’s worth distinguishing memory from CLAUDE.md (the project configuration file from Claude Code, Chapter 9), since they serve related but distinct purposes:

Aspect	CLAUDE.md	Memory
Author	Human (you write it)	Agent (it learns)
Content	Static facts, gotchas	Accumulated knowledge
Scope	Project	Agent/session/project
Mutability	You edit it manually	Agent updates automatically
Purpose	Orient the model	Carry learned knowledge forward

CLAUDE.md is human-authored orientation; memory is agent-accumulated knowledge. They complement each other: CLAUDE.md tells the agent what you know; memory holds what the agent has learned.

14.7 Best Practices

14.7.1 Seed Memory with Key Knowledge

When deploying an agent, seed its memory with key knowledge: project conventions, important facts, known gotchas. This gives the agent a strong starting point rather than making it learn everything from scratch.

14.7.2 Monitor What the Agent Learns

Periodically review the agent’s memory (it’s file-based and readable) to ensure it’s learning accurate, useful knowledge. Catch and correct incorrect memories early.

14.7.3 Use Scoping Deliberately

Think about memory scope: what should be agent-specific, what should be team-shared, what should be project-scoped. Over-sharing can cause confusion; under-sharing duplicates knowledge unnecessarily.

14.7.4 Leverage Audit Logs

Use the audit log for debugging (“why does the agent think this?”) and for compliance. The log is a powerful tool for understanding and trusting agent behavior.

14.8 Memory Architecture in Depth

Understanding the memory architecture helps you design effective memory strategies for your agents.

14.8.1 The Three-Layer Model

Managed Agents operates with a three-layer model of agent information:

Layer	Purpose	Lifetime	Example
Context	Current session working memory	Session	Files being edited, conversation history
State	Current task progress	Task/session	“Step 3 of 10 complete; waiting for test results”
Memory	Long-term accumulated knowledge	Persistent	“This project uses tabs for indentation”

Each layer serves a different purpose, and confusing them leads to inefficiency. Don’t put facts that should be in memory into the context (they’ll be lost when the session ends). Don’t put task progress that should be in state into memory (it’s not long-term knowledge).

14.8.2 Memory Types

Within the memory layer, different types of knowledge serve different purposes:

Preferences: User or project preferences (“User prefers concise summaries”).
Conventions: Coding or process conventions (“This project uses conventional commits”).
Factual knowledge: Information about the environment (“The database is PostgreSQL 15”).
Procedural knowledge: Effective approaches (“For this type of task, approach X works well”).
Corrections: Things that were wrong and shouldn’t be repeated (“Don’t use the deprecated API; use v2”).

The memory system stores and retrieves these types appropriately, applying different relevance signals to each.

14.8.3 How Memories Are Retrieved

When an agent starts a session or encounters a task, relevant memories are retrieved and loaded into context. The retrieval mechanism uses:

Semantic relevance: Memories semantically related to the task are prioritized.
Recency: More recent memories may be more relevant (preferences may change).
Frequency: Memories referenced often are likely important.
Explicit references: Memories explicitly linked to the current project, user, or task.

This retrieval is automatic — the agent doesn’t need to explicitly query memory. The right memories surface when they’re relevant.

Note

Automatic retrieval is what makes memory feel “intelligent.” The agent doesn’t search for relevant knowledge; the relevant knowledge arrives when needed. This is similar to how human memory works — you don’t consciously search for “how to type”; the knowledge is just there when you need it.

14.9 Designing a Memory Strategy

Effective use of memory requires a strategy — decisions about what to store, how to scope it, and how to maintain it.

14.9.1 What to Store

Let the agent learn from experience, but also seed memory with key knowledge upfront:

Seed memories (before first use): - Project conventions and coding standards - Architecture decisions and their rationale - Known gotchas and traps - Key stakeholder preferences

Let the agent accumulate: - Effective approaches to recurring task types - Corrections from past mistakes - User-specific preferences learned over time - Discoveries about the codebase or environment

14.9.2 Scoping Strategy

Decide on memory scopes based on your organization’s structure:

Scope	Best For	Example
Agent-specific	An agent’s private knowledge	A personal assistant’s knowledge of one user
Team-shared	Knowledge for a team’s agents	A dev team’s coding conventions
Project-scoped	Knowledge for a specific project	Architecture decisions for Project X
Organization-wide	Universal knowledge	Company-wide security policies

Over-sharing causes confusion (an agent gets irrelevant memories from another project). Under-sharing causes duplication (each agent learns the same thing independently). Find the right balance for your organization.

14.9.3 Maintenance Strategy

Memory is not set-and-forget. It requires maintenance:

Periodic review: Check what the agent has learned. Correct inaccurate memories.
Pruning: Remove outdated memories (conventions that changed, facts that are no longer true).
Consolidation: Merge redundant memories. Split overly broad memories.
Quality control: Ensure memories are accurate, useful, and well-structured.

The audit log (which tracks every memory change) makes maintenance tractable — you can see exactly what changed and when.

14.10 Advanced Memory Patterns

14.10.1 Pattern 1: Cross-Agent Knowledge Transfer

When an agent discovers valuable knowledge, share it with other agents:

# Agent A discovers a useful pattern
memory.write(
    key="effective-testing-approach",
    content="For testing async functions in this codebase, use pytest-asyncio with the 'auto' mode.",
    scope="team-shared"
)

# Agent B (a different agent) automatically retrieves this when relevant

This pattern turns individual agent learning into organizational knowledge accumulation.

14.10.2 Pattern 2: Memory Versioning for Experimentation

Use rollback/redo to experiment with memory states:

Snapshot the current memory state.
Make changes (add new memories, modify existing ones).
Test the agent’s behavior with the new memory.
If better: keep the changes. If worse: rollback to the snapshot.

This makes memory experimentable — you can try different knowledge configurations without risk.

14.10.3 Pattern 3: Memory as Documentation

Because memories are file-based and exportable, they can serve as a form of living documentation. The memory that says “This project uses event sourcing” is documentation that the agent actually uses. Unlike a wiki page that may be outdated, memory that the agent uses is kept current (because the agent updates it when it finds it’s wrong).

14.10.4 Pattern 4: Seeding from Existing Documentation

If you have existing documentation (wikis, READMEs, architecture docs), you can seed memory from it:

# Read existing documentation and seed memory
docs = read_documentation("docs/architecture/")
for doc in docs:
    memory.write(
        key=f"arch-{doc.title}",
        content=doc.summary,
        scope="project"
    )

This gives new agents a strong starting knowledge base derived from your existing investment in documentation.

14.11 Memory and Privacy

Memory raises privacy considerations that require careful design:

Sensitive data: Don’t store sensitive personal data in memory unless appropriate controls are in place.
User-specific knowledge: Knowledge about specific users should be scoped and access-controlled.
Data retention: Define how long memories persist and when they should be deleted (GDPR “right to be forgotten”).

The scoped permissions and audit logs help manage these concerns, but organizations should establish clear policies about what agents may remember and about whom.

14.12 Measuring Memory Effectiveness

To assess whether memory is helping:

Session efficiency: Are sessions faster because the agent doesn’t re-learn known information?
Quality improvement: Is the agent’s work better because it applies accumulated knowledge?
User satisfaction: Do users feel the agent “knows” their preferences and context?
Memory utilization: Are stored memories actually being retrieved and used? (Unused memories waste storage and retrieval effort.)

If memory isn’t improving these dimensions, the strategy may need adjustment — different scoping, different content, or better retrieval configuration.

14.13 Key Takeaways

Built-in memory (launched April 23, 2026) is an intelligence-optimized memory layer for Managed Agents that lets agents learn from every session.
Filesystem-based: memories are stored as files — transparent, portable, versionable, and debuggable.
Intelligence-optimized: the system stores knowledge based on utility for future work, not arbitrary data.
Scoped permissions: control which agents can access which memories (agent-specific, team-shared, project-scoped).
Audit logs record every memory change (what, when, who) for traceability and compliance.
Programmatic control: read, write, update, delete, and search memories via APIs.
Stores can be shared across agents, enabling a common knowledge base for teams.
Memories are exportable — back up, share, migrate, or audit them as files.
Rollback and redo support correction of incorrect learning and experimentation with memory states.
Memory complements CLAUDE.md: CLAUDE.md is human-authored orientation; memory is agent-accumulated knowledge.