agent-recall

English · 中文

AgentRecall

纠正你的 Agent 一次。它会在下个会话记住——我们还会衡量它是否真的不再犯。

为 AI Agent 打造、本地优先的记忆，围绕可审计的纠正记录和数学原理构建。MCP · SDK · CLI · Skill。

claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp

claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp

On session start                  → call session_start (before you act)
When the human corrects you       → call remember with type "correction" — saying "noted" is not saving
Before publish/push/deploy/delete → call check with action_description; obey verdict "blocked"
When past context would help      → call recall
On "save" / "remember" / exit     → call session_end

目录

• 问题 · 功能 · 会话循环 · MCP 工具
• 记忆的本质 — 5 个层次 · 记忆如何累积 · 数学原理
• 实测，而非承诺 · 与其他记忆工具的比较
• 安装 · 可选扩展 · 架构 · 平台 · 社区 · 链接

问题

你告诉 Agent：“未经允许，不要提升版本号。”它道歉并修正了问题，会话也随之结束。下周，新会话又犯了同样的错误——这条纠正记录在没人会看的聊天日志里。

AgentRecall 会将这句话转化为一条结构化、持久的规则，在下一个 Agent 开始行动之前将其呈现给它，并记录错误是否再次发生。

── session 3 ─────────────────────────────────────────────
you   › no — never bump the version without asking me first
agent › remember(type: "correction")
        ✓ saved · severity p0 · applies_when: [release, npm]

── session 9 · new agent, no chat history ───────────────
session_start › project "my-app" · 1 critical correction
                watch_for: version bump → ask the owner first
you   › ship the fix
agent › Fix is merged. Want me to bump to 1.4.1, or leave the version?
        outcome recorded: heeded

_{示例对话。}

功能

AgentRecall 有两个作用：

1. 一份受治理的纠正记录簿。 每条纠正（“不是那个版本”“把这一节放在最前面”“有疑问时先问再假设”）都会成为一条结构化记录，包含严重程度、证据、applies_when、撤回记录和结果，并在不同会话、项目和 Agent 重启之间持久保存。导出格式：corrections-export/v1，导出时会清理敏感信息。
2. 一种测量工具。 每条纠正都会累积 retrieved_count；每当 Agent 遇到相同情形，结果都会记录为 heeded 或 recurred。目前还没有公开基准衡量这一环节；我们先构建了测试框架，并公布其发现，包括那些不那么好看的数字。

会话循环

flowchart LR
    A([session start]) --> B["/arstart · session_start<br/>load rules + context"]
    B --> C{work}
    C -->|need past knowledge| D["/arrecall · recall"]
    D --> C
    C -->|corrected| R["remember<br/>type: correction"]
    R --> L[(corrections<br/>ledger)]
    C -->|risky action| K["check"]
    L -.-> K
    C --> E["/arsave · session_end<br/>journal + compound"]
    E --> F([session end])
    L -. watch_for .-> B
    F -. every K sessions .-> G["/arreflect<br/>consolidate"]
    G -.-> A

不运行 /arstart，全新的 Agent 就毫无上下文。不运行 /arsave，记忆就不会累积。

MCP 工具

默认提供五个工具。每项描述都面向 Agent，说明了何时调用它。

重要

自动化定律——为何只有 5 个工具。 只有无需请求就会触发的记忆，才能不断积累。在 44 个项目和数周的实际使用中，主动拉取信息的工具（recall、memory_query）从未被自然调用过一次——包括创建它们的 Agent。推送渠道（session_start、session_end、修正钩子）才会改变行为。每增加一个默认工具，每次会话都会消耗定义令牌，却没有任何回报。_{（基于所有者的存储数据自行测量，2026-06-12。）}

因此，在 Claude Code 中配置钩子，这样循环就能自动运行，无需依赖 Agent 自律：

