agentic-recall

Long-term memory for agentic tasks. It tells you when it doesn't know.

An MCP server that gives Claude Desktop and Claude Code a persistent memory across sessions — and, unlike a plain vector store, an explicit answer when the corpus does not contain what you asked for.

// ~/.claude.json  (Claude Code)  or  claude_desktop_config.json  (Claude Desktop)
"mcpServers": {
  "memory": {
    "command": "npx",
    "args": ["-y", "agentic-recall@2"],
    "env": { "MEMORY_DIR": "/absolute/path/to/your/memory/folder" }
  }
}

That is the whole install. MEMORY_DIR is the one path you supply, and that is deliberate: the server does not go looking through your disk for your notes.

🟥 Note the @2 — pin the major version. npx -y agentic-recall with no version asks npm for whatever is tagged latest every time its cache is cold, so a new major arrives silently and a config that worked yesterday breaks today. That is not hypothetical: 2.0.0 moved five actions to a second tool, and a tester's in-flight session started failing with received 'index' at action mid-task — because npx had re-resolved latest underneath a running workflow. The cache is what makes an unpinned spec feel stable, and a cache is not a pin: it is cleared by npm cache verify, by disk cleanup, and by every new machine.

@2 takes fixes and features, never a breaking major. agentic-recall@2.0.0 pins exactly.

🟥 A warm npx cache does NOT pick up a fix on its own. Measured 2026-09-22: 2.0.3 had been on the registry for over an hour, and three servers spawned with npx -y agentic-recall@2 still ran the cached 2.0.1. To take a fix, clear the cached copy and re-resolve once — macOS/Linux: rm -rf ~/.npm/_npx && npx -y agentic-recall@2 --version; Windows: the Remove-Item line below — then restart your client. serverVersion in every response tells you which version actually answered.

🟥 Windows users: use this config instead. Bare npx does not work for a Node MCP client on Windows. This is measured, not inferred — CI spawns the published package on windows-latest every push, and reports bare npx -> FAILED: spawn npx ENOENT while cmd /c npx connects:

json

Copy

"memory": {
  "command": "cmd",
  "args": ["/c", "npx", "-y", "agentic-recall@2"],
  "env": { "MEMORY_DIR": "C:/Users/<you>/Documents/memories" }
}

On Windows npx is a batch shim (npx.cmd), and Node's spawn will not resolve it without shell: true. A Node-based MCP client using the config above gets spawn EINVAL and the server silently never connects — it appears configured and does nothing. This is the standard Windows MCP gotcha, not specific to this server (claude-code#58510). npm i -g is not an escape — that installs a .cmd shim too. The only shim-free form is pointing node at the file directly: "command": "node", "args": ["C:/Users/<you>/AppData/Roaming/npm/node_modules/agentic-recall/index.js"].

Whether Claude Desktop itself is affected is still unconfirmed — it may spawn through a shell. The cmd /c form works either way, so it is the one to use on Windows.

🟥 Windows: if npx fails with ECOMPROMISED / Lock compromised, clear the npx cache. Node 24/25 with npm 11 leaves a stale lock in npx's cache directory that it then refuses to refresh (npm/cli#8710). Nothing to do with this server — it hits MCP Inspector and Gemini CLI identically. Measured on a real Windows machine: it reproduced twice, and clearing the cache fixed it (then a 98 s first download):

powershell

Copy

Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx" -ErrorAction SilentlyContinue
npm cache verify
npx -y agentic-recall@2 --version

If it still fails, two alternatives that avoid npx entirely — both verified end to end: npm install -g agentic-recall (then "command": "agentic-recall", "args": []), or Node 22, where npx works normally.

Requires Node 20 or newer. Nothing else — the embedding model downloads on first index and then runs locally. Your memories never leave the machine.

Prefer to read the code first, or run the suite?

git clone https://github.com/dfrancislyondflabc-tech/agentic-recall.git
cd agentic-recall && npm install && npm test    # 268 checks, no corpus of your own needed

Built by Daniel Francis-Lyon — questions, bug reports and criticism all welcome, either as an issue on this repo or at danfrancislyon@gmail.com.

Privacy Policy

Nothing leaves your machine. Memories are plain files in a folder you choose; the embedding model runs locally after a one-time download; there is no telemetry, no analytics and no phone-home. The author receives no data from your installation and has no means of doing so.

Full text: PRIVACY.md.

The part most memory tools skip

Retrieval always returns something. Ranked by similarity, the least-bad match comes back looking like an answer, and an agent acting on it cannot tell the difference between "here is what you wrote" and "here is the closest thing to it".

This server separates those two cases and says which one you got:

// asked about something that isn't in the corpus
{ "results": [],
  "confidence": "low",
  "bestWeak": [{ "name": "wheel-truing", "score": 0.31 }],
  "absenceNote": "no strong match — 'afternoon' appears nowhere in this corpus" }

Nothing was invented, nothing was silently ranked into first place, and the nearest thing is offered as a candidate rather than as an answer. Everything below is about how that verdict is reached and how it is measured.

The same refusal, applied to engineering claims

A memory saying "I fixed that in abc123" is a sentence. Classifying sentences has failed here three times — a correction vocabulary that fired on 76% of exchanges, an unresolved-statement vocabulary that fired on 24%. But a SHA is not a sentence to classify. It either exists or it does not.

Point MEMORY_GIT_REPOS at your repositories and every hex-shaped token in a retrieved memory is looked up. Four commands, and only what they prove:

Measured over 2,319 ingested exchanges: 707 SHA-shaped candidates collapsed to 355 real commits. Half of what looks like a commit isn't one, which is why every token is checked rather than trusted for its shape. Those rejects are not invented commits: re-measured on the current, larger corpus, 79% of reject occurrences are hex prefixes of conversation session IDs that the deliberately loose 7-10 character pattern sweeps up, so this gap measures how little the shape tells you rather than how often a memory fabricates a SHA.

What this does not tell you, deliberately. It does not check whether the change was later reverted, or whether the thing still exists at HEAD. A commit that landed and was undone the next day still reports as landed. So this is not a claim that the memory is currently true — it is a verified fact about the past, plus rev-list telling you exactly how much has happened since that nothing in the corpus can know about. The gap is measured rather than closed, which is the same discipline as the absence verdict above: never imply knowledge you do not have.

Repos are configured, never inferred — an earlier draft counted commits "in this repo", meaning wherever the process happened to be running, which is a different repository from the one the memories are about.

Two-tier hybrid retrieval over Claude's persistent memory corpus, exposed to Claude Desktop and Claude Code as two MCP tools: memory, which is read-only and never writes to your memory folder, and memory_write, which is the only way anything this server does can change it.

The curated corpus is the folder you point MEMORY_DIR at (see Environment overrides). MEMORY.md, if you have one, is treated as a hand-curated tier-1 index.

Figures quoted throughout this README — "121 .md files, ~2.7 MB", timings, hit rates — are measurements of the author's own corpus, not properties of yours. They are here because a claim with a number behind it can be checked; treat them as the conditions a result was obtained under, not as promises about your data. Three more work corpora sit beside it, each with its own index and its own statistics: other projects' memory folders (projects), auto-ingested conversation exchanges (staging) and the institutional handoff documents (handoff, read-only) — plus the library: imported reference material (books, manuals, policies) in per-category corpora that are searched only when named (scope:'books', or scope:'everything') and can never touch a work score. See Four work corpora + the library, one index each.

Why it exists

Reading the whole memory folder into context costs ~2.7 MB and buries the relevant three lines. This server answers the question "which memories matter for what I'm doing right now?" with three retrievers whose failure modes cancel: