AgentRecall MCP
Local agent memory built on a corrections ledger: tell Claude Code once and a new session reads the rule before it starts work
- 373 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Runs a local Node.js process, and the Claude Code hooks see every user message and commands before publishing or deleting
- Keeps corrections and session journals in ~/.agent-recall files, where sensitive project data may end up
- Semantic search downloads packages and a model when enabled, and cloud embeddings send text to OpenAI when the key is set
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/agentrecallDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Runs a local Node.js process, and the Claude Code hooks see every user message and commands before publishing or deleting
- Keeps corrections and session journals in ~/.agent-recall files, where sensitive project data may end up
- Semantic search downloads packages and a model when enabled, and cloud embeddings send text to OpenAI when the key is set
This is third-party code. Review the repository files before installing.
What it does
AgentRecall is an MCP memory server for AI agents built around a corrections ledger. You tell the agent "never bump the version without asking" and it saves that as a structured record with severity, applicability conditions, evidence and the option to retract. In a new session the record is shown to the agent before its first action, and the server separately counts whether the agent heeded the rule or broke it again. By default the server exposes five tools. session_start loads corrections and watch_for warnings. remember saves a fact and routes it to the journal, a palace room, corrections or awareness. recall searches every store with RRF rank fusion and respects usefulness feedback. check compares a plan with known corrections and returns a blocked verdict when one forbids it. session_end writes the session journal and promotes insights. The --full flag adds check_action, and AR_EXTRAS=1 enables pipeline control and a rule registry. Data sits as plain Markdown on your disk in ~/.agent-recall. In Claude Code the loop can be automated with hooks: they pull in context at start, silently catch corrections in messages, warn before npm publish, git push, rm -rf and DROP TABLE, and save the journal at exit. Beside the MCP there is a skill with the /arstart, /arsave, /arrecall and /arreflect commands, a JavaScript SDK and a CLI. Semantic search through a local model is switched on separately.
Who it is for. For developers who work with Claude Code, Codex, Cursor or Windsurf and tire of repeating the same corrections to an agent in every new session.
Good fit when
- The agent repeats mistakes you already corrected: a version bump without asking, the wrong section first, extra assumptions
- Before a publish, push, deploy or delete you want the agent to check its plan against saved corrections with check
- You need memory in plain Markdown files on disk, with no cloud and nothing sent out
- You run many projects and want a status board of all of them from /arstart
- You want to measure whether the agent heeds a rule: the ledger records heeded and recurred outcomes
Not a fit when
- You want memory with fact search in a cloud database and team-wide sharing: data here is stored locally in Markdown
- You expect the agent to call recall on its own without hooks: the developer reports that such manual calls almost never happened in their measurements
- You need a guarantee that the server catches every correction: the author's measurement on real data captured about a third
- You need zero overhead for tool definitions: the server adds five tools and more with the flags
Example request
Save this as a correction: never bump the package version without my approval. Then show what was saved with recallMCP
- Transport
- stdio
- Authentication
- not required
Environment variables
AGENT_RECALL_EMBEDDINGS- Setting it to 1 enables semantic search through a local model
AR_EXTRAS- With --full it unlocks pipeline control and the rule registry
Limitations
- Node.js is required and the server runs through npx. The automation hooks are described for Claude Code; in other clients memory connects as MCP only.
- The developer publishes candid measurements. Retrieval on the fixture hits the top five 73.1 percent of the time, and 80.8 with local embeddings. The share of heeded corrections on the real stream is currently 0 of 3 events, the starting point after the instrument was reset.
- Semantic search is off by default. Switching it on downloads a local runtime of about 380 MB and a model of about 145 MB, after which search runs without a network.
- Nightly consolidation ("dreaming") needs an active Claude Code login.
- The OpenAI cloud embedding path stays dormant and turns on only when `AGENT_RECALL_CLOUD_EMBEDDINGS=1` and the `OPENAI_API_KEY` key are set together.
How to disable. Remove the server from Claude Code with claude mcp remove agent-recall, and delete the hooks from agent settings by hand. The accumulated memory stays as ordinary files in ~/.agent-recall, which you can keep or delete.
FAQ
How do I install AgentRecall in Claude Code?
Run claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp. For Codex use codex mcp add agent-recall -- npx -y agent-recall-mcp, and for Cursor and Windsurf add a block with the npx command and the arguments -y agent-recall-mcp to mcp.json. Hooks for Claude Code are configured separately.
Where does AgentRecall keep its data?
On your disk, in plain Markdown files in the ~/.agent-recall directory. The developer states that data does not leave the machine. A Supabase mirror is optional. Corrections export in the corrections-export/v1 format, scrubbed on egress.
How is AgentRecall different from Mem0 or Letta?
Typical agent memory stores facts, while AgentRecall keeps corrections as a separate ledger with severity, evidence, retraction and outcome. Beyond retrieval it measures whether the agent's behavior changed in the next session. Storage is local, and the ranking formulas and constants are documented openly.
Why does AgentRecall ship only five tools?
The developer observed across 44 projects that query tools were almost never called on their own. Extra definitions cost tokens every session for no return, so session_start, remember, recall, check and session_end are on by default and the rest is available with --full.
How do I enable semantic search in AgentRecall?
Run ar embeddings setup, then ar embeddings rebuild, and set AGENT_RECALL_EMBEDDINGS=1. Setup downloads a local runtime and the multilingual paraphrase-multilingual-MiniLM-L12-v2 model, after which search works without a network. If the index is missing or corrupt, the server falls back to keyword search.
Discussion
No questions or reviews yet.
Related
MCP serversLocal persistent memory for coding agents: hooks record every session, and Claude Code, Codex or Cursor recall past decisions through 54 MCP tools
Long-term memory for Claude Code, Cursor and Codex: the agent saves decisions and finds them again in later sessions
An MCP server that keeps project decisions in Redis or Valkey and brings them back in new sessions and after compaction.
A long-term memory MCP server for AI agents: facts fade along a forgetting curve and related records are compressed into a summary
Local memory for agents: stores conversations and project files verbatim and retrieves them with semantic search over MCP
ai-memory retains session knowledge in a Markdown wiki, exposes MCP retrieval and passes context between agents and machines.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| AgentRecall (this card) | no | not required | 373 | |
| Hindsight | yes | API key | 59,167 | long-term agent memory: experience and facts the agent retrieves on demand |
| projectmem | yes | not required | 875 | local MCP memory for coding agents: issues, attempts, fixes and decisions |
| TrueMemory | no | not required | 384 | local memory with hooks that record facts from conversations |
README in short
The README explains the problem of repeated corrections and uses a two-session example to show how a rule reaches a new agent. It then walks through the session loop, the tools, five memory layers, the math of ranking and forgetting, measurements including unflattering numbers, a comparison with other memory tools and installation for MCP, skill, SDK and CLI.