ar hook-start        SessionStart      加载上下文，显示 watch_for 警告
ar hook-correction   UserPromptSubmit  静默捕获修正
ar hook-ambient      UserPromptSubmit  注入相关记忆（重叠词至少为 2 个）
ar hook-save         UserPromptSubmit  “save”/“retain” → 提示调用 session_end
ar hook-pretool      PreToolUse        对 npm publish、git push、rm -rf、deploy、DROP TABLE 发出警告
ar hook-end          SessionEnd        若当天尚未保存，则自动保存日志
ar health            —                 最近的钩子故障（明确报错）

记忆的本质——5 个层次

将认知心理学分类映射到普通文件。每个层次的遗忘速度各不相同，因为人类记忆也是如此。

~/.agent-recall/
├── projects/<slug>/
│   ├── journal/            episodic — one entry per session
│   ├── corrections/        behavioral rules + outcome ledger
│   └── palace/
│       ├── rooms/          semantic
│       ├── skills/         procedural
│       ├── pipeline/       narrative
│       ├── identity.md
│       └── awareness       cross-project insights
├── dreams/                 nightly consolidation reports
├── dashboard.html          human-readable
└── dashboard.json          agent-readable snapshot

所有层次共用一套命名规则，因此 Agent 可以根据意图组合出检索路径。较旧的文件通过 legacy_path 视图继续生效——无需迁移。

记忆如何累积效应

flowchart LR
    C["correction<br/>(remember / hook)"] --> L[(ledger)]
    L --> S["session_start<br/>ranked by severity,<br/>proof, recency"]
    S --> O{"same situation<br/>again?"}
    O -->|heeded| P["proof_count +1<br/>stability × 1.3"]
    O -->|recurred| X["phantom<br/>→ /arreflect<br/>rewrites the rule"]
    P --> A["≥ 3 confirmations<br/>→ awareness<br/>(cross-project)"]
    X --> L

每次确认一条纠正，它的效果就会增强；标记为无用时，效果会减弱；在三个不同的（日期、项目）场合得到确认后，它就会推广到所有项目。已保存的规则若未能阻止错误再次出现，就是一个幻影——写入成本已经付出，行为却没有改变；此时会重新编写规则，而不只是再次保存。

数学原理

业内大多数产品都把「AI 记忆」当作黑箱。AgentRecall 中的每一种机制都以可读公式呈现，常数在源代码中，并且标注真实状态：

1 · 排名融合 — 倒数排名融合 🟢

Palace、日志、洞见和纠正各自为候选项排序；合并列表时按排名，绝不按原始分数，因为原始分数的尺度无法直接比较（Cormack、Clarke 和 Büttcher，2009——Elasticsearch 使用的也是同一个 $k$）：

\mathrm{RRF}(d) \;=\; \sum_{\ell \,\in\, \text{lists}} \frac{w_\ell}{k + \mathrm{rank}_\ell(d)}, \qquad k = 60,\;\; w_\ell = 1

可选的语义环节只是再加入一个列表，权重为 $w = 1.0$——这是测量得出的权重，而非随意选择：1.1 和 1.3 会让前 5 名被淹没。

说明

数学揭示了一个错误。 相邻的 RRF 排名仅相差 $\frac{1/(60+r)}{1/(61+r)} \approx 1.6\%$，因此，融合后乘以任何超过约 1.02 的系数，都会让一条无关内容压过所有相关内容。旧版的 ×3 / ×2 / ×1.3「近期内容加权」正是如此——前 5 名全被过去 72 小时的日志条目占满。移除后：黄金测试集上的前 5 名命中率从 55.0% 提升至 75.0%（双生克隆对照，2026-09-12）。

2 · 遗忘 — 按来源应用艾宾浩斯曲线 🟢 形式 · 🟡 常数

R(t) = e^{-t/S}, \qquad S_{\text{journal}} = 2,\;\; S_{\text{knowledge}} = 180,\;\; S_{\text{palace}} = 9999 \text{ days}

3 · 间隔强化 — FSRS-lite 🟢 形式 · 🟡 常数

