recall

recall

Your Claude Code memory, in every agent. recall reads and writes the memory Claude Code keeps for each project, so Codex, Cursor or an agent you build yourself can use the same memories, over MCP or from code. Zero dependencies, no vectors, no database: the memories stay plain Markdown files.

Claude Code now remembers things on its own: your corrections, how you like to work, project decisions, where things live. It saves them as Markdown files with [[wiki-links]] under ~/.claude/projects/ /memory/. That is a good format, but only Claude Code reads it. Switch to another agent and it starts from zero.

recall makes that memory portable. It finds the same directory Claude Code uses (same rules, down to its folder-naming hash), reads every file Claude Code writes, and writes files Claude Code reads back.

Quick start: share it over MCP

Point any MCP client at recall and the project's repository. --read-only lets the other agent read what Claude Code remembers without changing it; leave it off to let both write.

Codex

codex mcp add recall -- npx -y @fainir/recall --claude-code /path/to/your/repo --read-only

Cursor (.cursor/mcp.json in the project, or ~/.cursor/mcp.json)

{

"mcpServers": { "recall": { "type": "stdio", "command": "npx", "args": ["-y", "@fainir/recall", "--claude-code", "/path/to/your/repo", "--read-only"] } } }

Cline: in the MCP Servers panel choose Configure, and add the same recall entry as for Cursor to cline_mcp_settings.json. Or ask Cline to "set up the MCP server from https://github.com/fainir/recall": in a test on 2026-11-01 it read this README, added the entry, started the server and listed its tools.

Gemini CLI: gemini extensions install https://github.com/fainir/recall (it serves the memory of the folder you start Gemini in).

Any other MCP client: run npx -y @fainir/recall with the same arguments as a stdio server. Needs Node.js 18+.

The agent then has these tools. Here is a real run against a repository with three memories Claude Code wrote:

> memory_list

3 memories in /Users/you/.claude/projects/-Users-you-code-acme-api/memory:

• feedback_testing (feedback) - run the integration suite before saying a change works
• reference_ci (reference) - where CI runs and how to rerun a flaky job
• user_role (user) - backend lead, prefers short answers with the command to run

memory_recall {"requires": ["feedback_testing"]}

feedback_testing (feedback) - run the integration suite before saying a change works

Run npm run test:int (needs the local Postgres from docker compose), not just npm test. Why: the unit tests mock the database; two "done" changes broke prod queries. How to apply: any change under src/db/ or src/queries/. CI details in [[reference_ci]].

reference_ci (reference) - where CI runs and how to rerun a flaky job

CI is GitHub Actions, workflow ci.yml. Rerun a flaky job with gh run rerun --failed.

tokens_used: 180

memory_recall followed the [[reference_ci]] link on its own. In testing, a Codex agent given only this server answered a question by calling memory_list and then memory_get.

recall-mcp options: --claude-code [repo] (the default, using the current directory), --dir for any other memory directory (add --format claude-code to write Claude Code's file format there), --read-only, and --allow-secrets. RECALL_DIR, RECALL_READ_ONLY=1 and RECALL_ALLOW_SECRETS=1 work as environment variables.

Use it from code

npm install @fainir/recall

import { Recall } from '@fainir/recall';

const memory = Recall.forClaudeCode('/Users/you/code/acme-api'); console.log(memory.dir);

for (const m of await memory.list()) console.log(m.name, '|', m.type, '|', m.description);

const slice = await memory.recall({ requires: ['feedback-testing'] }); console.log(slice.memories.map(m => m.name), slice.tokens_used);

// Save something Claude Code will see in its next session. await memory.write({ name: 'project_freeze', type: 'project', description: 'merge freeze until the 3rd for the mobile release', body: 'No merges to main until Nov 3. Why: mobile release cut.', });

Output (before the write):

/Users/you/.claude/projects/-Users-you-code-acme-api/memory

feedback_testing | feedback | run the integration suite before saying a change works reference_ci | reference | where CI runs and how to rerun a flaky job user_role | user | backend lead, prefers short answers with the command to run [ 'feedback_testing', 'reference_ci' ] 180

write() produces the file Claude Code itself writes:

---

name: project_freeze description: merge freeze until the 3rd for the mobile release metadata: node_type: memory type: project modified: 2026-10-27T17:51:14.486Z

---

No merges to main until Nov 3. Why: mobile release cut.

and adds a line to MEMORY.md, the index Claude Code loads at the start of every session, leaving the existing lines alone:

- [Testing](feedback_testing.md) - run the integration suite before saying a change works

• CI - where CI runs and how to rerun a flaky job
• Role - backend lead, prefers short answers
• project_freeze - merge freeze until the 3rd for the mobile release

Rewriting an existing memory keeps the fields recall does not own, such as Claude Code's originSessionId.

Where Claude Code keeps the memory

claudeCodeMemoryDir(repo) returns the directory, using Claude Code's rules:

• The project is the git repository root, so subfolders share one memory, and a worktree uses the memory of its main checkout. Outside git, it is the folder itself.
• The folder name is the project path with every character other than a-z, A-Z and 0-9 turned into -. Paths longer than 200 characters are cut and given the same hash suffix Claude Code adds.
• CLAUDE_CONFIG_DIR replaces ~/.claude. CLAUDE_CODE_PROJECT_DIR_NAME (next to CLAUDE_CONFIG_DIR) names the folder. An autoMemoryDirectory setting in the project's .claude/settings.local.json or your ~/.claude/settings.json wins over both.

This was checked against a real ~/.claude/projects folder: the rule reproduced 40 of 41 project folder names, including all three long, hashed ones (the other one belonged to a session that was moved after it started). recall listed and parsed all 194 memory files in it.

API

The package exports the Recall class and claudeCodeMemoryDir(). Every method is async.

A Memory is { name, type, description, updated_at, frontmatter, body, links }. type and updated_at come from the flat fields or from Claude Code's metadata: block, whichever the file has. links lists the memory names the body links to, deduplicated and in order.

write, get and delete throw on an unsafe name; write also throws on an invalid type or decay_class, a non-string body or description, or a reserved extra key. recall never throws on unknown names; it lists them in missing.

Memory file format

One file per memory, .md, with frontmatter and a Markdown body. recall reads both shapes, whichever format you pick for writing.

Claude Code's format (format: 'claude-code'; older Claude Code files have a flat type: instead of metadata:, and recall reads those too):

---

name: feedback_testing description: run the integration suite before saying a change works metadata: node_type: memory type: feedback modified: 2026-10-20T09:12:44.120Z

---

Run npm run test:int first. CI details in [[reference_ci]].

recall's own format (format: 'recall', the default, which earlier versions wrote):

---

name: top-customers type: project description: paying customers above $10K ACV decay_class: slow updated_at: 2026-05-25

---

• Northwind - $48K ACV (see [[northwind-account]])

• Names: a-z, 0-9, - and _, starting with a letter or digit, up to 128 characters. That keeps file names safe on every OS.
• Links: [[name]], [[name|label]] and [[name#heading]] all point at name. They are case-insensitive, - and _ match each other, and links inside code are ignored.
• Frontmatter is a small YAML subset: key: value lines, quoted strings, # comments, and one level of nesting (Claude Code's metadata: block).
• Other files (MEMORY.md, README.md, My Notes.md, folders) are not memories and are skipped.

How recall() picks the slice

1. Every name in requires. No embeddings, no fuzzy search.
2. Every memory reachable through [[wiki-links]] from those, breadth-first, up to link_depth hops.
3. If the total is over budget_tokens (estimated as characters / 4), memories are dropped until