CommitLore 是面向编码智能体的 Git 原生决策记忆工具，适用于 Claude Code、Codex、Cursor 等编码智能体。它的核心目标是解决“代码保留了结果，却没有保留判断”的问题：团队因为某个不明显的约束否决了一种方案，最终代码只留下了结果，后来的智能体看不到被否决的原因，可能再次提出同样的方案。CommitLore 将约束、被否决的替代方案和警告保留在代码旁边，并且只向智能体提供当前仍然有效的决策，而不是把仓库已经推翻的决定再交给它。
主要能力方面，CommitLore 以 Git 原生的方式存储记录，记录保存在普通的 Git trailer 和 notes 中，因此可以随代码一起分支、合并、克隆、审查，并在更换托管服务后仍然存在。SQLite 仅作为可重建的索引，删除它不会丢失 Git 中的记录。它强调“相关性”与“权威性”的区别：通用记忆或检索系统问的是“哪些旧文本看起来相关”，而 CommitLore 问的是“哪些已记录的决策现在仍然适用于这个路径”。已被取代的决策可能高度相关，但作为当前指导可能是错误的。工作流程包括捕获（智能体只起草 diff 无法展示的决策上下文）、验证（对照会话与暂存 diff 检查草稿）、保存（被接受的记录连同身份和生命周期保存在 Git 中）和交付（在后续编辑前只返回该路径的活动记录）。大多数提交不应携带记录，CommitLore 只用于代码无法保留的判断，而不是叙述每一次更改。
使用方式上，安装需要 Node.js 22.23.2+ 和 Git，安装脚本会在写入任何内容前检查两者。安装后会获得一个固定版本的源码检出和一个运行 node <checkout>/dist/commitlore.mjs 的包装器，无需编译下载或构建步骤。插件不会把 commitlore 加入 PATH，因此使用命令时仍需安装 CLI。安装后需要对希望使用它的每个仓库执行初始化。初始化会遵守 core.hooksPath 并保留已有 hook，将其移动为 <hook>.commitlore-chained 并优先调用；卸载时恢复。在受支持的技能集成中，普通提交请求会考虑 CommitLore，没有值得保留的内容时保持静默，无需在每次提交时点名它。仓库可以一次性用 commitlore auto on 选择让被接受的记录自动暂存。
针对 squash-merge 仓库，squash 合并会用一个新的提交替换分支的提交，而该提交不携带分支的 trailer，因此分支上做出的记录会被合并丢弃。解决办法之一是添加 .github/workflows/commitlore-preserve.yml。由于 pull_request_target 使用可写令牌，编辑该工作流时不得检出拉取请求的 head，也不得执行任何从 refs/commitlore/pr-head 可达的内容；来自 fork 的提交应作为数据读取 trailer，而不是作为代码运行。使用 merge commit 或 rebase 合并时记录会自行保留，无需此设置。
适用场景是为有历史的代码仓库提供决策记忆，让后续智能体在编辑特定文件时只看到仍然有效的约束、被否决的替代方案和警告，减少重复评审同一个坏主意。它面向编码智能体工作流，不是通用用户记忆系统、对话存档或向量数据库替代品。
限制方面，捕获是辅助性的而非确定性的，没有宿主被认证为能评估每一个符合条件的提交。默认指令模式不是身份验证，它只匹配提交作者头部，任何能写提交的人都可以设置该头部，因此默认模式下的 [directive] 是策略元数据而非身份证明；签名模式额外要求 Git 的已验证状态以及仓库本地 commitlore.trustedSigner 允许列表中的匹配项，允许列表缺失、为空或不可读时不授权任何人，该模式会安全失败。Guard 是实验性建议而非安全网，在 417 个决策语料上精确率 44.8%（95% Wilson 置信区间 32.7%–57.5%），召回率 22.0%，空的 guard 结果不是安全判定。交付会在每次匹配的工具调用上消耗 token，编辑前 hook 在 Read 以及 Edit、Write、MultiEdit 和 NotebookEdit 上都会触发，每次触发最多消耗默认 800 token 的负载预算，可用 --budget 更改；没有记录的仓库不会消耗。回答可能是部分的，覆盖范围会披露，部分结果中缺失并不证明没有记录。提交 trailer 会随克隆传播，notes 不会，Git 默认不获取 refs/notes/*，因此 refs/notes/commitlore 中的记录在普通克隆中缺失，直到 commitlore init 配置该镜像。没有托管后端，但一旦服务器或 hook 返回上下文，宿主会按自身策略处理该上下文。记录在被分级前视为不可信，注入形态的负载会从模型可读路由中扣留。
安装、升级与卸载、捕获工作流、记录协议、证据与限制、生产契约等详细文档可在仓库中查看，项目采用 MIT 许可证。
