{
  "markdown": "<!-- README:BRAND -->\n<p align=\"center\">\n  <img src=\"./assets/readme/commitlore-logo.svg\" width=\"440\" alt=\"CommitLore\">\n</p>\n\n<h1 align=\"center\">CommitLore</h1>\n\n<h3 align=\"center\">Stop re-reviewing the same bad idea.</h3>\n\n<p align=\"center\">\n  <strong>Decision authority for coding agents, owned by Git.</strong><br>\n  Keep constraints, rejected alternatives, and warnings in Git — then deliver\n  only what is still in force, so an agent is not handed a decision the\n  repository already reversed.\n</p>\n\n<p align=\"center\">\n  <strong>No hosted memory. The repository owns the record.</strong>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/MongLong0214/commitlore/actions/workflows/ci.yml\">\n    <img alt=\"CI\" src=\"https://github.com/MongLong0214/commitlore/actions/workflows/ci.yml/badge.svg\">\n  </a>\n  <a href=\"https://github.com/MongLong0214/commitlore/releases\">\n    <img alt=\"Latest release\" src=\"https://img.shields.io/github/v/release/MongLong0214/commitlore?display_name=tag\">\n  </a>\n  <a href=\"spec/SPEC.md\">\n    <img alt=\"Protocol 2.0 Stable\" src=\"https://img.shields.io/badge/protocol-2.0%20stable-3FB950\">\n  </a>\n  <a href=\"package.json\">\n    <img alt=\"Node.js 22.23.2 or newer\" src=\"https://img.shields.io/badge/node-22.23.2%2B-3FB950\">\n  </a>\n  <a href=\"LICENSE\">\n    <img alt=\"MIT License\" src=\"https://img.shields.io/badge/license-MIT-3FB950\">\n  </a>\n</p>\n\n<p align=\"center\">\n  <strong>English</strong> ·\n  <a href=\"README.ko.md\">한국어</a> ·\n  <a href=\"README.ja.md\">日本語</a> ·\n  <a href=\"README.zh-CN.md\">简体中文</a>\n</p>\n\n<p align=\"center\">\n  <strong>Install once.</strong> Then initialise each repository where you want it to work.\n</p>\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/MongLong0214/commitlore/v1.2.0/install.sh | sh -s v1.2.0\n```\n\n<details>\n<summary>Prefer to read the installer first?</summary>\n\n```bash\ncurl -fsSLO https://raw.githubusercontent.com/MongLong0214/commitlore/v1.2.0/install.sh\nsh install.sh v1.2.0\n\n# Or skip the script: the checkout it makes is one you can make yourself.\ngit clone --depth 1 --branch v1.2.0 https://github.com/MongLong0214/commitlore\nnode commitlore/dist/commitlore.mjs --version\n```\n\nIt installs a pinned source checkout and a wrapper that runs\n`node <checkout>/dist/commitlore.mjs` — no compiled download, no build step.\n\n</details>\n\n<p align=\"center\">\n  <img\n    src=\"./assets/readme/demo.gif\"\n    width=\"900\"\n    alt=\"commitlore demo prints two recorded decisions for src/pricing.ts, delivers only the active one with its limit and the alternative it ruled out, and says the superseded decision remains in Git without being delivered as current guidance.\"\n  >\n</p>\n\n---\n\n> **The code survives. The judgment doesn't.**\n\nAn agent proposes an approach. Your team rejects it because of a non-obvious\nconstraint. The final code preserves the outcome, but usually not why the\nalternative was rejected. A later agent sees only the code and proposes the\nsame idea again.\n\nCommitLore keeps that judgment beside the code.\n\n## What CommitLore does\n\n| | Behavior | Product path |\n|---|---|---|\n| **Captures** | Preserves constraints, rejected alternatives, and warnings that a diff cannot show. Candidates are checked against the session transcript and the staged diff. | `commitlore capture` |\n| **Preserves** | Stores accepted records in Git trailers or notes instead of a hosted memory database. | commit hooks · `refs/notes/commitlore` |\n| **Tracks lifecycle** | Keeps active, superseded, and expired decisions distinct. | `commitlore stale` |\n| **Scopes** | Selects decisions for the path an agent is about to edit. | `commitlore context` |\n| **Grades trust** | Delivers records as directives, claims, or withheld content. | default / signed mode |\n| **Delivers** | Gives supported agents current context before an edit. | plugin hook · MCP |\n\nMost commits should carry no record. CommitLore is for judgment the code cannot\npreserve, not for narrating every change.\n\n<!-- README:QUICKSTART -->\n## 60 seconds to decision-aware agents\n\n### 1. Install the CLI\n\nmacOS and Linux:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/MongLong0214/commitlore/v1.2.0/install.sh | sh -s v1.2.0\n```\n\nWindows:\n\n```powershell\n& ([scriptblock]::Create((irm https://raw.githubusercontent.com/MongLong0214/commitlore/v1.2.0/install.ps1))) v1.2.0\n```\n\nRequires Node.js 22.23.2+ and Git. The script checks both before it writes anything.\n\n### 2. Connect your agent\n\nClaude Code:\n\n```text\n/plugin marketplace add MongLong0214/commitlore\n/plugin install commitlore@commitlore\n```\n\nCodex:\n\n```bash\ncommitlore plugin install-codex\n```\n\nThe plugin puts no `commitlore` on `PATH`, so the commands below need the CLI\ninstall as well. The installers also detect and wire supported MCP hosts where\nthey can do so safely; the exact matrix is below.\n\n### 3. Initialize a repository\n\n```bash\ncd your-repository\ncommitlore init\ncommitlore context .\n```\n\nStart a new agent session after installing or updating a plugin: a running\nsession keeps the runtime it loaded.\n\nThen work and commit normally. On supported skill integrations, CommitLore is\nconsidered during ordinary commit requests and stays silent when there is\nnothing worth preserving. You do not need to name CommitLore on every commit.\n\nWant accepted records to stage without a per-record prompt? The repository can\nopt in once with `commitlore auto on`. That policy is repository-owned and\napplies to the team, so it is not silently enabled by this page.\n\n<!-- README:PAYLOAD -->\n## What the agent receives\n\nBefore editing `src/pricing.ts`:\n\n```text\ncommitlore: active records for src/pricing.ts\n\nLimit\n  [claim] r-price01  calculatePrice owns final checkout pricing only\n\nRuled-out\n  [claim] r-price01  Reuse it for admin quotes |\n                     eligibility and rounding semantics differ\n```\n\n`[claim]` means \"weigh this as information.\" A repository can opt into the\nstronger signed-authority mode. Delivery gives the agent context; it does not\nblock the edit.\n\n[Security model →](SECURITY.md)\n\n## Why Git?\n\n**The repository should own the judgment behind its code.**\n\nCommitLore stores records in ordinary Git trailers and notes, so they branch,\nmerge, clone, review, and survive provider changes with the code they explain.\n\nSQLite is only a rebuildable index. Delete it and Git still holds the record.\n\n## Finding an old decision is not enough\n\nA general memory or retrieval system asks:\n\n> Which old text looks related?\n\nCommitLore asks:\n\n> Which recorded decisions still apply to this path now?\n\nA superseded decision can be highly relevant and still be wrong as current\nguidance. Relevance and authority are different questions.\n\n## How it works\n\n<p align=\"center\">\n  <img src=\"./assets/readme/hero.svg\" width=\"720\" alt=\"For src/pricing.ts, the active decision in Git history moves into the context delivered before the next edit, carrying its limit and the alternative it ruled out. An earlier decision that also covered admin quotes has been superseded and stays in history without moving forward as current guidance.\"\n  >\n</p>\n\n1. **Capture** — an agent drafts only decision context the diff cannot show.\n2. **Verify** — CommitLore checks the draft against the session and staged diff.\n3. **Preserve** — the accepted record lives in Git with identity and lifecycle.\n4. **Deliver** — before a later edit, only active records for that path are returned.\n\nMost commits carry no record. The commit hook validates a record when one is\npresent; it does not invent one.\n\nAn existing hook is not overwritten. `commitlore init` honours `core.hooksPath`,\nmoves any hook already installed to `<hook>.commitlore-chained`, and calls it\nfirst; `commitlore hooks uninstall` puts it back.\n\n<!-- README:CAPABILITY -->\n## What happens automatically\n\n| Host | Pre-edit delivery | Verified capture workflow | Deterministic every-commit capture |\n|---|---|---|---|\n| Claude Code | Automatic through the plugin | Available through the plugin skill | **Not certified** |\n| Codex | Automatic through the plugin | Available through the plugin skill | **Not certified** |\n| Hermes | Available after `commitlore hermes install` | Available after host install | **Not certified** |\n| Gemini CLI, Cursor, Windsurf, opencode | MCP delivery where the host uses the registration | Procedure exposed over MCP | No |\n| `AGENTS.md` hosts | Procedure only | Procedure only | No |\n\n\"Available\" means the prepare → verify → stage workflow exists. It does not mean\nevery eligible commit is assessed automatically.\n\nUsers on supported skill hosts do not need to say \"record this in CommitLore\" on\nevery commit. The remaining limitation is host initiation, not a required\nper-record user command.\n\n\n## A field report, not a measurement\n\nOne run, on an unrelated repository, by someone installing v1.2.0 for the first\ntime. Nothing here was measured and none of it is in the evidence logs. It is on\nthis page because the paragraph above asserts a loop that no table here covers.\n\nThey asked an agent to fix a rounding bug, mentioned in passing that a decimal\nlibrary had already been considered and dropped, and ended with \"commit it\".\nCommitLore was never named. Part of what the commit carried:\n\n```\nRuled-out: adopting a decimal library such as Decimal.js | the backend is a\n  number contract, so it is meaningless\nWarn: do not revert the test file to console.assert: it exits 0 even on\n  failure, so CI passes silently\nProvenance: drafted\n```\n\nThe `Warn` was not dictated to the agent. It hit the trap while working and left\nit for whoever came next. `Provenance: drafted` records that no human read the\nrecord, which grades it `claim` — delivered as a report to weigh, not an order.\n\nA later session with no shared history was asked to adopt the decimal library\nafter all. It did not, and named the record as its reason. It also read the\ngrade: a `claim` is not an instruction, so it checked the stated reason against\nthe code before agreeing with it.\n\n## Unlike memory storage\n\n| | General memory / RAG | **CommitLore** |\n|---|---|---|\n| Primary question | What old text is related? | Which decisions still apply here now? |\n| Authority | Memory store or provider | Git |\n| Scope | Semantic similarity | Repository paths |\n| Lifecycle | Often append-first | Active · superseded · expired |\n| Trust | Retrieved text | Directive · claim · blocked |\n| Capture | Transcript or note storage | Evidence-checked decision record |\n| Portability | Backend-dependent | Ordinary Git |\n\nCommitLore is intentionally narrower. It is not a general user-memory system,\nconversation archive, or vector database replacement.\n\n<!-- README:EVIDENCE -->\n## Evidence\n\n| Question | Measured result | Boundary |\n|---|---|---|\n| Did claim-grade context change re-proposal in the registered study? | **2.8%** (16/580) with CommitLore vs **18.8%** (109/579) without | one model, one harness, constructed tasks |\n| Did lifecycle filtering deliver retired records in the measured active projection? | **0 retired records** | superseded records were present; expiry was not |\n| Does indexed lookup scale? | **496 ms p50 at 100k commits** | the no-index fallback is much slower |\n\nIndex build time follows the number of *records*, not the number of commits: the\nexpensive pass runs once per record, so a long history that has recorded little\nbuilds faster than a short one dense with records.\n\nPath scope is what keeps a large history from reaching the model. On the #167\ncorpus, only 2 of 10,002 records did:\n\n| route | model-visible records | relevant records | model-visible tokens |\n|---|---:|---:|---:|\n| inject everything | 10,002 | 2/2 | 1,004,554 |\n| top-k lexical | 2 | 1/2 | 190 |\n| CommitLore path scope | 2 | 2/2 | 335 |\n\nThat measures exposure and recall at a fixed two-record budget — not token cost,\nbilled cost, accuracy, or agent behaviour. One corpus, one query, one pinned\nembedding model.\n\nThe agent study does not establish a universal model effect. Delivery is not\nproof that a model read or followed a record.\n\n[Methods, full tables, exclusions, and negative results →](docs/evidence.md)\n\n<!-- README:LIMITS -->\n## Limits, trust and privacy\n\n- **Capture is assisted, not deterministic.** Supported skills consider ordinary\n  commit requests, but no host is certified to assess every eligible commit.\n- **Default directive mode is not authentication.** It matches the commit\n  author header, and anyone who can write a commit can set that header — so a\n  `[directive]` in default mode is policy metadata, not proof of identity.\n  Signature mode additionally requires Git's own verified status and a match in\n  the repository-local `commitlore.trustedSigner` allowlist; an absent, empty, or unreadable signer allowlist authorizes nobody, so the mode fails closed.\n- **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.\n- **Delivery spends tokens on every matching tool call.** The pre-edit hook\n  fires on `Read` as well as `Edit`, `Write`, `MultiEdit` and `NotebookEdit`, so\n  it runs far more often than an editing agent commits. Each fire spends up to\n  the payload budget — 800 tokens by default, changed with `--budget`. A\n  repository with no records spends nothing, which means this is a cost that\n  arrives with adoption rather than with installation.\n- **An answer may be partial.** Coverage is disclosed; absence from a partial\n  result is not proof that no record exists. Repository-wide coverage, symbol anchors,\n  and an interactive record builder remain open:\n  [#32](https://github.com/MongLong0214/commitlore/issues/32),\n  [#33](https://github.com/MongLong0214/commitlore/issues/33).\n- **Commit trailers travel with a clone; notes do not.** Git does not fetch\n  `refs/notes/*` by default, so a record in `refs/notes/commitlore` is absent\n  from an ordinary clone until `commitlore init` configures that mirror.\n- **There is no hosted backend.** But once the server or hook returns context,\n  the host handles that context under its own policy; CommitLore does not\n  control that data flow.\n\n[Security](SECURITY.md) ·\n[Compatibility](docs/COMPATIBILITY.md) ·\n[Evidence](docs/evidence.md)\n\n<details>\n<summary><strong>Security and trust model</strong></summary>\n\nRecords are untrusted until graded. Default author matching is policy metadata,\nnot authentication. Signed directive mode requires Git verification and a\nrepository-local signer allowlist; an absent or unreadable allowlist authorizes\nnobody. Injection-shaped payload is withheld from model-readable routes.\n\n[Full security model →](SECURITY.md)\n\n</details>\n\n<details>\n<summary><strong>Installation, upgrades, and old hook generations</strong></summary>\n\nThe CLI installer cannot rewrite hooks inside repositories it does not know\nabout, and running host sessions retain the runtime they loaded. `commitlore\ndoctor` names both states and their repair, and `commitlore upgrade` reports\nwhether a newer release exists.\n\n[Installation and upgrades →](docs/install.md)\n\n</details>\n\n<details>\n<summary><strong>Protocol and Git storage</strong></summary>\n\nRecords are ordinary Git trailers or notes. Protocol 2.0 defines lifecycle,\ntrust grades, validation, and compatibility.\n\n[Human guide →](docs/protocol.md) ·\n[Normative specification →](spec/SPEC.md)\n\n</details>\n\n<details>\n<summary><strong>Evidence and negative results</strong></summary>\n\nThe repository publishes the methods, exclusions, unsuccessful measurements,\nand the cases where the original benchmark or diagnosis was wrong.\n\n[Evidence →](docs/evidence.md) ·\n[Self-audit →](docs/SELF-AUDIT.md)\n\n</details>\n\n<hr>\n\n<p align=\"center\">\n  <strong>Try it on a repository with history.</strong><br>\n  <sub>Tell us where path scope, lifecycle, capture, or installation breaks.</sub>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/MongLong0214/commitlore/issues/new\">Report a failure case</a>\n  ·\n  <a href=\"docs/SELF-AUDIT.md\">Read the self-audit</a>\n</p>\n\n<hr>\n\n<!-- README:DOCS -->\n## Documentation\n\n- [Install, upgrade, and uninstall](docs/install.md)\n- [CLI reference](docs/cli.md)\n- [Capture workflow](docs/capture.md)\n- [Record protocol](docs/protocol.md)\n- [Security model](SECURITY.md)\n- [Evidence and limitations](docs/evidence.md)\n- [Production contract](docs/PRODUCTION-READINESS-SSOT.md)\n- [Documentation index](docs/README.md)\n\n## Contributing\n\n[CONTRIBUTING.md](CONTRIBUTING.md) covers the record protocol this repository\nholds itself to, the release gate, and how to reproduce the evidence.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 16597,
  "sha": "75f67df8dac3d30db870cc68655b22b99bdbcfc6fc37a191642e5bf1305faeab",
  "repo_slug": "monglong0214/commitlore",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_monglong0214_commitlore_fe538900/readme"
}