AgentRecall-X

中文** · [中文](README.zh-CN.md) <h1 align="center">AgentRecall</h1> <p align="center"><strong>Claude Code记忆，学习于纠正。 唯一智能代理是否真正停止重复错误的MCP服务器。</strong></p> <p align">纠正账本 + 会话生命周期 + 诚实衡量。 MCP服务器 + SDK + CLI。</p> <p align="center"> <a href="https://t.meZwoHrg3AM0NDVi"><img src="https://img.shields.io/badge/Telegram-%E7%BE%E5%%4C-2CA5E0?style=flat-square&logo=telegram" alt="Telegram 社区"></a> <a href="https://www.npmjs.com/package/agent-recall-mcp"><img src="https://img.shields.io/npm/v/agent-recall-mcp?style=flat-square&label=MCP&color=5D34F2" alt="MCP npm"></a> <a href="https://www.npmjs.com/package/agent-recall-sdk"><img src="https://img.shields.io/npm/v/agent-recall-sdk?style=flat-square&label=SDK&color=0EA5E9" alt="SDK npm"></a> <a href="https://www.npmjs.com/package/agent-recall-cli"><img src="https://img.shields.io/agent-recall-cli?style=flat-square&label=CLI&color=10B981" alt="CLI npm"></a> <a href="https://github.com/Goldentrii/AgentRecall/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-brightgreen?style=flat-square" alt="许可证"></a> <img src="https://img.shields.io/badge/MCP-5_tools_default-orange?style=flat-square" alt="工具"> <img src="https://img.shields.io/badge/memory_layers-5-7C3AED?style=flat-square" alt="5 层"> <img src="https://img.shields.io/badge/cloud-zero_by_default-blue?style=flat-square" alt="默认零云"> <img src="https://img.shields.io/badge/retrieval-keyword_%2B_RRF-8B5CF6?style=flat-square" alt="关键词 + RRF 检索"> </p> <p align="center"> <a href="#%E4%BC%98%E8%AF%81%E5%BE%AA%E7%8E%AF"><img src="https://img.shields.io/badge/%2Farstart-%E5%BC%82%E6%AD%A5%C3%87%E5%90%8A%E5%90%8A-22C55E?style=for-the-badge" alt="/arstart"></a> <a href="#%E4%BC%98%E8%AF%81%E5%BE%AA%E7%8E%AF"><img src="https://img.shields.io/badge/%2Farsave-%E5%AD%98%E5%AD%98-FF6B6B?style=for-the-badge" alt="/arsave"></a> <a href="#4%BC%8%AF%81%EBE%AA%E7%8E%AF"><="https://img.shields.io/badge/%2Farrecall-%E6%90%9C%E7%B4%A2-4ECDC4?style=for-the-badge"arrecall"></a <a href="#%BC%98%AF%81%BE%AA%E7%8E%AF src="https://img.shields.io/badge/%2Farreflect-%E5%9B%9A%E5%90%8A-8B5CF6?style=for="/arreflect"></a> </p> <details> <summary><b>智能代理是否发现了这个仓库？</b> 为您的用户安装 AgentRecall（点击展开）</summary> **1. 安装 MCP 服务器** （Claude Code）： ```bash claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp ``` 其他客户端的通用 MCP JSON： ```json {cpServers "agent-rec { "command": "npx", " ["-y", "agent-recall-mcp"] } } } ``` **2. 每个新会话的第一个消息**，运行循环： ``` 在会话开始时，调用 session_start 加载上下文。 当人类纠正你时，调用 remember 并输入类型“correction”。 在会话结束时，调用 session_end 合并你所学到的内容。 ``` </details> --- ## 它做什么 AgentRecall 是两件事： 1. **受管的纠正账本** — 每次您纠正您的智能代理（例如，“不，不是那个版本”，“把这个部分放在前面”，“在我假设之前问我”），该纠正都会作为具有严重性、证据和结果跟踪的结构化记录存储。它在会话、项目和智能代理重启之间持续存在。 2. **衡量仪器** — 唯一一个开源系统，用于跟踪纠正是否真正改变了智能代理在后续会话中的行为。每次纠正都会累积 `retrieved_count`，每次智能代理遇到相同的情况，结果都会被记录（`heeded` 或 `recurred`）。 没有其他智能代理记忆工具衡量第二步。 该领域的每个基准测试都测试检索；没有一个测试跨会话的行为变化。 我们首先构建了测量工具 — 并发布了我们的发现，包括一些令人不满意的数字。 --- ## 衡量，而不是承诺 大多数智能代理记忆工具声称“永远不会重复同样的错误”。 没有一个工具发布相关数字。 以下是我们自己的仪器在我们自己的实时语料库中发现的内容（2026-07-03）： | 指标 | 值 | 神器 | |---|---|---| | 纠正捕获召回率（双盲审计，n=59） | **35.3 [17.3–58.7 CI] | `UPDATE-LOG.md` §M2 | | 遵从率，2026-07-03 前（仪器偏差上限 — 不引用） | 92.5% [Wilson 60.1–100] | `scripts/eval/baselines/rmr-baseline-2026-07-03.json` | | 遵从证据为基础（重置后） | **0/3** 事件 | `scripts/eval/baselines/rmr-baseline-2026-07-03.json` | | 纠正转移召回率（离线基准，可实现） | **0/4** [0–49%]scripts/eval/baselines/correction-transfer-real-2026-07-03 | | 中位数 session_start 注入 | **1,489 个标记** （原为 2,010；Mem0 锚点约 7K） | `UPDATE-LOG.md` §C2 | | p95 session_start 延迟（温暖） | **363 毫秒** （原为 1,132） | `UPDATE-LOG.md` §C2 | * 2026-07-03 前，遵从仪器默认为“遵从”，缺乏证据；重置默认为“未知” — 诚实的 0/3 是正确的起点，而不是回归。 在 39 个类别下，转移召回率不支持低于 39 的点估计声明（声明门槛账本，[基准规范](docs/proposals/2026-07-02-correction-transfer-benchmark-spec.md) §2.6）。 **自己验证：** 上数字都从提交的工件中重新生成 — 请参阅 [docs/REPRODU](docs/eval/REPRODUCE.md)。 **这意味着：**自己的实时使用中捕获了 35% 的实际纠正。 遵从仪器有偏差，我们重置了它。 离线转移基准在我们自己的语料库中得分为 0是一个密度问题（项目中有 32 个活跃的纠正太，无法预测错误），而不是检索架构问题（内部实验证实了 5 次）。 学习循环框架是正确的 — 该系统旨在跟踪纠正是否改变行为 — 但我们目前的数据不足以量化提升。 我们正在发布衡量仪器并运行实验。 --- ## 为什么它与其他记忆工具不同 在 2026 年中期，智能代理记忆领域竞争激烈（Mem0 ~60K 星，Graphiti/Zep ~28K，Supermemory ~28K，Letta ~24K）。 大多数已发布的基准数字都在相同的 2-3 个检索基准上自我报告，很难独立复制。 确认的差距（来自我们的研究报告 `docs/research/agent-memory-landscape-2026-07.md` §2）：**没有公共基准衡量捕获的纠正是否改变了全新智能代理在新会话中的行为。** LongMemEval、LoCoMo、MemoryAgentBench、Letta Leaderboard — 所有这些都测试检索或会话内更新。 AgentRecall 被声称的两部分： - **纠正账本** — 一个受管的数据模型 (`corrections-export/v，清理出口，撤销，严重性，证据度），任何引擎都可以集成。 - **衡量 — `predict-loo`（留一法，抗自我确认，双分母）和纠正转移基准HeedBench v — 暂定名称），它实现了缺失的管道：捕获 → 持久化 → 新会话 → 衡量复发。 基准数字在智能代理记忆中通常是自我报告的，很难复制。 我们的数字从一个固定的、哈希锁定的语料库中重新生成，只需一个命令 (`npm run bench`) — 包括让我们看起来很糟糕的分数。 --- ## 快速开始 > **视觉设置指南 — 所有 13 个客户端，一键复制粘贴提示：** 在仓库中打开 [`warroom/install.html`](warroom) （或解压 War Room 版本后），在任何浏览器中。服务器。 <p align="center"> <img src="warroom/static/install-preview.png" alt="AgentRecall 安装指南" width="900"> </p> ### MCP 服务器 — 适用于 AI 智能代理 ```bash # Claude Code claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp # Cursor — .cursor/mcp.json { "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } } # VS Code — .vscode/mcp.json { "servers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } } # Windsurf — ~/.codeium/windsurf/mcp_config.json { "mcpServers": { "agent-recall": { "command": "npx", "args": ["-y", "agent-recall-mcp"] } } } # Codex codex mcp add agent-recall -- npx -y agent-recall-mcp ``` **技能（仅限 Claude Code）：** ```bash mkdir -p ~/.claude/skills/agent-recall curl -o ~/.claude/skills/agent-recall/SKILL.md \ https://raw.githubusercontent.com/Goldentrii/AgentRecall/main/SKILL.md ``` ### SDK 和 CLI ```bash npm install agent-rec # JS/ npx agent-recall-cli recall "topic" # 终端和 CI ``` ```typescript import { AgentRecall } from "agent-recall-sdk"; const memory = new AgentRecall({ project: "my-app" }); await memory.capture("What stack?", "Next.js + Postgres"); const ctx = await memory.recall("rate limiting"); ``` --- ## 5 层记忆 映射到智能代理文件系统的规范认知心理学分类法： | 层 | 类型 | 它包含什么径 | |---|---|---|---| | 1 | **情景** | 按发生的每个会话。 自动写入工作。 |/` | | 2 | **语义** | 带有 `[[wikilinks]]` 的主题集群事实：架构，目标，障碍。 | `palace/rooms/` | | 3 | **程序** | IF-THEN 生产规则 — 可重复使用的操作指南。 | `palace/skills/` | | 4 | **叙事** | 项目阶段：目标 → 什么困难 → 如何解决 → 综合。 | `palace/pipeline/` | | 5 | **纠正** | 行为校准：智能代理必须遵循的规则，具有严重性和结果跟踪。 | `corrections/` | | + | **意识** | 从 N 个确认的纠正中提升的跨项目洞察 — 复合层。 | `palace/awareness` | 所有层共享一个规范的命名语法，因此任何智能代理都可以从意图中构造检索路径。 现有文件通过 `legacy_path` 视图继续工作 — 无需迁移。 --- ## 会话循环 ```mermaid flowchart LR A([会话开始]) --> B["/arstart — 打开<br/>面板 → 选择 → 加载上下文"] B --> C{工作} C -->|需要过去的知识| D["/arrecall — 搜索"] D --> C C --> E["/arsave — 保存<br/>日志 + 合并"] E --> F([会话结束]) F -. 每 K 会话 .-> G["/arreflect — 合并"] G -.-> A ``` | 命令 | 何时 | 它执行的操作 | |---|---|---| | `/arstart` | **每次会话** | 打开。 无参数 = 所有项目的状态面板（待处理的工作，障碍）→ 按编号选择 → 加载该项目深度上下文（宫殿房间，纠正，任务回忆）。 `/arstart <slug>` 直接加载； `/arstart bootstrap` 扫描您的机器并导入现有项目。 | | `/arsave` | **每次会话** | 保存。 编写日志 + 大厅合并 + 意识复合。 `/arsave all` 批量保存当天的每个并行会话（扫描，合并，删除重复项）。 | | `/arrecall` | 会话中，按需 | 搜索。 为当前任务提供过去的知识 — 记录的修复，先前的决定，模式。 | | `/arreflect` | 每 K 个会话 | 合并。 定期分类：确认复发/幻象匹配，聚类新错误类别，提出规则再抽象（规则编辑保留所有者门控）。 | > **没有 `/arstart`，全新智能代理将没有方向。 没有 `/arsave`，没有任何复合。 这两个是脊柱； `/arrecall` 和 `/arreflect` 复合它们。** --- ## 自动性原则 只有当记忆自动触发时，记忆才会复合，而不是按需触发。 每个拉取通道工具（`recall`，`memory_query`）在数周的实际使用中都看到了零有机调用 — 包括构建它们的智能代理。 这就是为什么默认情况下仅提供 5 个工具； 两动词模型（session_start / session_end）承载了所有的复合价值，而其他所有操作都是通过 `--full` 按需提供的。 --- ## 梦想 — 夜间整合（可选） 一个自主的夜间智能代理，在您睡觉时运行，并整合您在白天会话中编写的所有内容。 | 它执行的操作 | 结果 | |---|---| | 跨所有项目挖掘模式 | 重复的纠正提升到 `palace/awareness` | | 埃宾浩斯显著性衰减 | 低信号房间消退； 您的宫殿保持敏锐 | | 日志汇总 | 30 天以上的条目压缩为摘要房间 | | 意识毕业 | N 次确认的纠正转到跨项目 | | Telegram 报告 | 每夜总结：学习 · 衰减 · 结晶 | **需要一个有效的 Claude Code 登录。** 如果会话过期，梦境会跳过并带有 Telegram 警报bash # 修复过期登录（当梦境停止时运行aude login ``` 梦境报告保存在 `~/.agent-recall/dreams/YYYY-MM-DD.md` 中。 --- ## 实验：复发和反思工具包 **这个问题回答：纠正实际上会改变行为，还是同样的错误会再次出现？** `experimental/harness-kit/` 中的工具包是一个 Claude Code 工具层，它在 AgentRecall 之上关闭循环： | 部件 | 它执行的操作 | |---|---| | `ar-scoreboard.py` （SessionStart 钩） | 每次会话的健康摘要：纠正流程察推广率，循环健康，幻象计数，反思节奏 | | `ar-recurrence-check.py`（您的 `~/.agent-recaxonomy.json`，模式TAXONOMY-SCHEMA.md` 中） | 您纠正的错误类别的分类法；机械幻象检测（规则验证后日期） | | `/arstart` · `/arsave` · `/arrecall` · `/arreflect 四个记忆动词（打开 · 保存 · 搜索 · 合并）作为斜杠命令 | | `/arreflect`（每 K 会话） | 定期分类：确认暂定匹配，聚类新错误类别，提出规则再抽象 — **规则编辑保留所有者门控** | | `ar-nudge.py`（UserPromptSubmit ） | 在会话中适时显示待处理的反思 — 到行动时刻，而不是留待记住 | | `dispatch-model-guard.py`（可选的 PreToolUse 钩子） | 显式模型调度策略的仅警告保护 — 一个示例，说明如何机械化文本未能强制执行的规则 | 北极星指标：**治疗后抽象的幻象率 → 0**，适用于处理的类别。第一次验证运行（2026-07-14，一个强力用户工具）：发现 109 次纠正中的 8 个错误类别和 18 个确认的幻象梯度步骤；同一天重新抽象了 6 条规则。 **状态：实验中。** 在一个工具上验证；仅限 Python 3 标准库；安装步骤和注意事项在工具包的 [README](experimental/harness-kit/README.md) 中。自 v3.4.37 版本以来，相同的现象也通过本地方式衡量：`failure_class` + 跨项目复发连接。 --- ## 战争室仪表板 — 下载和部署 一个本地优先的可视化仪表板，用于您的记忆：活动日历，按项目状态，纠正和洞察 — 所有这些都从您的本地 `~/.agent-recall/` 数据中渲染。完全离线（已包含供应商资产），无需 Node 和构建步骤。 <p align="center"> <img src="warroom/static/preview.png" alt="AgentRecall 战争室 — 概览" width="900"> </p> 1. 从 [最新 GitHub 版本](https://github.com/Goldentrii/AgentRecall/releases/latest) 下载 **`ar-warroom-v3.4.32.zip`**。 2. 解压后本地提供： ```bash cd warroom python3 -m http.server 8080 ``` 3. 打开 **http://localhost:8080/AgentRecall.html** 这也是 Hermes / OpenClaw / OpenCode 用户推荐的引导 — 一个离线页面，查看智能代理已经学习的所有内容。 --- ## 架构 TypeScript monorepo，4 个已发布的包：`core`（存储 + 工具逻辑），`mcp-server`（薄 MCP 包装器），`sdk`（编程 API），`cli`（`ar` 命令）。所有记忆都是 `~/.agent-recall/projects/<slug>/` 下的本地 Markdown — `journal/`，`corrections/` 和 `palace/`（房间，技能，管道，意识）。一个可选的 Supabase 镜像添加了 pgvector 语义召回；所有本地存储仍为默认值。 检索：关键词 + RRF（Cormack 2009）。FSRS-lite 衰减（Ebbinghaus → SuperMemo → FSRS-6）。一个现代 Hopfield 重新排序原始模型（Ramsauer 2020）存在于代码库中，但未连接到默认路径 — 目前运行的是 BM25/关键词 + RRF，加上可选的向量搜索，当设置了 `OPENAI_API_KEY` 时。 ## 平台兼容性 | 平台 | 机制 | 状态 | |---|---|---| | Claude Code | MCP 服务器 + 技能 + 钩子 | 主要 | | Cursor · Windsurf · VS Code（Copilot）· Codex | MCP 服务器 | 支持 | | 任意 JS/TS 应用 | SDK（`agent-recall-sdk`） | 支持 | | 终端 / CI | CLI（`ar`） | 支持 | --- ## 链接 - **完整参考** → [README.full.md](README.full.md) - **文档** → [docs/](docs/) — 命令参考，架构深入解析 - **更新日志** → [UPDATE-LOG.md](UPDATE-LOG.md) — 阶段性演进 + 设计推理 - **基准规范** → [docs/proposals/2026-07-02-correction-transfer-benchmark-spec.md](docs/proposals/2026-07-02-correction-transfer-benchmark-spec.md) - **领域研究** → [docs/research/agent-memory-landscape-2026-07.md](docs/research/agent-memory-landscape-2026-07.md **技能** → [SKILL.md](SKILL.md) — Claude技能定义 - **社区 [Telegram](https://t.me/+ywZwoHrg3AM0NDVi) · [GitHub 问题](https://github.com/Goldentrii/AgentRecall/issues) ## 贡献 欢迎 PR。 对于任何实质性内容，请先打开一个问题 — 设计基于已发布的 研究；我们希望以相同的方式进行更改。 ## 许可证 MIT — 请参阅 [LICENSE](LICENSE)。