这是 FSRS-6 / SuperMemo 的简化版本，包含两个组成部分（稳定性、可检索性）——没有难度项，因为我们从不运行复习会话：

R = e^{-\Delta t / S}, \qquad S_0 = 7\text{ d}, \qquad \underbrace{S' = 1.3\,S}_{\text{confirmed}}, \qquad \underbrace{S' = \max(1,\; 0.5\,S)}_{\text{marked wrong}}

分档：$R \ge 0.85$ 为高频 · $\ge 0.6$ 为温热 · $\ge 0.3$ 为偏冷 · 否则为归档候选项——显示在仪表板上，绝不自动删除。

4 · 显著性 — Palace 房间的价值 🟡

\text{salience} = 0.30\,\text{recency} + 0.25\,\text{access} + 0.20\,\text{connections} + 0.15\,\text{urgency} + 0.10\,\text{importance}

其中，$\text{recency} = \max(0.05,\; \rho_c^{\,\text{days}})$，衰减率取决于类别：目标 $\rho = 0.99$ · 架构 $0.98$ · 决策 / 经验教训 $0.97$ · 观察 $0.95$ · 阻塞项 $0.90$。刻意将自我报告的重要性设为权重最低的项——人们会误判重要性；你实际使用的内容才是更强的信号。

5 · 从反馈中学习 — 贝塔—伯努利 🟢

每条 recall 结果都可以评为有用 / 无用。项目分数会乘以其经过拉普拉斯平滑的后验均值的两倍（中性 = ×1.0；默认路径中唯一会改变融合后分数的操作）：

\mathbb{E}[\theta] = \frac{\text{pos}+1}{\text{pos}+\text{neg}+2}, \qquad \text{multiplier} = 2\,\mathbb{E}[\theta] \in (0, 2)

6 · 关联 — ACT-R 激活 🟡（选择启用 AGENT_RECALL_ACTIVATION=1）

一起被引用的记忆会建立关联。ACT-R 陈述性记忆公式中的关联项（Anderson 和 Lebiere）：

A_i = B_i + \sum_j W_j\, S_{ji}, \qquad S_{ji} = w_{ji}\, e^{-\Delta d / 30}, \qquad W_j = \tfrac{1}{|\text{context}|}

重新排序：$\text{score}' = \text{score}\cdot\bigl(1 + 0.2\,\tfrac{x}{x+1}\bigr)$——$\tfrac{x}{x+1}$ 这一压缩函数可以避免将两个不兼容的尺度相加；没有证据时，它则完全不起作用。

7 · 意译匹配 — 集合余弦 🟡 指标 · 🟢 阈值

\cos(A,B) = \frac{|A \cap B|}{\sqrt{|A|\,|B|}}, \qquad \text{sim} = \max\bigl(\cos_{\text{concepts}},\; \cos_{\text{char-trigrams}}\bigr) \ge 0.20

基于词干和 13 组人工整理的同义词（「publish / ship / release」归并为同一个概念）。它是模糊的词汇匹配，并不理解含义。0.20 的阈值通过留一法（predict-loo）调优，取仍能保持 0% 误报率的最高召回率点。

8 · 晋级——先纳入，再投票 🟢

夜间整合过去会以 $\tfrac{\text{obs}}{7}\times\text{recency} \ge 0.8$ 作为门槛。凌晨 2 点，最新的日志是昨天的，因此 recency $\le 0.85$；“7 天内观察到 3 次”的得分为 $\tfrac{3}{7}\times 0.85 = 0.36$——在 22 个夜晚里被悄然丢弃，而正常运行时间监控仍显示绿色。新的方案将纳入与晋级分开处理：

\text{promote} \iff \#\{(\text{day},\,\text{project}) \text{ confirmations}\} \ge 3

现在每晚都会写入一条 产出 记录，因此零产出的夜晚会被归类（empty-corpus · filtered · already-known · errored），而不会显得一切正常。

