CommitLore

Give coding agents only the Git-owned decisions, constraints, and warnings that still apply.

Stars
★ 18
Last updated
4d ago
License
MIT
Primary language
TypeScript

At a glance

Works with
Universal · cross-platformCodex · Claude Code (Partial support)
You'll need
Node.js 22.23.2 or newerGitShell / CLINetwork accessLocal filesystemMCP Server
Typical use
A team maintaining a long-lived codebase can preserve why an architectural alternative was rejected because of a non-obvious constraint, preventing a later agent from proposing it again.
Main limitation
Capture is assisted rather than deterministic, and no supported host is certified to assess every eligible commit.
Source review
89/100 · Good

What does this agent do, and when should you use it?

CommitLore is a Git-native decision-memory system for coding agents, designed to retain constraints, rejected alternatives, and warnings that a code diff cannot explain. Its components include a CLI, commit hooks, plugins for Claude Code and Codex, and MCP-based delivery for other supported hosts. Accepted records live in Git trailers or `refs/notes/commitlore`; SQLite is only a rebuildable index, leaving the repository in control of the record. Before an edit, CommitLore selects records by repository path and lifecycle, returns only active guidance, and grades it as a directive, claim, or blocked content. It is a focused fit for teams trying to stop agents from reopening settled engineering debates, not a general conversation archive, user-memory service, or vector database.

The workflow has four stages: Capture, Verify, Preserve, and Deliver. commitlore capture drafts decision context that the diff cannot retain and checks candidates against the session transcript and staged diff; accepted records are stored in Git trailers or refs/notes/commitlore. commitlore stale distinguishes active, superseded, and expired decisions, while commitlore context selects the decisions that still apply to the path an agent is about to edit. A plugin hook or MCP route delivers the resulting context before editing; default or signed mode grades content as a directive, claim, or withheld material, but does not block the edit. commitlore doctor reports installation, old-hook, and squash-inheritance conditions, while commitlore coverage describes how much history a scan reached.

  1. A team maintaining a long-lived codebase can preserve why an architectural alternative was rejected because of a non-obvious constraint, preventing a later agent from proposing it again.
  2. A developer using Claude Code or Codex on a sensitive module can receive active decisions scoped to the target path before making an edit.
  3. An organization that does not want a hosted memory backend can keep engineering judgment in Git trailers or notes so it travels with repository workflows.
  4. A project whose decisions change over time can retire records as superseded or expired instead of presenting relevant but obsolete guidance as current authority.
  5. A team using GitHub's Squash and merge can deploy action/preserve so CommitLore records survive when branch commits are replaced by a squash commit.

How do you install or deploy this agent?

Node.js 22.23.2 or newer and Git are required. On macOS or Linux, run:

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

On Windows, run:

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

Connect Claude Code with:

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

Connect Codex with:

commitlore plugin install-codex

The plugin does not place commitlore on PATH, so the CLI installation is still required. Start a new agent session after installing or updating a plugin.

How do you use this agent?

Enter the target Git repository, initialize CommitLore, and make an initial context query:

cd your-repository
commitlore init
commitlore context .

Then work and commit normally. Supported skill integrations consider decision capture during ordinary commit requests, while most commits should carry no record. A repository that wants accepted records staged without a per-record prompt can explicitly enable the team-wide policy:

commitlore auto on

Repositories using GitHub's Squash and merge also need the documented action/preserve workflow. Local git merge --squash is handled by the prepare-commit-msg hook installed through commitlore init.

What are this agent's strengths and limitations?

Pros
  • Git trailers or notes remain the durable record, while the SQLite index can be deleted and rebuilt.
  • Path scoping is combined with active, superseded, and expired lifecycle states, reducing the risk that a reversed decision is delivered as current guidance.
  • Trust is explicit through directive, claim, and blocked grades, with an optional signed mode that uses Git verification and a repository-local signer allowlist.
  • The project supplies a CLI, commit hooks, Claude Code and Codex plugins, plus MCP paths for additional coding-agent hosts.
  • Published measurements state their boundaries and negative results; in the reported fixed two-record corpus test, path scoping retained both relevant records.
