Ask Knox

Every Managed Agents session starts fresh. When the session ends, the context window — everything the agent knew, reasoned through, and produced — does not persist to the next session automatically. This is correct behavior for stateless pipelines. It is a significant design constraint for pipelines that need to accumulate knowledge or avoid repeating work across sessions.

Memory in Managed Agents is not automatic. It is a deliberate, explicit mechanism: the agent writes memories when they should persist, and reads memories when prior context would be useful. Understanding the distinction between what is ephemeral and what requires explicit persistence — and how to design for that boundary — is the difference between a pipeline that compounds value over time and one that starts from zero on every run.

What Is Not Persisted Automatically

Before designing memory architecture, be precise about what does not persist across sessions:

Session conversation history — the messages between the orchestrator and the agent, the chain-of-thought reasoning, the intermediate working — all of this exists only within the session's context window. When the session ends, it is gone.

Tool call history — which tools were called, what inputs were provided, what results were returned — none of this is automatically accessible in a future session.

Intermediate work product — files written to the ephemeral session file system, data parsed from web searches, analysis conducted on input documents — ephemeral unless explicitly saved to external storage or written into an attached memory store.

Agent state — there is no "agent state" that persists between sessions unless you explicitly design one. Each session is a fresh instantiation of the agent with its system prompt and any tools and skills configured at agent definition time.

Memory Stores

The persistence mechanism is the memory store: a workspace-scoped resource created once and attached to sessions as needed. Attached stores are mounted into the sandbox's file system at /mnt/memory/<name>/, and the agent reads and writes them with the standard file tools — read, write, edit, glob, grep. There is no dedicated memory tool.

import anthropic

client = anthropic.Anthropic()

# Create the store once — it lives at the workspace level
store = client.beta.memory_stores.create(name="competitor-intel")

# Attach it when starting a session
session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id},
    environment_id=environment.id,
    resources=[
        {
            "type": "memory_store",
            "memory_store_id": store.id,
            "access": "read_write",
            "instructions": "Store key research findings here, one file per topic."
        }
    ]
)

The attachment fields are the design surface:

access — read_only or read_write. A reporting agent can read the accumulated research without being able to corrupt it; only the accumulator agent gets read_write.
instructions — guidance injected for the agent about what this store is for and how to use it.
A session can attach up to 8 memory stores, which is what makes scoping composable (more below).

Stores are versioned: each change produces a new version, so you can audit how the store evolved and roll back a bad write. A redact operation removes content from a store's history when something should never have been persisted.

How the Agent Uses Memory

Memory is not auto-injected. The store is mounted as files; the agent must actually read them when prior context would be useful:

[Agent reasoning during session]
The task is to research Anthropic's latest releases.
Let me check if I have prior research on this topic.
[grep "Anthropic" /mnt/memory/competitor-intel/]
[Finds: notes from 2026-03-15 about the Claude Sonnet release]
Good — I have context from last month. I'll use this as a baseline and update with newer information.

The agent does not passively receive memories at session start. It actively decides when to consult them. This means your system prompt (and the store's instructions) needs to direct the agent to check relevant memory files as part of its task workflow.

Retrieved memories often cover only part of the current task. When that happens, the right behavior is to use what the store provides as context and explicitly note where the gaps are in the output — rather than discarding partial memory and starting from zero, or stalling the session until everything is resolved. Flagging the gap keeps the result honest and gives the next session a clear signal about what still needs to be gathered.

Scoping Memory: One Store per Scope

There is no namespace taxonomy on individual memories. Scope is determined by which stores you attach to a session — and because a session can attach several, you compose scopes:

Per-user scope — create one store per user (user-prefs-{user_id}) and attach the matching store to that user's sessions. The agent sees only that user's memory.

Shared agent scope — create one store for the agent's accumulated knowledge and attach it to every session of that agent, regardless of user. Useful for accumulated research, processed document indexes, and any knowledge that should be globally available to the agent.

Both at once — attach the user's store and the shared store to the same session, with the shared store read_only if the user session should consume but not modify the global knowledge.

session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id},
    environment_id=environment.id,
    resources=[
        {
            "type": "memory_store",
            "memory_store_id": user_store.id,       # this user's context
            "access": "read_write",
            "instructions": "This user's preferences and history."
        },
        {
            "type": "memory_store",
            "memory_store_id": shared_store.id,     # fleet-wide knowledge
            "access": "read_only",
            "instructions": "Shared research corpus. Read-only."
        }
    ]
)

When a Memory Store Is Not the Right Tool

Memory stores are useful but not universally appropriate. For structured data that needs reliable retrieval, external storage is often more appropriate:

External database — if your agent processes daily records and needs to track which records have been processed, a database with a processed_at timestamp is more reliable and queryable than files in a mounted store.

Object storage (S3, GCS) — if your agent generates reports or produces files that need to persist for downstream systems, write them to object storage during the session. Memory stores are agent working memory, not a delivery mechanism.

Vector database — for semantic search over large accumulated knowledge bases, a vector database provides better retrieval precision than grep over memory files.

Memory stores are right for: lightweight state the agent reads conversationally, preferences and context for specific users, and accumulated findings that should inform future sessions without requiring a full database query.

Designing for Stateful Pipelines

For pipelines that genuinely require state across sessions, the design pattern is:

At session start, the agent reads its memory files (or reads from external storage) for relevant prior state
The agent incorporates prior state into its current reasoning
At session end, the agent writes new findings to the memory store (or to external storage) before the session completes
The next session starts by repeating step 1

This explicit state management is more work to design than implicit persistence, but it is also more controllable. You can inspect the memory store, correct wrong memories (each change is a new version, so bad writes can be rolled back), and design the file layout to match your pipeline's actual needs.

# System prompt that makes the pipeline explicitly stateful
system = """You are a market intelligence accumulator.

At the start of each session:
1. Read /mnt/memory/market-intel/recent_findings/{topic}.md if it exists
2. If prior findings exist, summarize what you know and when it was gathered
3. Identify what has changed or is new since the last session

During research:
4. Gather new information using web_search
5. Cross-reference with prior findings to identify updates and changes

Before ending the session:
6. Write updated findings to /mnt/memory/market-intel/recent_findings/{topic}.md
7. Include: date, key findings, sources, what changed from prior session
8. Write a one-sentence summary to /mnt/memory/market-intel/summary/{topic}.md
"""