CommitLore
让编码代理只接收仍然有效的 Git 决策、约束与警告。
- Star 数
- ★ 19
- 最近更新
- 1 个月前
- License
- MIT
- 主语言
- TypeScript
- FA 评分
- 78/100 · 表现良好
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Codex · Claude Code(部分支持)
- 费用
- 免费,无需付费服务
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 维护长期代码库的团队,可记录某项架构方案为何因隐藏约束而被否决,避免后续代理再次建议同一路线。
- 不适合
- 需要托管记忆或云端同步的团队,记录只存在 Git 里
- 把记忆系统当作通用对话归档或向量数据库替代品的用户
- 需要确定性捕获、要求每次提交都被评估的团队
- 维护状态
- 近半年有提交最近提交 2026-10-18最新版本 v1.7.5(2026-10-18)
- 源码审查
- 78/100 · 表现良好
这个 Agent 能做什么,适合哪些场景?
CommitLore 是面向编码代理的 Git 原生决策记忆系统,重点保存代码差异无法表达的约束、被否决方案和警告。它提供 CLI、提交钩子、Claude Code 与 Codex 插件,以及供其他受支持宿主使用的 MCP 接口。记录以 Git trailer 或 refs/notes/commitlore note 保存,SQLite 仅作为可重建索引,因此决策记录由仓库持有。系统按仓库路径和生命周期筛选记录,在代理编辑文件前仅交付仍处于 active 状态的相关内容,并按 directive、claim 或 blocked 标示信任等级。它适合需要避免代理重复提出已被否决方案的团队,但不是通用会话存档、用户记忆或向量数据库替代品。
端到端流程由 Capture、Verify、Preserve 和 Deliver 四步组成。commitlore capture 为代码差异无法保留的决策背景生成候选记录,并依据会话转录与已暂存 diff 进行检查;接受后的记录进入 Git trailer 或 refs/notes/commitlore。commitlore stale 区分 active、superseded 和 expired 记录,commitlore context 根据代理即将编辑的路径选择当前仍有效的记录。插件钩子或 MCP 在编辑前交付结果;内容会依据默认模式或签名模式被分级为 directive、claim 或 withheld,而交付本身不会阻止编辑。commitlore doctor 检查安装、旧钩子和 squash 继承等状态,commitlore coverage 则说明扫描覆盖范围。
- 维护长期代码库的团队,可记录某项架构方案为何因隐藏约束而被否决,避免后续代理再次建议同一路线。
- 使用 Claude Code 或 Codex 修改敏感模块的开发者,可在编辑前自动取得与目标路径有关的有效决策。
- 希望由仓库而非托管记忆服务控制工程知识的组织,可将记录保存在 Git trailer 或 notes 中并随代码审查和迁移。
- 需要管理决策变更的项目,可将旧记录标记为 superseded 或 expired,避免相关但已失效的内容被当作当前指令。
- 采用 GitHub Squash and merge 的团队,可配置
action/preserve,在分支提交被压缩时继承 CommitLore 记录。
安装与配置要点
摘自下方的安装和使用说明,以项目 README 的最新说明为准。
- 安装 / 启动命令
curl -fsSL https://raw.githubusercontent.com/MongLong0214/commitlore/v1.5.1/install.sh | sh -s v1.5.1
- 运行环境
- Node.js 22.23.2
- 安装说明涉及
- Windows · macOS · Linux
如何安装或部署这个 Agent?
需要 Node.js 22.23.2 或更高版本以及 Git。macOS 和 Linux 可运行:
curl -fsSL https://raw.githubusercontent.com/MongLong0214/commitlore/v1.5.1/install.sh | sh -s v1.5.1Windows 可运行:
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/MongLong0214/commitlore/v1.5.1/install.ps1))) v1.5.1Claude Code 的连接步骤是:
/plugin marketplace add MongLong0214/commitlore
/plugin install commitlore@commitloreCodex 的连接步骤是:
commitlore plugin install-codex插件不会把 commitlore 加入 PATH,因此仍需单独安装 CLI。安装或更新插件后应启动新的代理会话。
如何使用这个 Agent?
进入目标 Git 仓库,初始化 CommitLore,并先查询一次当前目录的上下文:
cd your-repository
commitlore init
commitlore context .之后照常工作和提交。受支持的 skill 集成会在普通提交请求中考虑是否需要保存决策;多数提交不应产生记录。若团队希望已接受的记录无需逐条确认即可暂存,可为仓库显式启用:
commitlore auto on该设置属于仓库级团队策略。若使用 GitHub 的 Squash and merge,还需按项目提供的工作流配置 action/preserve;本地 git merge --squash 则由 commitlore init 安装的 prepare-commit-msg 钩子处理。
这个 Agent 有哪些优点和局限?
- 记录保存在普通 Git trailer 或 notes 中;SQLite 只是可重建索引,不是唯一事实来源。
- 路径范围与 active、superseded、expired 生命周期过滤相结合,可防止已撤销决策继续作为当前指导交付。
- 区分 directive、claim 和 blocked,并提供需要 Git 验证及仓库本地 signer allowlist 的更强签名模式。
- 同时提供 CLI、提交钩子、Claude Code/Codex 插件和 MCP 路径,覆盖多种编码代理宿主。
- 公开的测量包含边界和负面结果;所述实验中,路径范围在固定两条记录预算下保留了 2/2 相关记录。
- 捕获是辅助式流程,任何宿主都未被认证为会对每个符合条件的提交进行确定性评估。
- Node.js 22.23.2+ 与 Git 是硬性运行要求,插件安装也不能替代 CLI 安装。
- Git notes 默认不会随普通 clone 获取;必须通过
commitlore init配置refs/notes/commitlore镜像。 - GitHub Squash and merge 会丢失分支 trailer,必须额外部署具有
contents: write权限的保留 Action。 - 编辑前钩子也会在 Read 等工具调用时触发,每次匹配调用最多消耗配置的上下文预算;默认上限为 800 tokens。
- 公开效果数据来自有限模型、单一工具链或构造任务,不能证明所有模型都会读取或遵循交付的记录。
这个 Agent 与同类方案有什么区别?
通用记忆或 RAG 主要检索语义上相关的旧文本;CommitLore 询问的是哪些决策现在仍适用于特定仓库路径。它以 Git 为权威来源,显式管理 active、superseded、expired 生命周期,并对交付内容划分 directive、claim 和 blocked,而不是把所有相关文本直接当作当前指导。相应地,它的范围更窄,不适合作为会话归档、通用用户记忆或向量数据库的替代品。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| CommitLore 当前 | 78 · 表现良好 | 命令行工具免费 | ★ 19 | 1 个月前 | TypeScript | — |
| PowerContext | 82 · 表现良好 | 命令行工具免费 | ★ 1.8k | 1 天前 | Python | Codex · Claude Code |
| Agent Systems Handbook | 62 · 存在缺口 | 网页应用免费 | ★ 315 | 1 个月前 | MDX | — |
| Agent Graph | 53 · 缺口较多 | 自托管服务免费 + 模型费 | ★ 239 | 4 天前 | Python | — |
FollowAgents 如何评估这个 Agent?
查看各维度的扣分理由
MCP 源码说明查询来自本地 Git 和索引、没有网络客户端,并对模型路由隐藏 blocked 内容;安全文档区分默认作者字符串匹配与签名白名单。安装器检查前置条件、默认不启用自动记录,卸载与钩子恢复路径明确,因此多数权限和回滚问题处理充分。敏感内容有捕获扫描的说明,但未给出扫描范围或误报边界;依赖安全也未提供锁文件或漏洞审计证据,故不满分。记录作者字段和仓库链接可见,但发布者身份仍未知,不能据品牌加分。
协议、CLI、MCP 和 CI 文档多处描述相同的记录生命周期与限制;README 也明确指出捕获并非确定性,且 squash 合并需额外继承配置。材料仍存在局部张力,例如 AGENTS.md 称可直接遵循 directive,而安全文档说明默认作者匹配不是身份认证;因此自洽性扣分。Node/Git 前置要求、失败退出码和诊断示例有说明,但没有覆盖所有依赖故障与恢复分支。
材料具体说明了 Claude Code、Codex、Hermes、MCP 及遵循 AGENTS.md 的主机,并区别自动投递、捕获辅助与尚未认证的确定性捕获。查询、捕获、初始化、诊断、签名信任和多种安装方式均有清晰边界。普通提交触发依赖主机选择 skill,且 token 消耗会随匹配工具调用发生;跨主机的环境兼容证据主要是文档说明,未在本次静态审查中执行验证。
文档按安装、CLI、捕获、协议、安全和证据分层,示例、卸载与限制说明具体;MIT 许可证文本完整。版本固定为 1.7.5、协议标为 2.0 stable,并有 ADR 与 CI,但给定材料未包含集中式发布日志或明确维护者责任机制,发布者来源也未验证,因此版本和责任项只给部分分。
路径范围、生命周期筛选、信任分级和结构化查询输出能形成可用的决策上下文,README 提供样例并披露基准边界。记录内容并非普遍提高代理行为的证明,且项目明确承认捕获不确定、guard 召回有限、每次匹配调用有 token 成本;所以价值有根据但收益成本尚非全面确立。
README 数值链接到方法说明,ADR 明确划定定位表述与效果主张,CI 工作流展示了可机器核验的规范、构建和基准检查;这对主张追溯与区分事实、推断支持较强。跨来源印证只给了选定文件,样本并非全仓库,也没有在本审查中运行这些检查,故不作满分。
- 默认 directive 信任基于可伪造的提交作者字符串;面对不可信提交者时,应使用签名验证和仓库本地 signer 白名单。
- 捕获取决于主机是否启动 skill,并非每个合格提交都会评估;squash 合并可能丢失记录,除非配置继承 Action。
- 投递会消耗 token,且记录只是上下文;guard 的空结果不代表安全,也不证明代理会遵循记录。
最近版本
来自该项目 GitHub Releases 的最新发布记录,说明为上游原文摘录,未经本站改写或测试。
-
发布说明摘录
init can leave the working tree exactly as it found it If a script runs commitlore init as part of checking that a checkout is clean, this is the release you want. init writes one file inside the working tree: the PreToolUse injection hook at .claude/settings.json. It is untracked, so after init the tree is no longer clean — and a caller whose whole job is to verify a clean checkout then sees its own observation as a change: ```sh git status --porcelain --untracked-files=all # empty commitlore init --mcp-scope none --no-unattended </dev/null …在 GitHub 查看 ↗ -
发布说明摘录
Two production advisories, and the three capture faults a 118.7 MB transcript uncovered Take this one. It patches a high and a critical advisory in dependencies that ship with the CLI. | package | severity | advisory | |---|---|---| | @modelcontextprotocol/sdk → 1.32.1 | high | OAuth client could send credentials to an authorization server the MCP server chose ([GHSA-6qxp-vccf-f47h](https://github.com/advisories/GHSA-6qxp-vccf-f47h)) | …在 GitHub 查看 ↗ -
发布说明摘录
A paragraph that holds no record was being inherited as one If you squash-merge with squash-preserve, take this one. A squash merge in another repository was refused by commitlore validate and could not land: ``` shape failed · 169: unknown-key Claude-Session — got "Claude-Session", want "a key from SPEC §3, or X-Claude-Session if this is your own metadata" ``` The range held an ordinary merge commit with no record at all. Its last paragraph was a single line: ``` Claude-Session: https://claude.ai/code/session_… ``` …在 GitHub 查看 ↗
常见问题
没有任何决策记录的仓库会持续消耗上下文吗?
默认的 directive 能证明作者身份吗?
commitlore.trustedSigner allowlist;allowlist 缺失、为空或不可读时不会授权任何人。删除 SQLite 索引会丢失决策吗?
普通 clone 一定包含全部记录吗?
refs/notes/*;运行 commitlore init 后才会配置 notes 镜像。部分扫描的缺失结果也不能证明记录不存在,可用 commitlore coverage 检查覆盖范围。CommitLore 会阻止代理违反记录吗?
CommitLore 免费吗?
CommitLore 开源吗?
CommitLore 安全吗?
CommitLore 还在维护吗?
谢谢反馈,我们会据此改进页面。