commitlore

CommitLore

Stop re-reviewing the same bad idea.

Decision authority for coding agents, owned by Git.

Keep constraints, rejected alternatives, and warnings in Git — then deliver

only what is still in force, so an agent is not handed a decision the

repository already reversed.

No hosted memory. The repository owns the record.

English ·

·

·

Install once. Then initialise each repository where you want it to work.

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

Prefer to read the installer first?

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

It installs a pinned source checkout and a wrapper that runs

`node /dist/commitlore.mjs` — no compiled download, no build step.

> The code survives. The judgment doesn't.

An agent proposes an approach. Your team rejects it because of a non-obvious

constraint. The final code preserves the outcome, but usually not why the

alternative was rejected. A later agent sees only the code and proposes the

same idea again.

CommitLore keeps that judgment beside the code.

What CommitLore does

Most commits should carry no record. CommitLore is for judgment the code cannot

preserve, not for narrating every change.

60 seconds to decision-aware agents

1. Install the CLI

macOS and 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

Requires Node.js 22.23.2+ and Git. The script checks both before it writes anything.

2. Connect your agent

Claude Code:

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

Codex:

commitlore plugin install-codex

The plugin puts no `commitlore` on `PATH`, so the commands below need the CLI

install as well. The installers also detect and wire supported MCP hosts where

they can do so safely; the exact matrix is below.

3. Initialize a repository

cd your-repository
commitlore init
commitlore context .

Start a new agent session after installing or updating a plugin: a running

session keeps the runtime it loaded.

Then work and commit normally. On supported skill integrations, CommitLore is

considered during ordinary commit requests and stays silent when there is

nothing worth preserving. You do not need to name CommitLore on every commit.

Want accepted records to stage without a per-record prompt? The repository can

opt in once with `commitlore auto on`. That policy is repository-owned and

applies to the team, so it is not silently enabled by this page.

What the agent receives

Before editing `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]` means "weigh this as information." A repository can opt into the

stronger signed-authority mode. Delivery gives the agent context; it does not

block the edit.

Security model →

Why Git?

The repository should own the judgment behind its code.

CommitLore stores records in ordinary Git trailers and notes, so they branch,

merge, clone, review, and survive provider changes with the code they explain.

SQLite is only a rebuildable index. Delete it and Git still holds the record.

Finding an old decision is not enough

A general memory or retrieval system asks:

> Which old text looks related?

CommitLore asks:

> Which recorded decisions still apply to this path now?

A superseded decision can be highly relevant and still be wrong as current

guidance. Relevance and authority are different questions.

How it works

1. Capture — an agent drafts only decision context the diff cannot show.

2. Verify — CommitLore checks the draft against the session and staged diff.

3. Preserve — the accepted record lives in Git with identity and lifecycle.

4. Deliver — before a later edit, only active records for that path are returned.

Most commits carry no record. The commit hook validates a record when one is

present; it does not invent one.

An existing hook is not overwritten. `commitlore init` honours `core.hooksPath`,

moves any hook already installed to `.commitlore-chained`, and calls it

first; `commitlore hooks uninstall` puts it back.

What happens automatically

"Available" means the prepare → verify → stage workflow exists. It does not mean

every eligible commit is assessed automatically.

Users on supported skill hosts do not need to say "record this in CommitLore" on

every commit. The remaining limitation is host initiation, not a required

per-record user command.

A field report, not a measurement

One run, on an unrelated repository, by someone installing v1.2.0 for the first

time. Nothing here was measured and none of it is in the evidence logs. It is on

this page because the paragraph above asserts a loop that no table here covers.

They asked an agent to fix a rounding bug, mentioned in passing that a decimal

library had already been considered and dropped, and ended with "commit it".

CommitLore was never named. Part of what the commit carried:

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

The `Warn` was not dictated to the agent. It hit the trap while working and left

it for whoever came next. `Provenance: drafted` records that no human read the

record, which grades it `claim` — delivered as a report to weigh, not an order.