Limitations
  • Capture is assisted rather than deterministic, and no supported host is certified to assess every eligible commit.
  • Adoption requires Node.js 22.23.2 or newer and Git, and installing a plugin does not replace installing the CLI.
  • Git notes are not fetched by an ordinary clone, so commitlore init must configure the refs/notes/commitlore mirror.
  • GitHub Squash and merge requires an additional preservation Action with contents: write permission or branch records can be lost.
  • Pre-edit delivery also fires on reads and other matching tool calls; each call can spend up to the configured payload budget, which defaults to 800 tokens.
  • The reported behavioral and performance evidence is bounded to particular models, harnesses, corpora, or constructed tasks and does not prove universal agent compliance.

How does this agent compare with similar options?

General memory or RAG systems primarily ask which old text is semantically related. CommitLore instead asks which recorded decisions still apply to a particular repository path now. Git is the authority, records have active, superseded, or expired lifecycle states, and delivered material is graded as directive, claim, or blocked rather than treating every relevant passage as current guidance. That narrower design means it is not intended to replace conversation archives, general user memory, or vector databases.

Key facts side by side with the most closely related agents.

Agent Source review Stars Updated Language Full support on
CommitLore This agent 89 · Good ★ 18 4d ago TypeScript —
PowerContext 55 · Major gaps ★ 1.1k 4d ago Python Codex · Claude Code
Puppyone 39 · Major gaps ★ 1.3k 3mo ago TypeScript ChatGPT · Claude Code
Tura 65 · Some gaps ★ 641 11d ago Rust —

How does FollowAgents rate this agent?

FollowAgents source review · FARS-2.1
Good
89/ 100 5-point scale 4.5 / 5
Trust 25/29
Reliability 12/14
Adaptability 15/18
Convention 16/18
Effectiveness 13/13
Verifiability 8/8
Why each dimension lost points
Trust25 / 29 · 4.3/5

The evidence shows a repository-local design based on Git trailers, notes, and a rebuildable SQLite index, without a hosted memory service. Workflows declare narrow permissions and isolate jobs that execute contributor code from jobs holding publication credentials. The README and SECURITY.md explain how records enter Git, reach hosts, why default author matching is not authentication, how signed mode fails closed, and that CommitLore no longer controls data after a host receives it. Content is scanned for secrets before staging, injection-shaped records are withheld from model-readable routes, production dependencies face a zero-threshold audit, and most third-party Actions are commit-pinned. External writes, notes pushes, hook chaining, and PR comments are documented; uninstall restores prior hooks and the index is disposable. Deductions: repository-level auto mode can stage approved records without per-record confirmation, npm packages use version ranges while development audit findings are non-blocking, and source ownership and licensing are stated but publisher identity is not independently verified by the supplied evidence.

Reliability12 / 14 · 4.3/5

The README, SECURITY.md, package metadata, CI, and tests are internally consistent about storage, trust grades, installation, and GitHub Action behavior. CI checks the exact Node floor and current LTS, Git behavior across operating systems, full history and notes availability, clean-clone execution, packaged entry points, actual execution of every test file, and machine-derived documentation figures. Tests exercise shallow clones, missing refs, read-only tokens, remote rejection, and non-permission failures with specific diagnostics. The deduction is dependency availability: operation requires a recent Node 22.23.2+, Git, and access to a pinned GitHub source tag; there is no public npm fallback, and Git notes are absent from ordinary clones until configured.

Adaptability15 / 18 · 4.2/5

Documentation covers Claude Code, Codex, Hermes, MCP hosts, AGENTS.md-style hosts, macOS, Linux, Windows, squash merges, and alternative trust modes. It clearly excludes general user memory, conversation archives, and vector-database use. Boundaries are unusually explicit: capture is not deterministic, delivery does not block edits, coverage may be partial, notes require special fetching, guard quality is limited, and unsigned directives provide weak identity assurance. Trigger precision loses a point because no host is certified to evaluate every eligible commit and pre-edit delivery may run on several high-frequency tool calls. Environment fit loses a point because the supplied CI evidence primarily establishes Linux and macOS behavior; Windows has instructions but no equivalent test evidence, while the strict Node floor and notes setup add integration constraints.

