agentic-recall 是一个 MCP 服务器，为 Claude Desktop 和 Claude Code 提供跨会话的持久记忆，并面向智能体任务设计。它与其他记忆工具的关键区别在于：当语料中不包含用户所问内容时，它会明确给出“不知道”的判定，而不是返回一个看起来像答案的最差匹配。
用途与定位 该服务器读取用户指定的一个 Markdown 记忆文件夹，进行两层混合检索，通过两个 MCP 工具暴露给 Claude：memory 为只读，永不写入记忆文件夹；memory_write 是服务器唯一能改变记忆内容的途径。
主要能力
- 混合检索：使用 BM25F、稠密向量和短语邻近度三种检索器，其失败模式相互抵消。分数经过归一化后按 42/42/16 融合，再经过长文档校正、热层提升和轻微时效衰减。每个结果报告其来源（keyword/semantic/phrase/both），便于诊断排序。
- 缺失判定：检索始终会返回结果，但本服务器能区分“这里有你的原文”与“这是最接近的东西”。当没有足够匹配时，返回 noStrongMatch: true，并将候选放入 bestWeak。该判定由测得的弱点组合加词汇测试共同得出，而非单一分数阈值。
- 提交哈希校验：通过 MEMORY_GIT_REPOS 指向仓库后，检索到的记忆中的每个十六进制令牌都会被查证。它只报告这些命令能证明的事实，不检查更改是否后来被回滚，也不检查内容是否仍存在于 HEAD——这是关于过去的已核实事实，而非当前真实性的声明。
- 多语料索引：支持指向记忆文件夹（projects）、自动摄入的对话交流（staging）、机构交接文档（handoff，只读），以及按类别划分的导入参考资料库（books/manuals/policies），后者仅在显式指定 scope:'books' 或 scope:'everything' 时被搜索，且永不参与工作评分。
- 长文档校正：按每个语料自身的正常长度衡量“长”，并依据关键词证据按比例免除惩罚，避免一个超大文档仅因块数多而主导排名。
使用方式 安装命令为 npx -y agentic-recall@2。必须固定主版本号 @2，因为不带版本号的 npx -y agentic-recall 会在缓存冷时每次向 npm 请求最新标签，新主版本可能静默到达并破坏已有配置。需要提供 MEMORY_DIR 环境变量指向记忆文件夹。若希望校验提交哈希，还需设置 MEMORY_GIT_REPOS。
Windows 用户需使用特定配置：裸 npx 在 Windows 上对 Node MCP 客户端无效，会得到 spawn npx ENOENT。应使用 "command": "cmd", "args": ["/c", "npx", ...] 形式，或指向 node 直接运行文件："command": "node", "args": ["C:/Users/<you>/AppData/Roaming/npm/node_modules/agentic-recall/index.js"]。注意 npm i -g 在 Windows 上同样安装 .cmd shim，不能作为规避方案。若 npx 报 ECOMPROMISED / Lock compromised，清除 npx 缓存即可，这与本服务器无关。
注意：npx 缓存变热并不会自动获取修复版本。要获取修复，需清除缓存副本并重新解析一次（macOS/Linux: rm -rf ~/.npm/_npx && npx -y agentic-recall@2 --version；Windows: 使用 Remove-Item 命令），然后重启客户端。每个响应中的 serverVersion 会告知实际应答的版本。
适用场景 适用于需要跨会话长期记忆的智能体任务，尤其是希望记忆以本地纯文件保存、不依赖外部向量数据库、且对“不知道”有明确判断的场景。也可用于需要核实记忆中提交哈希是否真实存在的工程记忆管理。
限制 需要 Node 20 或更高版本。嵌入模型在首次索引时下载，之后本地运行，记忆永不离开本机。缺失判定在语料较小时可靠性下降：orphanShare 衡量问题中独特词在语料中完全不出现的比例，因此在词汇较薄的年轻语料上，可以回答的问题约 5/20（122 文件）或 3/4（13 文件）被误判为缺失。它是安全失败——正确文档在 bestWeak 中而非被编造——但在年轻语料上应阅读 bestWeak 再相信拒绝判定。提交哈希校验不检查更改是否后来被回滚或是否仍存在于 HEAD。所有引用的数字（如 121 个 .md 文件、约 2.7 MB、命中率等）均为作者自己语料的测量结果，不是用户数据的属性或承诺。test/… 路径是数字测量位置的引用，不是发行版中的文件；测试套件未随包发布。