A later session with no shared history was asked to adopt the decimal library

after all. It did not, and named the record as its reason. It also read the

grade: a `claim` is not an instruction, so it checked the stated reason against

the code before agreeing with it.

Unlike memory storage

CommitLore is intentionally narrower. It is not a general user-memory system,

conversation archive, or vector database replacement.

Evidence

Index build time follows the number of *records*, not the number of commits: the

expensive pass runs once per record, so a long history that has recorded little

builds faster than a short one dense with records.

Path scope is what keeps a large history from reaching the model. On the #167

corpus, only 2 of 10,002 records did:

That measures exposure and recall at a fixed two-record budget — not token cost,

billed cost, accuracy, or agent behaviour. One corpus, one query, one pinned

embedding model.

The agent study does not establish a universal model effect. Delivery is not

proof that a model read or followed a record.

Methods, full tables, exclusions, and negative results →

Limits, trust and privacy

• Capture is assisted, not deterministic. Supported skills consider ordinary

commit requests, but no host is certified to assess every eligible commit.

• Default directive mode is not authentication. It matches the commit

author header, and anyone who can write a commit can set that header — so a

`[directive]` in default mode is policy metadata, not proof of identity.

Signature mode additionally requires Git's own verified status and a match in

the repository-local `commitlore.trustedSigner` allowlist; an absent, empty, or unreadable signer allowlist authorizes nobody, so the mode fails closed.

• Guard is an experimental advisory, not a safety net: precision 44.8% (95% Wilson CI 32.7%–57.5%), recall 22.0% on the 417-decision corpus. An empty guard result is not a safety verdict.
• Delivery spends tokens on every matching tool call. The pre-edit hook

fires on `Read` as well as `Edit`, `Write`, `MultiEdit` and `NotebookEdit`, so

it runs far more often than an editing agent commits. Each fire spends up to

the payload budget — 800 tokens by default, changed with `--budget`. A

repository with no records spends nothing, which means this is a cost that

arrives with adoption rather than with installation.

• An answer may be partial. Coverage is disclosed; absence from a partial

result is not proof that no record exists. Repository-wide coverage, symbol anchors,

and an interactive record builder remain open:

#32,

#33.

• Commit trailers travel with a clone; notes do not. Git does not fetch

`refs/notes/*` by default, so a record in `refs/notes/commitlore` is absent

from an ordinary clone until `commitlore init` configures that mirror.

• There is no hosted backend. But once the server or hook returns context,

the host handles that context under its own policy; CommitLore does not

control that data flow.

Security ·

Compatibility ·

Evidence

Security and trust model

Records are untrusted until graded. Default author matching is policy metadata,

not authentication. Signed directive mode requires Git verification and a

repository-local signer allowlist; an absent or unreadable allowlist authorizes

nobody. Injection-shaped payload is withheld from model-readable routes.

Full security model →

Installation, upgrades, and old hook generations

The CLI installer cannot rewrite hooks inside repositories it does not know

about, and running host sessions retain the runtime they loaded. `commitlore

doctor` names both states and their repair, and `commitlore upgrade` reports

whether a newer release exists.

Installation and upgrades →

Protocol and Git storage

Records are ordinary Git trailers or notes. Protocol 2.0 defines lifecycle,

trust grades, validation, and compatibility.

Human guide → ·

Normative specification →

Evidence and negative results

The repository publishes the methods, exclusions, unsuccessful measurements,

and the cases where the original benchmark or diagnosis was wrong.

Evidence → ·

Self-audit →

Try it on a repository with history.

Tell us where path scope, lifecycle, capture, or installation breaks.

·

Documentation

• Install, upgrade, and uninstall
• CLI reference
• Capture workflow
• Record protocol
• Security model
• Evidence and limitations
• Production contract
• Documentation index

Contributing

CONTRIBUTING.md covers the record protocol this repository

holds itself to, the release gate, and how to reproduce the evidence.

License

MIT — see LICENSE.