9 · 衡量行为变化——采纳率 + Wilson 区间 🟢

\text{heed} = \frac{\text{heeded}}{\text{heeded} + \text{recurred}}, \qquad
\text{CI}_{95} = \frac{\hat p + \frac{z^2}{2n} \;\pm\; z\sqrt{\frac{\hat p(1-\hat p)}{n} + \frac{z^2}{4n^2}}}{1+\frac{z^2}{n}}, \quad z = 1.96

当 $n$ 较小时，区间会诚实地保持较宽，而不是给出自信的单点估计。事件按证据分级（heeded_verified · heeded_checkaction · heeded_default · recurred_verified · recurred_selfreport），每个 KPI 展示面都会将两个等级显示为一个范围——没有证据，不应计作“已采纳”。

10 · 校准置信度 🟡

\text{conf} = \frac{\text{score}}{0.12}\;(\text{local RRF}) \;\;\big|\;\; \frac{\text{score}}{0.049}\;(\text{Supabase RRF}) \;\;\big|\;\; \cos\;(\text{vectors}) \;\;\longrightarrow\;\; \text{high} \ge .66,\; \text{med} \ge .40,\; \text{low} \ge .20

\xi^{\text{new}} = X^{\top}\operatorname{softmax}(\beta X \xi), \qquad E = -\tfrac{1}{\beta}\log\sum_i e^{\beta\langle x_i,\xi\rangle} + \tfrac12\lVert\xi\rVert^2

未解决的问题 🔴——冗余能否重建意图？

目前，累积的修正采用聚类 + 衰减 + 集合余弦相似度：这是计数，而不是后验概率。称之为“意图重建”会言过其实。要名副其实，模型应将每条修正视为潜在偏好 $\theta$ 的一个带噪样本，其中 $x_i = \theta + \varepsilon_i,\; \varepsilon_i \sim \mathcal N(0, \sigma^2 I)$，先验为 $\theta \sim \mathcal N(\mu_0, \tau^2 I)$：

\operatorname{Var}[\theta \mid x_{1..N}] = \Bigl(\frac{1}{\tau^2} + \frac{N}{\sigma^2}\Bigr)^{-1} = O\!\left(\frac{\sigma^2}{N}\right),
\qquad \mathrm{SNR}_N = \frac{\lVert \mu_N \rVert^2}{\operatorname{tr}\operatorname{Var}[\theta \mid x_{1..N}]}

可证伪的主张：对于一致的修正流，$\mathrm{SNR}_N$ 会单调上升；修正互相冲突时则会停滞。想参与构建吗？这是该仓库中最重要的未解决问题。

_{完整推导、输入以及每个常量的来源：packages/core/src/MATH.md。}

有数据测量，不只是承诺

Agent 记忆基准测试检验的是检索能力。没有任何测试会检验一次纠正是否会改变一个全新 Agent 的行为。以下是我们自己的测量结果——包括那些不太光彩的部分。

_{🔁 可从此仓库重新生成 · 🔒 在所有者的私有存储上自行测量，无法在此复现。方括号内为 95% 区间。80.8% 的嵌入结果是在本地使用可选模型测得的（CI 不会下载该模型，因此没有提交任何产物）。耗时取决于机器；CI 会检查架构和确定性，不会对耗时数值设门槛。}

与其他记忆工具的对比

_{竞品数据为其自行公布的数字，并非并排测量得出。市场概览：docs/research/agent-memory-landscape-2026-07.md。}

安装

MCP 服务 — 面向 Agent

# Claude Code
claude mcp add --scope user agent-recall -- npx -y agent-recall-mcp

# Codex
codex mcp add agent-recall -- npx -y agent-recall-mcp

// Cursor — .cursor/mcp.json   ·   Windsurf — ~/.codeium/windsurf/mcp_config.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"] } } }

Skill — Claude Code

