Enables AI agents to read and write Claude Code's project memory files to share context across different MCP clients.
Also known as fainir/recall, @fainir/recall
- Stars
- 3
- Tools
- 6
- Downloads, 30 days
- 684
- Latest version
- 0.3.0
- Last commit
- Nov 11, 2026
- License
- MIT
What is recall MCP?
recall enables AI agents to read and write Claude Code's project memory files to share context across different MCP clients. It exposes 6 tools, such as memory_list, memory_get, memory_recall.
Summary generated from the project's README
About recall MCP server
Recall enables AI agents to access and manage the project memory files created by Claude Code. While Claude Code stores project decisions, user preferences, and technical context in Markdown files, these memories are typically isolated to that specific tool. This server makes that information portable, allowing other MCP clients like Cursor, Codex, Cline, or Gemini CLI to read and write to the same memory directory.
Users can connect the server to their local repositories using the --claude-code flag or point it to specific directories. It operates as a stdio server and supports a read-only mode to prevent external agents from modifying existing records. The system uses plain Markdown files with wiki-links instead of complex databases or vector stores, ensuring the data remains human-readable and lightweight. Developers can use the provided Node.js library to integrate these memory capabilities directly into their own custom applications.
What you can do with it
- 1Share context across different agentsAn AI agent can access the same project memories previously recorded by Claude Code to maintain continuity.
- 2Retrieve linked project documentationA developer can ask an agent to recall a specific memory and automatically follow its internal wiki-links to gather related context.
- 3Prevent accidental memory modificationYou can configure the server in a read-only state so that secondary agents can view project history without altering it.
- 4Automate memory management via codeDevelopers can use the Recall class to programmatically list, write, or delete project memories within their own software.
Written from the project's README. Every use case is checked against a quote from it.
How to install recall MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall recall MCP in Claude Code
$ claude mcp add recall -- npx -y @fainir/recallInstall recall MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"recall": {
"command": "npx",
"args": [
"-y",
"@fainir/recall"
]
}
}
}Install recall MCP in VS Code
.vscode/mcp.json
{
"servers": {
"recall": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@fainir/recall"
]
}
}
}Install recall MCP in VS Code CLI
$ code --add-mcp '{"name":"recall","type":"stdio","command":"npx","args":["-y","@fainir/recall"]}'Install recall MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"recall": {
"command": "npx",
"args": [
"-y",
"@fainir/recall"
]
}
}
}Install recall MCP in Codex
$ codex mcp add recall -- npx -y @fainir/recallInstall recall MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.recall] command = "npx" args = ["-y", "@fainir/recall"]
Install recall MCP in Gemini CLI
$ gemini mcp add -s user recall npx -- -y @fainir/recallInstall recall MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"recall": {
"command": "npx",
"args": [
"-y",
"@fainir/recall"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @fainir/recall 0.3.0 in an isolated container with no network and no keys. It answered and listed 6 tools.
recall MCP tools 6
Read from the server with tools/listmemory_listRead-onlyList every saved memory with its type and one-line description. Start here to see what is known.
memory_getRead-onlyRead one memory in full. Names match file names; "-" and "_" are interchangeable.
memory_recallRead-onlyRead the named memories plus the memories they link to with [[wiki-links]], trimmed to a token budget. Unknown names are reported as missing instead of failing.
memory_dueRead-onlyList memories old enough that they should be re-confirmed with the person before being relied on.
memory_writeActionSave a memory, or replace the one with the same name. One fact per memory. Save only what a future session could not work out from the code or git history. Never save secrets. Link related memories in the body with [[name]]. user: who the person is and how they like to work. feedback: corrections and confirmed approaches. project: ongoing work, decisions and deadlines not in the code. reference: where to find things outside the project.
memory_deleteActionDelete a memory that turned out to be wrong or obsolete. Exact name only.
Configuration
RECALL_READ_ONLYSet to 1 to expose read-only tools
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubrecall
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/<project>/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
Try it with sample notes
Run this in Bash or Zsh with Node.js 18 or newer. It creates two temporary notes, asks the read-only MCP server to recall the review note named in requires, and follows its link to checks.
(
sample_dir=$(mktemp -d "${TMPDIR:-/tmp}/recall-demo.XXXXXX") || exit
trap 'rm "$sample_dir/review.md" "$sample_dir/checks.md"; rmdir "$sample_dir"' EXIT
printf '%s\n' 'Before merging, follow [[checks]].' > "$sample_dir/review.md"
printf '%s\n' 'Run the focused test before merging.' > "$sample_dir/checks.md"
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"recall-demo","version":"1"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"memory_recall","arguments":{"requires":["review"]}}}' |
npx -y @fainir/recall@0.3.0 --dir "$sample_dir" --read-only
)
In the last JSON response, result.content[0].text contains both Before merging, follow [[checks]]. and Run the focused test before merging. The second line comes from the linked note. Use the setup below to connect your own project.
Connect your project
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.
| Tool | What it does |
|---|---|
memory_list |
Every memory with its type and one-line description. Optional type filter. |
memory_get |
One memory in full. feedback-testing and feedback_testing both work. |
memory_recall |
The named memories plus the ones they [[link]] to, trimmed to a token budget. Unknown names come back as missing. |
memory_due |
Memories old enough to re-confirm before relying on them. |
memory_write |
Save or replace a memory in Claude Code's format, and add it to the MEMORY.md index. Not offered with --read-only. |
memory_delete |
Delete a memory and its index line. Not offered with --read-only. |
recall-mcp options: --claude-code [repo] (the default, using the current directory), --dir <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](reference_ci.md) - where CI runs and how to rerun a flaky job
- [Role](user_role.md) - backend lead, prefers short answers
- [project_freeze](project_freeze.md) - 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-Zand0-9turned into-. Paths longer than 200 characters are cut and given the same hash suffix Claude Code adds. CLAUDE_CONFIG_DIRreplaces~/.claude.CLAUDE_CODE_PROJECT_DIR_NAME(next toCLAUDE_CONFIG_DIR) names the folder. AnautoMemoryDirectorysetting in the project's.claude/settings.local.jsonor your~/.claude/settings.jsonwins 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.
| Call | Arguments | Returns |
|---|---|---|
Recall.forClaudeCode(repo) |
path inside a project; default the current directory | a Recall on Claude Code's memory directory, in claude-code format |
new Recall({ dir, format }) |
dir: memory directory. format: recall (default) or claude-code |
a Recall instance |
write({ name, type, description, decay_class, body, extra }) |
name: slug (required). type: user | feedback | project | reference (required). description: one line, default ''. decay_class: permanent | slow | fast | ephemeral, default slow. body: Markdown, default ''. extra: more frontmatter fields |
{ name, type, decay_class, updated_at }. Creates or replaces <dir>/<name>.md; in claude-code format also updates MEMORY.md |
get(name) |
a memory name; - and _ are interchangeable, and a frontmatter name also matches |
a Memory, or null |
list({ type }) |
optional type filter |
Memory[], sorted by name |
recall({ requires, link_depth, budget_tokens }) |
requires: names. link_depth: [[link]] hops to follow, default 1. budget_tokens: default 2000 |
{ memories: Memory[], tokens_used, missing: string[], dropped: string[] } |
dueForReview(asOf) |
Date or date string, default now |
Memory[] past their review window, each with age_days |
delete(name) |
exact memory name | true if a file was removed, false if it did not exist |
claudeCodeMemoryDir(repo) |
path inside a project | the directory path (it may not exist yet) |
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, <name>.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 atname. They are case-insensitive,-and_match each other, and links inside code are ignored. - Frontmatter is a small YAML subset:
key: valuelines, quoted strings,# comments, and one level of nesting (Claude Code'smetadata:block). - Other files (
MEMORY.md,README.md,My Notes.md, folders) are not memories and are skipped.
How recall() picks the slice
- Every name in
requires. No embeddings, no fuzzy search. - Every memory reachable through
[[wiki-links]]from those, breadth-first, up tolink_depthhops. - If the total is over
budget_tokens(estimated as characters / 4), memories are dropped until it fits: the deepest links first, so the required memories go last; at the same depth,ephemeralfirst, thenfast,slow,permanent. Their names come back indropped, and the rest keep their walk order.
For an agent that knows what it needs, explicit keys beat similarity search: asking for "voice" should return the voice memory, not four memories that mention the word.
Decay
decay_class says how often a memory should be re-confirmed. dueForReview() returns the ones whose last update (Claude Code's modified, or recall's updated_at) is older than their window. Nothing is deleted automatically.
decay_class |
Due for review after |
|---|---|
permanent |
730 days |
slow (default) |
90 days |
fast |
30 days |
ephemeral |
7 days |
Limitations
- Privacy: serving Claude Code's memory to another agent sends those memories to that agent's model provider. Use
--read-onlyand point it only at projects you are happy to share. - Secrets: a memory can capture a credential from a debugging session. Before a memory leaves the server, recall replaces recognisable secrets with
[redacted]: passwords in connection URLs, bearer tokens, private key blocks, and Anthropic, OpenAI, GitHub, Slack, AWS, Google and Stripe keys, plus JWTs, and says how many it hid. The files on disk are not changed.--allow-secretsturns this off. It is a safety net for known formats, not a guarantee: keep secrets out of memories. - Claude Code reads
MEMORY.mdat the start of a session, so a memory another agent writes shows up in Claude Code's next session, not the current one. Claude Code loads only the first 200 lines (or 25 KB) of that index. - Writes are atomic (temp file + rename), but the last writer wins. There is no locking between recall and a running Claude Code session.
- Auto memory is per machine. recall does not sync it anywhere.
- The token count is an estimate (characters / 4), not a tokenizer.
Development
No dependencies, so there is nothing to install:
git clone https://github.com/fainir/recall.git
cd recall
npm test # node:test, no network
node examples/basic.js # the library on a plain recall directory
License
More open source by Nir Feinstein
- agent-harness - make Claude Code or Codex act as a product team, a CEO or a portfolio manager
- frugal - your agent finds the cheaper honest way before it pays for anything
- flipback - an automatic
/goalfor every turn: sends Claude Code back when it stops early - most-capable-agent-system-prompt - the copy-paste prompt for a self-improving agent system
- All projects
recall MCP questions
How do I add recall MCP to Claude Code?
Run claude mcp add recall -- npx -y @fainir/recall in your terminal. Add --scope user to make it available in every project.
How do I add recall MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does recall MCP provide?
It exposes 6 tools, including memory_list, memory_get, memory_recall, memory_due, memory_write.
What is recall?
It is a tool that makes Claude Code's project memory portable by reading and writing the Markdown files it uses, allowing other agents like Cursor or Codex to access the same context.
Does recall require a database?
No, it has zero dependencies and uses plain Markdown files for storage instead of vectors or databases.
Can I use recall in read-only mode?
Yes, you can use the --read-only flag to let other agents read Claude Code's memories without being able to change them.