Persistent Memory for Claude Code Sessions with Recall

Claude Code persistent memory helps when you do not want to re-explain the same project habits in every session. The built-in path starts with CLAUDE.md files for stable instructions and auto memory for local notes Claude Code writes from corrections, workflows, build commands, debugging insights, and preferences. This guide starts there, then covers Recall, a third-party Claude Code plugin by Raiyan Yahya that writes project-local memory files. Recall is not official Anthropic tooling. There is also a separate Recall web-app MCP server for hosted Recall knowledge bases, and the MCP section below explains when that path fits.

Quick comparison: Claude Code memory options

What Claude Code remembers by default

Claude Code sessions start with a fresh context window, and memory systems load at the start of a conversation. Treat memory as context, not hard enforcement.

Use CLAUDE.md for stable project instructions

Use CLAUDE.md for persistent instructions you want Claude Code to see across sessions. Anthropic documents project instruction files at ./CLAUDE.md and ./.claude/CLAUDE.md.

Claude Code reads CLAUDE.md, not AGENTS.md. If you already have an AGENTS.md, CLAUDE.md can import it with @path/to/file. For modular rules, .claude/rules/ can hold instruction files, including path-scoped rules.

# Project instructions

- Run tests with npm test.
- Keep generated memory files out of git.
- Prefer existing helper functions before adding new utilities.

Use auto memory for learned local notes

Claude Code auto memory is built in. It requires Claude Code v2.1.59 or later and is on by default unless toggled with /memory, settings, or CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

The default storage path is ~/.claude/projects/<project>/memory/. The project path is derived from the git repository, so worktrees and subdirectories of the same repo can share memory. Auto memory is machine-local.

Claude Code loads the first 200 lines or 25KB of MEMORY.md, whichever comes first. Topic files are read on demand.

Use slash memory to inspect or change saved notes

Use /memory as the control point for Claude Code auto memory. The memory files are plain Markdown, so you can audit, edit, or delete them directly.

What Recall adds to Claude Code persistent memory

Recall adds a project-local memory layer for Claude Code sessions.

Recall is a third-party Claude Code plugin

Recall is the GitHub repository raiyanyahya/recall, described by its repository as a third-party Claude Code plugin. Its structure matches the Claude Code plugin model because it has .claude-plugin/plugin.json, commands/, and hooks/.

Do not treat the plugin as an Anthropic official feature. The verified setup path for this repo-based memory plugin is the Claude Code plugin marketplace flow from the Recall repository.

Recall stores history and context in .recall

Recall presents itself as fully local project memory for Claude Code. It writes two project-local files under .recall/.

The repository says summarization is local and classical, using TF-IDF sentence vectors, a cosine-similarity graph, and TextRank or PageRank-style scoring. It also says normal use requires no API keys, external model, or pip install.

The Recall web app MCP server is a different path

Model Context Protocol is a standard way for AI applications to connect to external systems and data. The Recall web-app documentation describes a hosted MCP server at https://backend.getrecall.ai/mcp/ for connecting MCP-compatible clients to a Recall knowledge base.

That hosted server is currently read-only. It uses browser-based OAuth and exposes tools to search cards, filter metadata, read document content, and explore the knowledge base. Use it if your context already lives in Recall's web app and you want Claude, ChatGPT, Cursor, Perplexity, or Gemini CLI to search those cards.

That is different from the raiyanyahya/recall Claude Code plugin in this guide. The plugin writes .recall/history.md and .recall/context.md inside a project. Use the plugin commands below for Claude Code session memory. Use the web-app MCP server when you want an assistant to read hosted Recall cards.

Review Recall before you install it

warning

Plugins are highly trusted components. Install Recall only after reviewing the repository, because plugins can run code on your machine with your user privileges.

Check the repository and plugin files

Before installing Recall, inspect the GitHub repository, .claude-plugin/plugin.json, .claude-plugin/marketplace.json, commands/, hooks/, and the privacy policy.

The checked Recall manifest reports name recall, version 0.3.5, author Raiyan Yahya, repository https://github.com/raiyanyahya/recall, and MIT license. The marketplace metadata still says version 0.3.4. Treat version text as something to verify, not as a security decision by itself.

Do not put secrets in long-term memory

Recall's privacy policy says it has no server, account, telemetry, or network connection. It also says Recall reads local Claude Code session transcripts, writes .recall/history.md and .recall/context.md, and keeps small bookkeeping files in the same directory.

The same policy says redaction is best effort and does not guarantee all secrets are removed. Do not store API keys, tokens, private keys, customer data, confidential code excerpts, or regulated data in Claude Code memory or .recall/.

Keep .recall out of git by default

Recall's privacy policy says .recall/ files should be treated like source code and reviewed before sharing or committing. Add .recall/ to .gitignore unless your team has decided to share those files.

