CommitLore

curl -fsSL https://raw.githubusercontent.com/MongLong0214/commitlore/v1.2.0/install.sh | sh -s v1.2.0

curl -fsSLO https://raw.githubusercontent.com/MongLong0214/commitlore/v1.2.0/install.sh
sh install.sh v1.2.0

# Or skip the script: the checkout it makes is one you can make yourself.
git clone --depth 1 --branch v1.2.0 https://github.com/MongLong0214/commitlore
node commitlore/dist/commitlore.mjs --version

它安装一个固定版本的源码检出和一个包装器，运行 node <checkout>/dist/commitlore.mjs——无需下载编译产物，无需构建步骤。

代码存续。判断不存续。

代理提出一种方案。你的团队因为一个不明显的约束而否决了它。最终代码保留了结果，但通常没有保留为什么备选方案被否决。后来的代理只看到代码，又提出了同样的想法。

CommitLore 将这种判断保存在代码旁边。

CommitLore 做什么

大多数提交不应携带记录。CommitLore 用于代码无法保存的判断，而不是叙述每一次变更。

Related MCP server: Hypermnesic

60 秒让代理具备决策感知

1. 安装 CLI

macOS 和 Linux：

curl -fsSL https://raw.githubusercontent.com/MongLong0214/commitlore/v1.2.0/install.sh | sh -s v1.2.0

Windows：

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/MongLong0214/commitlore/v1.2.0/install.ps1))) v1.2.0

需要 Node.js 22.23.2+ 和 Git。脚本在写入任何内容之前会检查两者。

2. 连接你的代理

Claude Code：

/plugin marketplace add MongLong0214/commitlore
/plugin install commitlore@commitlore

Codex：

commitlore plugin install-codex

插件不会将 commitlore 加入 PATH，因此下面的命令也需要安装 CLI。安装程序还会在安全的情况下检测并接入受支持的 MCP 主机；具体矩阵见下文。

3. 初始化仓库

cd your-repository
commitlore init
commitlore context .

安装或更新插件后，请启动新的代理会话：正在运行的会话会保留其加载的运行时。

然后正常工作和提交。在受支持的技能集成中，CommitLore 会在普通提交请求期间被考虑，并在没有值得保存的内容时保持沉默。你不需要在每次提交时都提到 CommitLore。

希望已接受的记录无需逐条提示即可暂存？仓库可以一次性通过 commitlore auto on 选择启用。该策略归仓库所有并适用于整个团队，因此本页面不会静默启用它。

代理会收到什么

在编辑 src/pricing.ts 之前：

commitlore: active records for src/pricing.ts

Limit
  [claim] r-price01  calculatePrice owns final checkout pricing only

Ruled-out
  [claim] r-price01  Reuse it for admin quotes |
                     eligibility and rounding semantics differ

[claim] 表示"将其作为信息来权衡"。仓库可以选择启用更强的签名权威模式。交付为代理提供上下文；它不会阻止编辑。

安全模型 →

为什么选择 Git？

仓库应该拥有其代码背后的判断。

CommitLore 将记录存储在普通的 Git trailers 和 notes 中，因此它们会随其所解释的代码一起分支、合并、克隆、审查，并在提供商变更后继续存在。

SQLite 只是一个可重建的索引。删除它，Git 仍然持有记录。

找到旧决策还不够

一般的记忆或检索系统会问：

哪段旧文本看起来相关？

CommitLore 会问：

哪些已记录的决策现在仍然适用于这条路径？

一个被取代的决策可能高度相关，但作为当前指导仍然是错误的。相关性和权威性是不同的问题。

工作原理

1. 捕获 —— 代理只起草 diff 无法展示的决策上下文。

2. 验证 —— CommitLore 将会话和暂存 diff 与草稿进行核对。

3. 保存 —— 已接受的记录以身份和生命周期存在于 Git 中。

4. 交付 —— 在后续编辑之前，只返回该路径的有效记录。

大多数提交不携带记录。提交钩子在存在记录时验证记录；它不会凭空创造记录。

现有钩子不会被覆盖。commitlore init 尊重 core.hooksPath，将已安装的钩子移动到 <hook>.commitlore-chained，并先调用它；commitlore hooks uninstall 会将其放回原位。

自动发生什么

"可用"意味着准备 → 验证 → 暂存的工作流存在。这并不意味着每个符合条件的提交都会被自动评估。

受支持技能主机的用户不需要在每次提交时都说"在 CommitLore 中记录这个"。剩余的局限是主机发起，而不是需要逐条记录的用户命令。

一份实地报告，而非测量结果

一次运行，在一个无关的仓库上，由一位首次安装 v1.2.0 的人完成。这里没有任何内容是经过测量的，也不在证据日志中。它出现在本页是因为上面那段话断言了一个本页任何表格都未覆盖的循环。

