Claude Agent SDK Memory: How SDK Agents Remember

The Claude Agent SDK runs the same agent loop as Claude Code inside your own Python or TypeScript program. Developers who build on it soon ask what the agent remembers between runs. The SDK has three memory mechanisms with different lifetimes. Sessions store the conversation, while CLAUDE.md holds the rules you write. Auto memory is where Claude keeps notes for itself. The Claude API adds a fourth option outside the SDK: a memory tool backed by your own storage.

What is Claude Agent SDK memory, in one sentence?

Claude Agent SDK memory is the set of files the SDK keeps so an agent can carry context past one query: session transcripts plus instruction and memory files.

The SDK itself is a library that "runs the Claude Code binary," per Anthropic's Agent SDK overview. Your code gets Claude Code's built-in tools plus its hooks and sessions. Anthropic renamed it from the Claude Code SDK on September 29, 2025, because the harness was already used for work beyond coding. The packages are now @anthropic-ai/claude-agent-sdk for TypeScript and claude-agent-sdk for Python, per the migration guide.

How do the SDK's memory mechanisms compare?

Sessions record what happened in one conversation. CLAUDE.md sets the rules for a project, and auto memory keeps what Claude learned there. The memory tool puts that kind of learning in storage you run.

Sessions and CLAUDE.md come from the sessions guide and the guide to Claude Code features in the SDK. Auto memory is from the Claude Code memory docs. The last column is from the memory tool docs.

How do sessions work in the Claude Agent SDK?

A session is the conversation history the SDK builds while your agent works. It holds your prompt plus every tool call and its result. The SDK writes it to disk on its own. Anthropic's sessions guide is explicit that sessions persist "the conversation, not the filesystem." To roll back file edits, you need file checkpointing.

You get three ways back into a session. Continue picks up the most recent session in the current directory, with no ID to track. Resume takes a specific session ID, which you read from the result message. That is the right choice for a multi-user app with one session per user. Fork copies a session's history into a new session, so you can try another approach and keep the original intact.

In Python, ClaudeSDKClient keeps one session alive across several queries in the same process. In TypeScript, you pass continue: true on each later query() call. If you want nothing written to disk, the TypeScript option persistSession: false keeps the session in memory only.

Transcripts live under ~/.claude/projects/ in a folder named after the working directory. They are local to the machine that created them. For serverless or autoscaled deployments, the SDK accepts a SessionStore adapter. It mirrors transcripts to your own backend, and Anthropic ships reference adapters for S3, Redis and Postgres. The SDK never deletes from your store, so retention is your job.

A resumed session holds one conversation's history and nothing from other threads. The transcript also gets compacted as it grows: the session storage docs show a store holding 503 raw entries that returns 18 messages after auto-compaction. For anything that must outlive one thread, the guide's own advice is to capture results as application state and pass them into a fresh session.

How do CLAUDE.md and auto memory load in an SDK agent?

When you omit the settingSources option, query() reads the same filesystem settings as the Claude Code CLI. The features guide says that covers the settings files and CLAUDE.md. It also covers anything in .claude/ such as skills. Pass an empty list to turn that off and configure the agent only in code.

SDK v0.1.0 briefly loaded no filesystem settings before Anthropic reverted the change. The migration guide also warns that Python SDK 0.1.59 and earlier treated an empty list the same as omitting the option. Upgrade before you rely on it for isolation.

