Claude Code does not remember your last session on its own. Each session starts with a fresh context window, so anything it needs again has to be written somewhere it reads at startup. Claude Code has two built-in ways to do that: CLAUDE.md files that you write, and auto memory, which Claude writes for itself. For one person on one machine, those two are often enough. A shared store, such as the one in agent-memory, is for when they are not.
How are you handling agent memory?
Developers ask this in forums such as r/LLMDevs, and the answers split into two camps. One keeps a plain folder of notes that the agent reads with ls and grep. The other adds a retrieval layer, usually embeddings or a graph, that finds the right note for a question. Plain files stop being easy to search once the folder grows. A retrieval engine finds things, but its index is often something you cannot read or move.
Claude Code's built-in memory sits in the first camp, with one addition. Anthropic's memory documentation says both CLAUDE.md files and auto memory load at the start of every conversation, and that Claude treats them as context, not enforced configuration. If a rule must hold every time, the same page points to a PreToolUse hook instead.
| CLAUDE.md files | Auto memory | |
|---|---|---|
| Who writes it | You | Claude |
| What it holds | Instructions and rules | Learnings and patterns from your corrections |
| Scope | Project, user or organization | Per repository, shared by its worktrees |
| When it loads | Every session | Every session, the first 200 lines or 25KB of its index |
| Use it for | Coding standards, workflows, project architecture | Your preferences and project context Claude cannot read from the code |
Does Claude Code remember anything between sessions?
Yes, but only what lands in those two places. Auto memory is on by default in local sessions. Claude keeps its notes in a directory for each project, under ~/., with a MEMORY. index and one file per memory. The documentation describes four note types: user, feedback, project and reference. You can browse and edit them with /memory, and they are plain Markdown.
Two limits matter in practice. Only the first 200 lines or 25KB of MEMORY. load at session start; anything past that is dropped on the next load, which is why the docs ask Claude to keep the index short and move detail into topic files. And auto memory is machine-local. It does not follow you to another laptop or a cloud environment.
Is CLAUDE.md enough to remember my project?
For standing rules, yes. Write down what you would otherwise explain again each time: build commands, conventions, the layout of the project and "always do X" rules. The docs also say that short, specific instructions are followed more consistently than long ones, so a file that grows without limit works against you.
CLAUDE.md is weak at state. You maintain it by hand, and it drifts the moment you stop editing it. What was the last decision? Which branch is in progress? Which bug is still open? Those belong in a memory written as the work happens, not in a rules file. The same documentation says a multi-step procedure belongs in a skill rather than in CLAUDE.md, and autoharness, another Tigerless Labs project, is built around that kind of skill for Claude Code. So the split that works is this: rules in CLAUDE.md, procedures in skills, and what you learn along the way in memory.
How do I make Claude Code and Codex share one memory?
The built-in files cannot do it. Auto memory belongs to Claude Code, and Codex reads its own instructions. If you use both tools on one project, you end up keeping two sets of notes that drift apart.
agent-memory is a Tigerless Labs open-source project: one store of plain Markdown files that Claude Code and Codex CLI share. The store has a root MEMORY. index, one file per memory placed by its type, and an archive kept out of normal retrieval. Writes happen at conversation boundaries through a hook: at session start the index is injected, and at session end the session is distilled into memory files. The read path calls no model and no network service. There is no API key. The judgement that turns a session into a memory comes from the host agent's own CLI, so the work runs inside the tool you already use, and each write is visible in its transcript. If you also want to see what a Claude Code or Codex session sends to the API, cost-xray is the Labs project for that, and it does not change what the agent does.
The Labs page for agent-memory sets out the design. The short version: files are the truth, and every index is a cache you can delete and rebuild.
How do I set it up?
You need Python 3.12 or newer and uv. The project has no PyPI release yet, so you install from a checkout of the GitHub repository, which is MIT licensed. Then:
- Install Python 3.12 or newer and uv.
- Clone github.com/tigerless-labs/agent-memory and run uv sync --all-packages inside the checkout.
- Add the checkout's virtual environment to your PATH with export PATH="$PWD/.venv/bin:$PATH".
- Run mem init to create the store.
- Run mem setup --host claude-code, or --host codex for Codex CLI.
Setup adds its hook to the host and leaves the rest of your settings alone. Session start injects the index and session end distils the session. Once the store has memories, you can search it from the shell:
mem recall "why files instead of a database"
mem read <name> --level outline
mem context "why files instead of a database"Agents that speak MCP get the same core calls through mem-mcp. Anything that can run a shell command can use the mem CLI directly.
How does recall keep the context small?
Recall does not paste memories into the context. It returns a short list of hits, each with a one-line abstract, a file path, an anchor and a score. The agent opens a hit only as deep as the task needs, in rungs: the index line, the abstract, the outline, the full file, and finally the raw messages the memory was distilled from, read with mem trace. Each rung costs more context than the one before, and each is a place to stop. Most questions end at the abstract.
The files stay the truth throughout. If the index ever seems wrong or slow, delete it and rebuild it with rm -rf .. A rebuild loses no knowledge, because the index is derived from the Markdown files. Consolidation runs on its own schedule, in a sleep-time pass that may add and update memories without you. Deletion only arrives as a proposal you confirm.
When is built-in memory enough?
Often. If you use only Claude Code, on one machine, and your memory is a handful of project rules and preferences, the built-in files need no setup, and Claude keeps auto memory up to date itself. agent-memory adds a hook, a checkout to update and a store to back up. It is an early project, installed from source, and that is a real cost for a small need.
The case for a shared store is narrower. It fits when Claude Code and Codex work on the same project, when you want memory you can grep, diff and commit, or when the same memory has to reach more than one machine, since auto memory does not cross machines. If none of those apply, use the built-in files and skip the store. A memory that nobody maintains is worse than a short CLAUDE.md that someone does.
Two caveats about agent-memory itself. It is not a hosted service, so backups, syncing between machines and the store's location are yours to manage. And its published evaluation measures a write strategy on a bounded set of episodes, not on your own sessions, so read any accuracy figure as a result for that setup and check it against your own work before you rely on it.
Conclusion
Claude Code keeps rules in CLAUDE.md and its own notes in auto memory. Both load at the start of every session, both stay on one machine, and both serve one person working in one tool well. Put the rules in CLAUDE.md, keep procedures in skills, and move to a shared store when two agents or two machines need the same memory. The right setup is the one where a new session can answer "what was I doing last time?" without you retyping it.
Try the built-in files for a week. If you find yourself copying the same notes between tools, install agent-memory from its repository and run mem setup for the host you use most. Its design and install steps are on the agent-memory page, and the other Labs projects are listed beside it. For a close look at what a Claude Code session sends to the API, see our article on cost-xray.
FAQ
Does Claude Code's auto memory need any setup?
No. It is on by default in local sessions. You can turn it off from the auto memory toggle in /memory, or with the autoMemoryEnabled setting for one project, and you can browse the notes with /memory at any time.
Where does Claude Code keep auto memory?
In a directory for each project under ~/.claude/projects/. The directory name comes from the git repository, so every worktree and subdirectory in one repository shares it. Outside a git repository, the project root is used instead.
Can I share Claude Code memory between two computers?
Not with auto memory, which is machine-local. You can keep a store of plain Markdown files in a git repository and pull it on the other machine. agent-memory's files are designed to be greppable, diffable and committed.
Does agent-memory need an API key?
No. It has no LLM client inside. The judgement that writes a memory comes from the host agent's own CLI, so there is no separate key to set up.
Is agent-memory a hosted service?
No. It is a local tool that you install from its GitHub repository under the MIT license. It needs no Tigerless account, and nothing in the read path calls a model or the network.
