Chapter 12: Why Memory Changes Everything — Stateful vs. Stateless

By the end of this chapter, you will understand why agent memory is architecturally transformative, the difference between stateful and stateless agents, and when memory is the right tool for your workflow.

The Big Idea

Without memory, every session starts from zero.

You can build an agent that does excellent research in Session 1. In Session 2, it has no idea Session 1 happened. Every user preference it learned is gone. Every decision it made is forgotten. Every context it built up over hours of work is erased.

This is the default. According to the memory documentation: "Managed Agents API sessions are ephemeral by default. When a session ends, anything the agent learned is gone."

Memory stores change this. They are persistent, structured collections of text that the agent can read before starting a task and write to when it learns something worth keeping. With memory, the agent carries knowledge from session to session — user preferences, project conventions, prior mistakes, domain context.

The difference between a stateless agent and a stateful one is the difference between a capable stranger and a capable coworker. The stranger can do excellent work. The coworker does excellent work and already knows your codebase, your style preferences, what you tried last time, and what didn't work.

Important status note: Memory is a Research Preview feature, which means it requires separate access. The full memory API is available to approved users, but not automatically to all accounts. Check the memory documentation for current access requirements.

The Analogy

Think about the difference between hiring a contractor versus hiring a staff member.

The contractor is skilled. They show up, do the work, and leave. Every time they come back, you have to brief them again: here's the project, here's the codebase, here's how we do things, here are the decisions we already made. They're capable, but every engagement starts from zero.

The staff member is equally skilled. But they accumulate context. They remember the architecture decisions. They know you prefer descriptive variable names. They remember that you tried the caching approach in March and it caused problems. They show up each time knowing more than they did last time.

Memory stores are what make an agent a staff member rather than a contractor. The capability is the same. The accumulated context is what changes.

The cost of contractor briefings compounds over time. The value of staff member context also compounds over time. Memory is the mechanism that lets your agent's value increase with each session rather than reset.

How It Actually Works

What a Memory Store Is

A memory store is "a workspace-scoped collection of text documents optimized for Claude." (Memory)

The key properties:

• Each memory in a store is a text document at a specific path (like a file in a file system)
• The agent automatically checks memory stores before starting a task when they're attached
• The agent automatically writes durable learnings when done — no additional prompting or configuration needed
• Each memory change creates an immutable version record for auditing and rollback

The path-based structure is important. Memories aren't a single blob of text — they're organized documents. A memory at /preferences/formatting.md is distinct from one at /project/decisions.md. This lets the agent (and you, via the API) read and write specific memories without touching others.

The Automatic Behavior

When one or more memory stores are attached to a session, "the agent automatically checks the stores before starting a task and writes durable learnings when done — no additional prompting or configuration is needed." (Memory)

This is worth pausing on. You don't have to prompt Claude to read its memory or tell it to save what it learned. The behavior is built into the memory-enabled session. Attach a memory store, and the agent will:

1. Read relevant memories before starting work (via memory_search and memory_read tools)
2. Write new memories when it learns something worth keeping (via memory_write and memory_edit tools)

The Hard Limits

Understanding the limits is essential for designing memory architectures that work. From the memory documentation:

• Maximum 8 memory stores per session — "A maximum of 8 memory stores are supported per session."
• 100 KB per individual memory (~25K tokens) — "Individual memories within the store are capped at 100KB (~25K tokens). Structure memory as many small focused files, not a few large ones."
• 4,096 characters for the per-store prompt field at session creation

These limits shape how you design your memory architecture. The 100 KB cap per individual memory means you can't create one massive document — you need to structure knowledge as multiple small, focused files. The 8 stores per session limit means you can segment by type (user preferences in one store, project context in another) while staying within budget.

Stateless vs. Stateful: When Each Is Right

Not every agent needs memory. The right choice depends on whether accumulated context improves outcomes:

Stateless (no memory) is right when:

• Every task is independent with no shared context
• You're processing batches of unrelated documents
• Privacy requirements prevent cross-session data retention
• You're running one-off tasks with no repeat interactions

Stateful (with memory) is right when:

• The agent works with the same user repeatedly and should adapt to their preferences
• Tasks build on each other over time (a codebase that evolves, a project that progresses)
• The agent needs to remember decisions made in past sessions to avoid re-litigating them
• You want the agent to learn from mistakes and improve over time

Memory vs. Files vs. Session History

Three persistence mechanisms exist in Managed Agents. They're different tools for different jobs:

Memory stores are distinct from simply uploading files. Memory stores are optimized for agent access — small, structured, queryable documents that Claude reads intelligently before starting work. Files are raw data that the agent processes. Session history is the complete interaction record for a specific working session.

Memory Versioning: The Audit Trail

Every change to a memory creates an immutable version:

• operation: "created" — first write to a path
• operation: "modified" — content or path changed
• operation: "deleted" — memory deleted

(Memory)

You can view all versions of any memory, see what changed, and roll back to a previous state. This is critical for production memory systems: if the agent writes something incorrect, you can identify it, understand what changed, and correct it without losing the audit trail.

Access Modes: Read-Write vs. Read-Only

When attaching a memory store to a session, you control the access level:

resources=[
    {
        "type": "memory_store",
        "memory_store_id": store.id,
        "access": "read_write",  # or "read_only"
        "prompt": "User preferences and project context.",
    }
]

read_only attachment means the agent can consult memories but cannot write new ones or modify existing ones. This is useful for shared knowledge bases that multiple agents read from but only administrators update.

Chapter Recap

• Agent memory is a Research Preview feature that enables persistent knowledge across sessions. Without it, every session starts from zero — everything learned is lost when the session ends.
• A memory store is a workspace-scoped collection of text documents at paths. Agents automatically read from attached stores before starting work and write learnings when done — no prompting required.
• The key limits: 8 stores per session, 100 KB per individual memory. Structure knowledge as many small, focused files. Every change creates an immutable version for auditing. Use read_only access for shared knowledge bases that agents should consult but not modify.