.recall/

Set up Recall as a Claude Code plugin

The steps below show the documented install flow. This pipeline did not run Recall in a signed-in Claude Code environment, so treat these as documented commands and checklist steps, not as personally verified runtime results.

Add the Recall marketplace

The Claude Code plugin documentation describes marketplace installation as a two-step process. The /plugin marketplace add command can add a GitHub repository marketplace in owner/repo format.

For Recall, add the repository author's third-party marketplace.

/plugin marketplace add raiyanyahya/recall

Install the Recall plugin

After the marketplace is added, install the Recall plugin from the Recall marketplace.

/plugin install recall@recall

Here, recall@recall means the recall plugin from the recall marketplace.

Configure Recall only if you need to change defaults

The checked recall.config.json template contains this minimal configuration.

{
  "output_dir": ".recall",
  "capture_history": true,
  "summary_sentences": 8,
  "redact": true,
  "include_git": true,
  "max_input_chars": 200000
}

The README also documents auto_save_context with default "off", but that key was not present in the checked config template.

Test that Claude Code remembers project context

Use this as a manual test procedure. The research verified documented commands and repository files, not live Recall runtime behavior.

Create a harmless test note

Use a harmless project fact, not a secret or private customer detail. Ask Claude Code to remember a test phrase.

Remember for this project: test memory with the phrase "blue notebook" and never store secrets in persistent memory.

Save and show Recall context

The Recall README documents these slash commands.

/recall:save
/recall:show
/recall:log

/recall:save runs the local summarizer and overwrites context.md. /recall:show prints context.md. /recall:log tails history.md.

Start a new session and ask for the saved detail

Start a new Claude Code session in the same project and ask for the harmless saved detail. The check passes only if Claude Code can refer to the note through loaded memory or Recall context.

Do not use this test with secrets. The Recall README says it surfaces context.md on SessionStart, captures on Stop and SessionEnd, and can regenerate context manually with /recall:save.

Audit, edit, disable, or delete saved memory

Audit Claude Code auto memory

Open /memory and check ~/.claude/projects/<project>/memory/. The path is derived from the git repository, so worktrees and subdirectories of the same repo can share memory. Auto memory is machine-local.

Audit Recall files before sharing a repo

Inspect .recall/history.md, .recall/context.md, and any bookkeeping files in .recall/ before committing, sharing, zipping, or uploading a project. Treat those files like source code because they may contain details from your sessions.

Remove stale memory safely

Stale memory can push Claude Code toward wrong suggestions. Edit or delete stale Markdown notes, regenerate Recall context with /recall:save, and keep stable project rules in CLAUDE.md instead of relying on remembered conversation details.

Troubleshooting Claude Code memory and Recall

Use documented storage paths and commands first. Avoid inventing extra setup layers when a memory issue is just stale, local, or scoped to the wrong project path.

Claude Code does not remember the project

Check these causes first.

• You are in a worktree or subdirectory and expected a different memory scope.
• Auto memory is disabled through /memory, settings, or CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.
• MEMORY.md is past the first 200 lines or 25KB load limit.
• The relevant detail is in a topic file that is only read on demand.
• You expected auto memory to sync across machines or cloud environments.
• You do not have stable project instructions in CLAUDE.md.

Recall creates files but context feels wrong

Open .recall/context.md and .recall/history.md directly, then compare them with /recall:show and /recall:log. If the context is stale, regenerate it with /recall:save.

Also review summary_sentences. The checked config template uses 8. If you removed sensitive text manually after capture, regenerate context after cleanup so the summary matches the files you intend to keep.

You expected Recall MCP commands

Recall has two paths with similar names. The raiyanyahya/recall plugin in this guide uses Claude Code plugin commands. Recall's web app docs describe a hosted MCP server at https://backend.getrecall.ai/mcp/ for read-only access to a Recall knowledge base.

If your goal is Claude Code session memory inside a repo, use the plugin flow above. If your goal is to let an MCP client search Recall cards, follow Recall's MCP docs and complete the browser OAuth flow. Do not mix the web-app MCP URL into the plugin setup.

When to use built-in memory, Recall, or neither

Use the smallest memory layer that solves the problem.

• Use CLAUDE.md for stable instructions you would be comfortable committing.
• Use auto memory for local habits and recurring project notes.
• Use Recall when you want a project-local session trail and summarized context, and you trust the plugin.
• Use the Recall web-app MCP server when your memory already lives in Recall cards and your client supports custom MCP connectors.
• Use another MCP memory server only when you have reviewed that specific server.
• Use no persistent memory for secrets, regulated data, throwaway experiments, or projects where local history should not be retained.

Persistent memory is context, not a security control or a guarantee that Claude Code will remember perfectly.