Convention16 / 18 · 4.4/5

The README has a coherent quick start, capability matrix, mechanism overview, limitations, evidence section, and documentation index. Installation is pinned to v1.5.1 and covers script inspection, manual cloning, upgrades, uninstall behavior, session restarts, hook chaining, and squash-merge configuration. Protocol terms, commands, record fields, and package versions are stable and test-constrained; examples and operational edge cases are extensive. MIT metadata matches the full LICENSE. Deductions: the material identifies releases, the current version, a stable protocol, and a latest-release-only support policy, but supplies no complete changelog. It provides private vulnerability reporting, response expectations, and issue routes, but not an independently verifiable maintainer team, succession plan, or explicit division of maintenance responsibility.

Effectiveness13 / 13 · 5.0/5

Path-, lifecycle-, and trust-scoped output exposes constraints, rejected alternatives, warnings, record IDs, and commit identifiers in an immediately usable pre-edit format; partial and truncated results are labeled. Its Git ownership, lifecycle retirement, path scoping, and trust grading provide concrete marginal value over generic text retrieval. Cost and benefit are treated quantitatively but conservatively through re-proposal rates, retired-record leakage, 100k-commit lookup results, token exposure, per-hook payload limits, and zero cost for repositories without records. Full scores reflect the unusually concrete static evidence and disclosed limitations; they do not imply that this review executed or independently reproduced the measurements.

Verifiability8 / 8 · 5.0/5

Core claims trace to named commands, protocol fields, configuration keys, CI gates, test assertions, and benchmark-derived reporting. Security, installation, capability, and evidence claims in the README are corroborated by SECURITY.md, package metadata, both workflows, and Action tests. CI requires README figures to be regenerated, protocol examples to stay synchronized, and test files not to disappear silently. Fact/inference separation is explicit: the field report is labeled non-measurement, the agent study is not generalized, delivery is not equated with reading or compliance, an empty guard result is not called safe, and author matching is not called authentication. No material static-source deduction is identifiable for these three criteria, while confidence remains low because nothing was executed or independently reproduced.

Risks and how to mitigate them
  • This was a static review of the supplied files only; the installer, CLI, tests, benchmarks, and GitHub Actions were not executed.
  • Default author-string directive mode does not resist an attacker who can commit. High-trust repositories should require signatures and maintain a trustedSigner allowlist.
  • After repository-level auto mode is enabled, records may be staged without per-record confirmation; review team policy, hook changes, and the permanence of Git-history writes before adoption.
  • Ordinary clones do not fetch refs/notes/commitlore automatically, so missing initialization or mirror configuration can produce incomplete context.
  • The pull_request_target preservation example holds contents:write; its rule against checking out or executing fork-head content must remain intact.
  • Installation depends on pinned GitHub tags and a recent Node runtime with no npm-registry fallback; assess source availability, supply-chain pinning, and upgrade procedures.
Evidence confidence: Low Reviewed Sep 24, 2026 Reviewed revision 6dce0fa6d5f1
See the full review method →

FAQ

Does a repository with no records consume context on every tool call?
No. The documented behavior says a repository with no records spends nothing. After adoption, matching calls can consume up to the configured payload budget, which is 800 tokens by default.
Does a default-mode directive authenticate its author?
No. Default mode matches the commit author header and is policy metadata, not identity proof. Signed mode additionally requires Git verification and a match in commitlore.trustedSigner; a missing, empty, or unreadable allowlist authorizes nobody.
Will deleting the SQLite database erase decisions?
No. Git trailers and notes hold the record; SQLite is a rebuildable index.
Does a normal clone always contain every CommitLore record?
No. Trailers travel with commits, but Git does not fetch refs/notes/* by default. commitlore init configures the notes mirror, and commitlore coverage reports what a scan reached.
Can CommitLore enforce a decision and stop an edit?
No. Delivery provides graded context but does not block editing. The experimental guard is advisory, and an empty guard result is not a safety verdict.
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related agents