他们让代理修复一个舍入错误，顺带提到一个十进制库已经被考虑过并放弃了，最后说"提交它"。CommitLore 从未被提及。提交所携带的部分内容：

Ruled-out: adopting a decimal library such as Decimal.js | the backend is a
  number contract, so it is meaningless
Warn: do not revert the test file to console.assert: it exits 0 even on
  failure, so CI passes silently
Provenance: drafted

Warn 不是强加给代理的。它在工作时撞上了这个陷阱，并把它留给了后来者。Provenance: drafted 记录着没有人类阅读过该记录，这将其分级为 claim——作为一份需要权衡的报告交付，而不是命令。

一个没有共享历史的后续会话被要求最终采用那个十进制库。它没有采用，并点名该记录作为其理由。它还读取了分级：claim 不是指令，所以它在同意之前对照代码核对了所述理由。

与记忆存储的区别

CommitLore 有意做得更窄。它不是通用的用户记忆系统、对话存档或向量数据库的替代品。

证据

索引构建时间取决于记录的数量，而不是提交的数量：昂贵的遍历对每条记录只运行一次，因此一条历史很长但记录很少的仓库，其构建速度比一条记录密集但历史较短的仓库更快。

路径范围是让大量历史不触及模型的原因。在 #167 语料上，10,002 条记录中只有 2 条被触及：

这衡量的是在固定两条记录的预算下的暴露度和召回率——而非 token 成本、计费成本、准确性或智能体行为。一个语料、一个查询、一个固定的嵌入模型。

智能体研究并未确立普遍的模型效应。交付并不能证明模型读取或遵循了某条记录。

方法、完整表格、排除项和负面结果 →

限制、信任与隐私

• 捕获是辅助性的，而非确定性的。 受支持的技能会考虑普通的提交请求，但没有哪个宿主被认证为能评估所有符合条件的提交。

• 默认指令模式并非身份验证。 它匹配提交作者头，而任何能写入提交的人都可以设置该头部——因此默认模式下的 [directive] 是策略元数据，而非身份证明。签名模式额外要求 Git 自身的验证状态，并在仓库本地的 commitlore.trustedSigner 允许列表中匹配；如果签名者允许列表缺失、为空或不可读，则不会授权任何人，因此该模式会失败关闭。

• Guard 是实验性建议，而非安全网： 在 417 个决策的语料上，精确率为 44.8%（95% Wilson 置信区间 32.7%–57.5%），召回率为 22.0%。空的 Guard 结果并非安全结论。

• 交付会在每次匹配的工具调用上消耗 token。 编辑前钩子会在 Read 以及 Edit、Write、MultiEdit 和 NotebookEdit 上触发，因此其运行频率远高于编辑代理提交的频率。每次触发最多消耗负载预算——默认 800 个 token，可通过 --budget 更改。没有记录的仓库不会消耗任何 token，这意味着这是一项随采用而非随安装而来的成本。

• 答案可能是部分的。 覆盖率会被披露；部分结果中的缺失并不能证明不存在记录。仓库级覆盖率、符号锚点和交互式记录构建器仍是开放项： #32、 #33。

• 提交尾部会随克隆一起传播；注释则不会。 Git 默认不会获取 refs/notes/*，因此 refs/notes/commitlore 中的记录在普通克隆中不存在，直到 commitlore init 配置了该镜像。

• 没有托管后端。 但一旦服务器或钩子返回上下文，宿主就会根据其自身策略处理该上下文；CommitLore 不控制该数据流。

安全 · 兼容性 · 证据

记录在分级之前是不可信的。默认作者匹配是策略元数据，而非身份验证。签名指令模式要求 Git 验证和仓库本地的签名者允许列表；缺失或不可读的允许列表不会授权任何人。注入形状的负载会从模型可读的路由中剔除。

完整安全模型 →

CLI 安装程序无法重写它不知道的仓库中的钩子，而正在运行的宿主会话会保留其加载的运行时。commitlore doctor 会指出这两种状态及其修复方法，commitlore upgrade 会报告是否存在更新版本。

安装与升级 →

记录是普通的 Git 尾部或注释。协议 2.0 定义了生命周期、信任等级、验证和兼容性。

人工指南 → · 规范性规范 →

该仓库发布了方法、排除项、不成功的测量，以及原始基准或诊断出错的情况。

证据 → · 自我审计 →

文档

• 安装、升级与卸载

• CLI 参考

• 捕获工作流

• 记录协议

• 安全模型

• 证据与局限性

• 生产契约

• 文档索引

贡献

CONTRIBUTING.md 涵盖了本仓库对自身所要求的记录协议、发布门槛，以及如何复现证据。

许可证

MIT — 参见 LICENSE。