recall
Your Claude Code memory, in every agent. Read and write Claude Code's auto memory over MCP (Codex, Cursor, ...) or from code. Markdown + wiki-links, zero dependencies.
Install / Use
claude mcp add fainir -- npx -y github:fainir/recallIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
AI & Machine LearningSupported Platforms
Tags
Our assessment of recall
recall scores 83/100 on our quality scale, 660th of 947 AI & Machine Learning skills we index.
Its MCP Server is 16 KB long, well organised into 16 sections with 12 code examples: a thorough specification that gives an agent plenty to work with.
It has 3 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated 5 days ago, so recall is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 92/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-11-15. Automated pattern scan on 2026-11-15. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
recall compared with similar skills
All 4 of these similar skills score higher than recall; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| recall (this skill)by fainir | 83 | 3 | 5d ago | MCP Server |
| claude-memby thedotmack | 100 | 117.6k | today | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| Understand-Anythingby Egonex-AI | 100 | 92.8k | 1d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
Frequently asked questions
- How do I install recall?
- Run
claude mcp add fainir -- npx -y github:fainir/recall. The install tabs above show the steps for each supported agent. - Which AI agents does recall work with?
- It is written for Claude Code, Claude Desktop, Cursor, Gemini CLI and OpenAI Codex, as a MCP Server file. Other agents that read the same format can often use it too.
- Is recall safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 92/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is recall still maintained?
- The repository was last updated 5 days ago, so recall is actively maintained.
Skill content
View source 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.
<p align="center"> <img src="assets/demo.png" width="860" alt="Codex calling recall: memory_list shows three memories Claude Code wrote, then memory_recall returns feedback_testing and follows its [[reference_ci]] link on its own, in 180 tokens."> </p>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: f
Truncated for display — read the full file on GitHub.
Related Skills
claude-mem
117.6kPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
Understand-Anything
92.8kGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
