Skip to main content
Glama
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 做什么

行为

产品路径

捕获

保留 diff 无法展示的约束、被否决的备选方案和警告。候选记录会与会话记录和暂存的 diff 进行核对。

commitlore capture

保存

将已接受的记录存储在 Git trailers 或 notes 中,而不是托管的记忆数据库。

commit hooks · refs/notes/commitlore

跟踪生命周期

区分有效、被取代和已过期的决策。

commitlore stale

限定范围

为代理即将编辑的路径选择相关决策。

commitlore context

分级信任

将记录作为指令、声明或保留内容交付。

默认 / 签名模式

交付

在编辑前为受支持的代理提供当前上下文。

插件钩子 · MCP

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

Related MCP server: memini

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 会将其放回原位。

自动发生什么

主机

编辑前交付

已验证的捕获工作流

确定性的每次提交捕获

Claude Code

通过插件自动完成

通过插件技能可用

未认证

Codex

通过插件自动完成

通过插件技能可用

未认证

Hermes

在 commitlore hermes install 后可用

在主机安装后可用

未认证

Gemini CLI、Cursor、Windsurf、opencode

主机使用注册时通过 MCP 交付

通过 MCP 暴露流程

否

AGENTS.md 主机

仅流程

仅流程

否

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

受支持技能主机的用户不需要在每次提交时都说"在 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 不是指令,所以它在同意之前对照代码核对了所述理由。

与记忆存储的区别

通用记忆 / RAG

CommitLore

首要问题

哪段旧文本相关?

哪些决策现在仍然适用于这里?

权威

记忆存储或提供商

Git

范围

语义相似性

仓库路径

生命周期

通常只追加

有效 · 被取代 · 过期

信任

检索到的文本

指令 · 声明 · 阻止

捕获

记录或笔记存储

经证据核对的决策记录

可移植性

依赖后端

普通 Git

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

证据

问题

测量结果

边界

在注册研究中,声明级上下文是否改变了重新提案?

2.8% (16/580) 使用 CommitLore,而18.8% (109/579) 未使用

一个模型、一个测试框架、构造的任务

生命周期过滤是否在测量的活动投影中交付了已退役记录?

0 条退役记录

存在被取代的记录;过期未被触发;

索引查找是否可扩展?

100k 次提交时 p50 为 496 ms

无索引回退要慢得多

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

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

路由

模型可见记录

相关记录

模型可见 token

注入全部内容

10,002

2/2

1,004,554

top-k 词法

2

1/2

190

CommitLore 路径范围

2

2/2

335

这衡量的是在固定两条记录的预算下的暴露度和召回率——而非 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 定义了生命周期、信任等级、验证和兼容性。

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

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

证据 → · 自我审计 →

文档

贡献

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

许可证

MIT — 参见 LICENSE。

Available Tools

8 tools
commitlore_before_changeA
Read-only

Everything recorded about a path, before editing it: the active decisions, the gaps in what could be verified, and any ruled-out alternative a proposal would revive. Returns active_decisions, verification_gaps, possible_revival_matches, guard_confidence and cache_key. Pass path alone for context. Pass proposal as well to also run the guard against that path's Ruled-out records; without it guard_confidence is "not-run" and possible_revival_matches is empty because nothing was checked, not because nothing matched. The guard is an experimental advisory: precision 44.8%, recall 22.0% on the 417-decision corpus. An empty possible_revival_matches does not guarantee the proposal avoids every ruled-out alternative.

Inputs: path (required), proposal.

commitlore_guardA
Read-only

Check a proposal against the Ruled-out records for a path before acting on it. Returns every record whose alternative matches, with the reason it was rejected. Experimental advisory: precision 44.8%, recall 22.0% on the 417-decision corpus. An empty matched array does not guarantee the proposal avoids every ruled-out alternative.

Inputs: proposal (required), path.

commitlore_prepare_captureA