mkdir -p ~/.claude/skills/agent-recall
curl -o ~/.claude/skills/agent-recall/SKILL.md \
  https://raw.githubusercontent.com/Goldentrii/AgentRecall-X/main/SKILL.md

SDK — JS/TS 应用

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");

每个实例都有自己的隔离根目录（AsyncLocalStorage），因此并发实例之间绝不会共享状态。

CLI — 终端、CI、钩子

npx agent-recall-cli recall "rate limiting"
ar bootstrap            # scan git repos, Claude AutoMemory, CLAUDE.md files (read-only, secrets untouched)
ar bootstrap --import   # import what it found

可选扩展

ar embeddings setup     # one-time: local runtime (~380 MB) + model (~145 MB), cached
ar embeddings rebuild   # incremental — only new/changed content embeds
export AGENT_RECALL_EMBEDDINGS=1
ar embeddings status

架构

packages/
├── core/         storage, retrieval, math, tool logic     agent-recall-core
├── mcp-server/   thin MCP wrappers                        agent-recall-mcp
├── sdk/          programmatic API                         agent-recall-sdk
└── cli/          the `ar` command + hooks                 agent-recall-cli

flowchart LR
    Q[query] --> T[tokenize · stem<br/>synonyms · IDF]
    T --> P[palace<br/>0.9 key + 0.1 salience]
    T --> J[journal<br/>0.5 recency + 0.5 exact]
    T --> I[insights<br/>relevance · exact · confirm]
    T --> K[corrections<br/>exact · severity · proof]
    Q -. opt-in .-> V[local embeddings<br/>cosine top-8]
    P & J & I & K & V --> F["RRF  Σ w/(60+rank)"]
    F --> B["× Beta feedback"]
    B --> C[calibrated confidence]
    C --> R[results + alsoLinked]

所有记忆均为本地 Markdown。可选的 Supabase 镜像会添加 pgvector 召回，并采用相同的 RRF 融合；默认仍为完全本地模式。写入通过支持进度感知的文件锁进行，并采用兼容 NTFS 的释放方式；对齐和反馈日志均为仅追加的 NDJSON。

平台

CI 会在 ubuntu-latest 和 windows-latest 上运行构建、回归和测试。

社区

• 💬 Telegram — 提问、反馈、需求
• 🗣️ GitHub Discussions — 实测报告、基准数据、适配器、中文区
• 🐛 GitHub Issues — 错误和功能请求
• 📦 npm： agent-recall-mcp · agent-recall-sdk · agent-recall-cli

提示

最有价值的 15 分钟贡献。 目前领域内的正面结果均由厂商挑选，且没有用于衡量行为变化的外部基线。使用 AgentRecall 一周，然后：

git clone https://github.com/Goldentrii/AgentRecall-X.git && cd AgentRecall-X
npm ci && npm run bench    # reads your local ~/.agent-recall corpus

将结果发布到 Discussions → Benchmark Numbers — 得分低也是有效结果。更多信息请参阅 CONTRIBUTORS-WANTED.md。

贡献者

感谢 @buer5、@lonelyhty 和雷昊完成 Windows 可移植性相关工作并修复了问题，这些改进已随 3.5.x 发布。

链接

• README.full.md — 完整参考：SDK API、CLI、所有工具参数
• packages/core/src/MATH.md — 所有公式、常量和标签
• docs/eval/REPRODUCE.md — 重新生成所有 🔁 数值
• CHANGELOG.md · UPDATE-LOG.md — 变更内容及原因
• Correction-transfer benchmark spec · Agent-memory landscape 2026
• SKILL.md — Claude Code 技能 · AGENTS.md — 适用于在此代码库中工作的 Agent
• 旧版 README：docs/archive/README-2026-10-13.md

贡献

欢迎提交 PR。对于任何重要改动，请先创建 issue — 本项目的设计有明确主张，并以已发表的研究为依据；我们也希望改动以同样的方式为依据：有公式、有标签、有测量结果。

许可证

MIT — 参见 LICENSE。