Claude Code

Persistent memory for Claude Code

Q: Does Claude Code remember between sessions?

Partly. Claude Code loads your CLAUDE.md files and its own auto-memory notes at the start of every session, and claude --resume reopens an earlier conversation. What it doesn't keep is a running record of where the work stands: the goal, what the last turns did and whether they worked. Crosshead saves that through Claude Code's hooks and adds it to the next session in the same repository.

Q: Should I still keep a CLAUDE.md?

Yes. CLAUDE.md is the right place for stable instructions: build commands, conventions, things that are true every session. Crosshead tracks the changing state of the work, which goes stale too fast to maintain by hand. Our eval compares automatic memory with written handoffs, including a smaller pilot that updates notes only when relevant facts change.

Q: What happens to memory when Claude Code compacts the conversation?

/compact replaces the conversation with a summary, and detail is lost. Crosshead hooks PreCompact and PostCompact and saves working state immediately on both, so the state from before compaction is still available on the next prompt.

Q: Is it per project or global?

With --workspace-root "$PWD" the hooks go into that project's .claude/settings.json. Without it they go into your user-level ~/.claude/settings.json and run in every project. Either way, memory is kept separately for each repository.

Q: Where is my memory stored?

Your agent's private key stays on your machine, in ~/.onlybots with owner-only file permissions. Memory is stored by the Crosshead service so it can follow the agent between machines and tools; the service reads it to build context. To have hosted memory deleted, email josh@crosshead.sh from the address you'd like us to reply to, with your agent's npub.

Every new Claude Code session re-reads the repository and asks you to re-explain where things stand. Crosshead saves the working state of each session through Claude Code's own hooks and puts it back in front of the next one.

Install for Claude Code How it compares to CLAUDE.md and --resume

Install

Set up in your project

Run these from the root of the repository you work in. Quickstart creates your agent's identity, installs the Claude Code hooks, starts the local daemon and checks the connection.

Install the CLI
```
curl -fsSL https://crosshead.sh/install | bash
```
Needs Node.js 22+, npm, curl and tar on macOS or Linux. The installer verifies the release checksum before unpacking; read the script first if you prefer.
Put it on your PATH
```
export PATH="$HOME/.onlybots/bin:$PATH"
```
Add the same line to your shell profile to keep it.
Connect Claude Code
```
crosshead quickstart --api-base https://crosshead.sh --adapter claude-code --workspace-root "$PWD"
```
Then start Claude Code as usual. From the second session on, each prompt arrives with a short summary of where the work stands.
Check it
```
crosshead status
crosshead doctor
```
After a restart, run crosshead start to bring the daemon back.

Continue the work

Resume a session or start fresh · Keep requirements through compaction · Carry context into Codex

Under the hood

What the hooks do

Quickstart registers five standard Claude Code hooks. Each one calls the Crosshead daemon on your machine.

Hook	What Crosshead does
`SessionStart`	Attaches the session to this repository's memory, on startup, resume and after compaction.
`UserPromptSubmit`	Adds a compact context pack (about 360 tokens at most) with the current goal, recent turns and how the last session ended.
`Stop`	Records what the turn did and whether it succeeded, and saves the updated working state.
`PreCompact` / `PostCompact`	Saves working state immediately, so compaction doesn't erase it.

Set how much the agent saves with crosshead memory mode off|manual|assist|auto. The default, assist, also runs a reflection step after each turn. Remove everything with crosshead uninstall claude-code.

Compared

What Claude Code already remembers, and what it doesn't

Crosshead works alongside Claude Code's own memory. Each tool below keeps something different.

Feature	What it keeps	Who writes it	New session?	Codex?
`CLAUDE.md`	Instructions and conventions	You	Yes	No; Codex reads `AGENTS.md`
Auto memory	Notes Claude chooses to save	Claude	Yes	No
`--resume`	One past conversation, in full	Automatic	Only that conversation, reloaded whole	No
`/compact`	A summary of the current conversation	Claude	No	No
Crosshead	Goal, recent turns and outcomes, where the last session ended	Hooks, every turn	Yes, every session in the repo	Yes

Also using Codex?

Working state is kept per agent, not per tool. Install the Codex adapter under the same profile and a Codex session in the same repository picks up where Claude Code left off. For an explicit transfer, export a signed handoff from one and import it in the other.

Codex setup and handoffs →

Does it save anything?

In our October 2026 regression suite, Crosshead passed 48/48 trials on Claude Opus 5.5, matching written handoffs while using 21.5% fewer tokens and costing 29.1% less. The handoff control wrote a note at every boundary. Native resume was cheaper; a smaller compaction pilot tests update-only handoffs separately.

Method, data and limits →

FAQ

Claude Code memory questions

Does Claude Code remember between sessions?

Partly. Claude Code loads your CLAUDE.md files and its own auto-memory notes at the start of every session, and claude --resume reopens an earlier conversation. What it doesn't keep is a running record of where the work stands: the goal, what the last turns did and whether they worked. Crosshead saves that through Claude Code's hooks and adds it to the next session in the same repository.

Should I still keep a CLAUDE.md?

Yes. CLAUDE.md is the right place for stable instructions: build commands, conventions, things that are true every session. Crosshead tracks the changing state of the work, which goes stale too fast to maintain by hand. Our eval compares automatic memory with written handoffs, including a smaller pilot that updates notes only when relevant facts change.

What happens to memory when Claude Code compacts the conversation?

/compact replaces the conversation with a summary, and detail is lost. Crosshead hooks PreCompact and PostCompact and saves working state immediately on both, so the state from before compaction is still available on the next prompt.

Is it per project or global?

With --workspace-root "$PWD" the hooks go into that project's .claude/settings.json. Without it they go into your user-level ~/.claude/settings.json and run in every project. Either way, memory is kept separately for each repository.

Will Crosshead ever block or slow down Claude Code?

Hook errors are caught and logged as warnings, and the hook exits cleanly, so Claude Code carries on. If the local Crosshead daemon isn't running, the hooks do nothing; start it with crosshead start.

Where is my memory stored?

Your agent's private key stays on your machine, in ~/.onlybots with owner-only file permissions. Memory is stored by the Crosshead service so it can follow the agent between machines and tools; the service reads it to build context. To have hosted memory deleted, email josh@crosshead.sh from the address you'd like us to reply to, with your agent's npub.