Prepare a capture transaction: computes binding conditions (HEAD, staged diff, tree, policy hash), generates the prompt contract for the agent to use, and persists a phase:"prepared" pending transaction. Returns the nonce needed for verify and stage. The prompt carries the end of the transcript rather than all of it; transcript_window says which lines, numbered as the whole transcript numbers them. Verification still reads the whole transcript, so quote only what the prompt shows you. The transaction binds to THIS server's checkout, returned as repository; if your working directory is a linked worktree or another clone, pass repository to assert it and this refuses rather than binding to the wrong HEAD.

Inputs: transcript (required), repository, unattended.

commitlore_queryA
Read-only

Active CommitLore records for a path: the constraints, ruled-out alternatives and warnings recorded in git history. Same answer as commitlore <kind> --json.

Inputs: kind (required), path.

commitlore_runtime_identityA
Read-only

Report the exact CommitLore entrypoint, package root, version and index schema this MCP server executes.

Inputs: no named parameters.

commitlore_stage_captureA

Stage a verified capture transaction: advances the pending record from verified to staged, stamps expires_at (staged_at + 5 minutes), and makes it eligible for the prepare-commit-msg hook. All bindings are server-owned and computed from stored state; the only inputs are the nonce and, optionally, the receipt your verification was issued.

Inputs: nonce (required), receipt.

commitlore_staleA
Read-only

Records that are no longer carrying their weight: superseded, past a date-form Expires:, or flagged for review by a condition-form one. Same answer as commitlore stale --json.

Inputs: no named parameters.

commitlore_verify_captureA

Verify a capture draft against the transcript and diff that were hashed at prepare time. Evidence citations are checked mechanically (verbatim match); fabricated quotes are discarded. Stores the verified result in the pending transaction for stage to consume.

Inputs: draft (required), nonce (required), transcript (required), diff.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 8 tools

    Disambiguation3/5

    The capture lifecycle tools (prepare/verify/stage) are clearly separated by phase, and stale/runtime_identity are distinct. However, before_change, query, and guard overlap: before_change already runs the guard when a proposal is supplied, and query also returns ruled-out alternatives for a path. The descriptions help, but an agent could easily pick the wrong one for a pre-edit context lookup.

    Naming Consistency4/5

    All tools share the commitlore_ prefix and use lowercase snake_case, which is a clear and consistent pattern. The capture tools use verb_noun (prepare_capture, verify_capture, stage_capture), but before_change, stale, and runtime_identity are stylistic deviations, so the set is mostly consistent rather than fully uniform.

    Tool Count5/5

    Eight tools is well-scoped for this server's purpose: three for the capture pipeline, three for reading/guarding context, plus stale and runtime identity. Each tool has a place and the set feels neither bloated nor thin.

    Completeness4/5

    The core workflow is covered: retrieving records/context, checking proposals, and the prepare/verify/stage capture pipeline. Minor gaps exist—such as no direct way to update, dismiss, or resolve stale records—but these are workable and may be intentionally outside the MCP surface.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      Local-first memory layer for AI coding agents — captures issues, attempts, fixes, and decisions, and warns at git commit before you repeat a mistake.
      19
      978 PyPI
      877
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Local-first project memory for AI coding agents. Records failed attempts, fragile files, and decisions per repo, and warns the agent via hooks before it repeats a recorded mistake.
      6
      59 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides AI coding agents with git-native persistent memory and a dependency-aware task graph, letting them record and fuzzy-recall architectural decisions, lessons, and gotchas while creating, claiming, and completing tasks that auto-unblock downstream work. Stores everything as plain JSON and Markdown committed inside the repository, so context stays branch-aware, team-shared, and reviewable in pull requests.
      6 npm
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables coding agents to persist and retrieve ADR-style decisions and machine-checkable constraints as git-friendly markdown in a repository, linked to requirement ids, tests and commits. Agents can pull relevant context before a task, check a proposed change against accepted constraints before committing, and record, supersede or search decisions over a local stdio connection.
      7
      23 npm
      MIT