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.7.5/install.sh | sh -s v1.7.5

Prefer to read the installer first?

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

sh install.sh v1.7.5

Or skip the script: the checkout it makes is one you can make yourself.

git clone --depth 1 --branch v1.7.5 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.7.5/install.sh | sh -s v1.7.5

Windows:

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

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 a1b2c3d4 calculatePrice owns final checkout pricing only

Ruled-out [claim] r-price01 a1b2c3d4 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.

Squash-merge repositories

A squash merge replaces a branch's commits with one new commit, and that commit does not carry the branch's trailers. If your repository merges with the squash button, a record made on a branch is dropped by the merge unless something carries it onto the commit that squashed it.

Two paths cover that, and one of them needs a one-time setup:

GitHub performs that merge on its own servers, where no local git hook runs at all, so the local hook cannot see it. The Action is the only place that has what it needs at that moment: the pull request, its commits, and the commit they were squashed into.

Add .github/workflows/commitlore-preserve.yml:

name: CommitLore squash inheritance

pull_request_target, not pull_request: a pull request from a fork gets a

read-only token on pull_request, so the job would build the record and then

fail to publish it.

on: pull_request_target: types: [closed]

permissions: contents: write # the one push to refs/notes/commitlore

concurrency: group: commitlore-notes cancel-in-progress: false

jobs: preserve: if: github.event.pull_request.merged == true runs-on: ubuntu-latest steps:

• uses: actions/checkout@v4 with:

the merge commit is on the base branch, and a closed pull request

has no merge ref left to check out

ref: ${{ github.event.pull_request.base.ref }} fetch-depth: 0

the mirror this action writes; publishing from a checkout that never

read it would fork the notes history

• run: git fetch --no-tags origin '+refs/notes/commitlore:refs/notes/commitlore'

a squash merge usually deletes the branch, and then the pull request's

own ref is the only one still reaching the commits that carry records

• run: git fetch --no-tags --force origin '+refs/pull/${{ github.event.pull_request.number }}/head:refs/commitlore/pr-head'

The action runs CommitLore from a checkout of this repository: the

package is private, so there is no published npm name to fall back to.

dist/ is committed (ADR-0011), so nothing needs building.

• uses: actions/checkout@v4 with: repository: MongLong0214/commitlore ref: v1.7.5 path: .commitlore-cli persist-credentials: false

• uses: MongLong0214/commitlore/action/preserve@v1.7.5 with: cli-path: .commitlore-cli/dist/cli.js

Two rules for whoever edits this next, because pull_request_target runs with a writable token: never check out the pull request's head here, and never execute anything reachable from refs/commitlore/pr-head. The fork's commits arrive as data to read trailers from, not as code to run.

commitlore doctor reports whether this is switched on, under squash inheritance. It says so before a record is lost; squash conservation is the row that reports records already gone.

If you merge with