agentic-recall

agentic-recall is an MCP server that provides persistent memory across sessions for Claude Desktop and Claude Code, and is designed for agentic tasks. Its key difference from other memory tools is that when the corpus does not contain what the user is asking about, it explicitly gives a "don't know" verdict instead of returning a worst match that looks like an answer.

Purpose and positioning The server reads a user-specified Markdown memory folder, performs two-layer hybrid retrieval, and exposes it to Claude through two MCP tools: memory is read-only and never writes to the memory folder; memory_write is the server's only way to change memory content.

Main capabilities

1. Hybrid retrieval: uses three retrievers—BM25F, dense vectors, and phrase proximity—whose failure modes cancel each other out. Scores are normalized and fused at 42/42/16, then subjected to long-document correction, hot-layer boosting, and slight recency decay. Each result reports its source (keyword/semantic/phrase/both), making ranking easier to diagnose.
2. Missing-content verdict: retrieval always returns results, but this server can distinguish "here is your original text" from "this is the closest thing." When there is no sufficiently strong match, it returns noStrongMatch: true and places candidates in bestWeak. This verdict is derived from a combination of measured weakness plus lexical tests, rather than a single score threshold.
3. Commit hash verification: after pointing MEMORY_GIT_REPOS at a repository, every hexadecimal token in retrieved memories is verified. It reports only the facts these commands can prove; it does not check whether changes were later rolled back, nor whether the content still exists in HEAD—this is a verified fact about the past, not a claim about current truth.
4. Multi-corpus indexing: supports pointing at memory folders (projects), automatically ingested conversational exchanges (staging), institutional handoff documents (handoff, read-only), and imported reference libraries divided by category (books/manuals/policies), the latter of which is searched only when scope:'books' or scope:'everything' is explicitly specified, and never participates in work scoring.
5. Long-document correction: measures "long" according to each corpus's own normal length, and proportionally exempts penalty based on keyword evidence, preventing an oversized document from dominating the ranking merely because it has many chunks.

How to use Installation instructionsMake it npx -y agentic-recall@2. The major version @2 must be pinned, because npx -y agentic-recall without a version number will request the latest tag from npm every time when the cache is cold, and a new major version may arrive silently and break existing configurations. The MEMORY_DIR environment variable must be provided to point to the memory folder. If you want to verify commit hashes, MEMORY_GIT_REPOS must also be set.

Windows users need a specific configuration: bare npx does not work on Windows for Node MCP clients and will produce spawn npx ENOENT. Use the form "command": "cmd", "args": ["/c", "npx", ...], or point directly to node to run the file: "command": "node", "args": ["C:/Users/<you>/AppData/Roaming/npm/node_modules/agentic-recall/index.js"]. Note that npm i -g also installs a .cmd shim on Windows and cannot be used as a workaround. If npx reports ECOMPROMISED / Lock compromised, clearing the npx cache is enough; this is unrelated to this server.

Note: a warm npx cache does not automatically fetch a fixed version. To get a fix, clear the cached copy and resolve it once again (macOS/Linux: rm -rf ~/.npm/_npx && npx -y agentic-recall@2 --version; Windows: use the Remove-Item command), then restart the client. The serverVersion in each response will tell you the version that actually responded.

Use cases Suitable for agent tasks that need long-term memory across sessions, especially scenarios where you want memory stored as local plain files, not dependent on an external vector database, and with a clear judgment for "I don't know." It can also be used for engineering memory management that needs to verify whether commit hashes in memory actually exist.

Limitations Requires Node 20 or later. The embedding model is downloaded on first indexing, then runs locally afterward, and memory never leaves the local machine. Missingness determination becomes less reliable when the corpus is small: orphanShare measures the proportion of unique words in a question that do not appear at all in the corpus, so on a young corpus with thinner vocabulary, about 5/20 (122 files) or 3/4 (13 files) of answerable questions are misjudged as missing. It is a safe failure - the correct document is in bestWeak rather than being fabricated - but on young corpora you should read bestWeak before trusting the refusal determination. Commit hash verification does not check whether a change was later reverted or whether it still exists in HEAD. All cited numbers (such as 121 .md files, about 2.7 MB, hit rate, etc.) are measurement results from the author's own corpus, not properties or promises of user data. The test/... paths are references to where the numerical measurements were taken, not files in the distribution; the test suite is not shipped with the package.