CLAUDE.md files are instructions you write. The project source loads CLAUDE.md and .claude/rules/*.md from the working directory and every parent directory. The user source loads ~/.claude/CLAUDE.md. All levels add up, and the docs say there is "no hard precedence rule" when two files conflict.

Claude writes auto memory itself, and it loads even when settingSources is empty. Per the memory docs, Claude saves four kinds of notes: user preferences, feedback and corrections, project decisions it cannot derive from the code, and pointers to outside references. Each project gets a folder under ~/.claude/projects/ with a MEMORY.md index and one file per memory. The first 200 lines or 25KB of the index load at the start of every session. The SDK has no dedicated memory tool for this, so Claude needs the Write and Edit tools enabled to save anything.

Auto memory is machine-local, and its files are not shared across machines or cloud environments. Anthropic also warns against relying on default options for multi-tenant isolation. Its advice is to give each tenant its own filesystem and an empty settingSources. Then switch off auto memory with this variable:

CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

When should you use the API memory tool instead?

The memory tool belongs to the Claude API, not the Agent SDK. You add it to a Messages API request with the tool type memory_20250818. Claude then checks a /memories directory before it starts a task and records what it learns as it works. The tool runs client-side: Claude asks for view, create, str_replace, insert, delete or rename, and your code performs the operation against storage you control.

That makes it the better fit when you write your own tool loop with the Client SDK and need memory in a database or a per-user bucket. Agent SDK users already get similar coverage from auto memory and CLAUDE.md as plain files. The Python and TypeScript client SDKs ship a local-filesystem implementation to start from. You own the security work. The docs require path validation on every command, because a path like /memories/../../secrets.env can escape the directory. They also suggest size caps and expiring files nobody has read in a long time.

What are the gaps for SDK agents in production?

None of these mechanisms crosses machines on its own. Auto memory stays in a local folder. Sessions need a SessionStore adapter to move, and the memory tool needs a handler you write.

Scope is the second gap. All four belong to Claude, so a team running SDK agents next to Codex or Cursor keeps separate stores. Each store relearns the same project facts.

Defaults are the main production risk. Loading user settings is convenient on a laptop. On a server, a process can pick up host-level configuration and per-directory memory unless you switch them off.

The bottom line

Use sessions to continue or branch one conversation. Use CLAUDE.md for rules a human owns and auto memory for what Claude learns on a single machine. Reach for the API memory tool when you run your own loop and need memory in your own storage. On multi-tenant servers, give each tenant its own filesystem and an empty settingSources, and turn auto memory off.

How do you share what an SDK agent learns with your other coding agents?

The Agent SDK's memory is tied to Claude and, for auto memory, to one machine. A preference you corrected in an SDK agent on a CI runner never reaches Claude Code on your laptop. It does not reach Codex either. Session transcripts hold the raw history, but they get compacted and stay local unless you build an adapter.

memU keeps memory as a shared wiki of readable Markdown that follows you across agents and devices. Each host adapter hooks memU in at two points. A scheduled background task slices new session logs into jobs that the agent distills into memory and skill Markdown. A standing instruction in CLAUDE.md or AGENTS.md tells the agent to retrieve before it answers.

memU itself makes no LLM calls. It only stores and retrieves the Markdown the agent prepared, with embeddings for search. All hosts share one backend, so what Codex learned is available to Claude Code. Check the support matrix before you point it at an agent built on the SDK.

To try the hosted version, which is free and syncs across devices, get an API key from memu.so and send your agent one message:

Read https://memu.pro/SKILL.md, follow its instructions to install and configure memU, API Key is YOUR_MEMU_API_KEY.

The self-hosted setup and the support matrix are in the memU GitHub repository.

FAQ

Does the Claude Agent SDK have memory?

Yes, in three built-in forms, plus the separate API memory tool. Sessions store each conversation as a transcript you can resume or fork. CLAUDE.md files and auto memory carry instructions and learned notes into every new session.

Where does the Claude Agent SDK store sessions?

In JSONL files under ~/.claude/projects/, in a folder named after the working directory. Set CLAUDE_CONFIG_DIR to move them, or attach a SessionStore adapter to mirror them to your own backend.

Does the Agent SDK load CLAUDE.md by default?

Yes. When you omit settingSources, the SDK loads the same settings and CLAUDE.md files as the Claude Code CLI. Pass an empty list to disable them.

Is the memory tool part of the Claude Agent SDK?

No. The memory tool is a Claude API tool with the type memory_20250818, and your application executes its file operations. SDK agents save memories through auto memory with the regular Write and Edit tools.

How do I stop an SDK agent from sharing memory between tenants?

Give each tenant its own filesystem and pass an empty settingSources. Then set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Anthropic notes that server-managed settings still load when the process authenticates with an organization credential.