CommitLore
Give coding agents only the Git-owned decisions, constraints, and warnings that still apply.
- Source repo
- MongLong0214/commitlore
- Stars
- ★ 19
- Last updated
- 21d ago
- License
- MIT
- Primary language
- TypeScript
- FA score
- 78/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code (Partial support)
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- 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.
- Not a fit if
- Teams wanting hosted memory or cloud sync; records live only in Git
- Users seeking a general conversation archive or vector database replacement
- Teams needing deterministic capture of every eligible commit
- Source review
- 78/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.
- 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.
- A developer using Claude Code or Codex on a sensitive module can receive active decisions scoped to the target path before making an edit.
- 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.
- A project whose decisions change over time can retire records as superseded or expired instead of presenting relevant but obsolete guidance as current authority.
- A team using GitHub's Squash and merge can deploy
action/preserveso 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.1On Windows, run:
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/MongLong0214/commitlore/v1.5.1/install.ps1))) v1.5.1Connect Claude Code with:
/plugin marketplace add MongLong0214/commitlore
/plugin install commitlore@commitloreConnect Codex with:
commitlore plugin install-codexThe 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 onRepositories 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?
- 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.
- 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 initmust configure therefs/notes/commitloremirror. - GitHub Squash and merge requires an additional preservation Action with
contents: writepermission 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 | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| CommitLore This agent | 78 · Good | CLIFree | ★ 19 | 21d ago | TypeScript | — |
| PowerContext | 82 · Good | CLIFree | ★ 1.5k | today | Python | Codex · Claude Code |
| Agent Systems Handbook | 62 · Some gaps | Web appFree | ★ 313 | 23d ago | MDX | — |
| Puppyone | 47 · Major gaps | Self-hosted serviceFreemium | ★ 1.3k | 4mo ago | TypeScript | ChatGPT · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
The MCP source says queries use local Git and the local index with no network client, and model-facing routes withhold blocked payloads. SECURITY distinguishes default author-string matching from signed verification plus a signer allowlist. Install prerequisites, opt-in automatic staging, uninstall behavior, and hook restoration are described, supporting solid privilege and rollback scores. Secret scanning is asserted, but its coverage and false-positive boundaries are not shown; dependency security has no lockfile or audit evidence in the packet, so both are deducted. Author and repository metadata are present, but publisher identity remains unknown and earns no brand credit.
The protocol, CLI, MCP, and CI materials describe a largely consistent record lifecycle, while the README discloses nondeterministic capture and the extra squash-inheritance setup. Some tension remains: AGENTS.md tells agents to follow directive records, while SECURITY explains that default author matching is not authentication, so self-consistency is not full. Node/Git prerequisites, exit behavior, and diagnostic examples are documented, but not every dependency failure and recovery path is covered.
The packet names Claude Code, Codex, Hermes, MCP, and AGENTS.md-reading hosts, and separates automatic delivery, assisted capture, and uncertified deterministic capture. Query, capture, setup, diagnostics, signature trust, and installation paths have clear boundaries. Ordinary-commit capture depends on host skill selection, and token use can occur on matching tool calls; cross-host environment compatibility is described rather than independently exercised in this static review.
Documentation is organized around installation, CLI, capture, protocol, security, and evidence, with concrete examples, uninstall steps, and limitations. The MIT license text is complete. Version 1.7.5 and protocol 2.0 stable are stated, with ADRs and CI evidence, but the packet lacks a centralized release changelog and a clear maintenance responsibility mechanism. Publisher provenance is unverified, so versioning and responsibility receive partial credit.
Path scoping, lifecycle filtering, trust grades, and structured query output provide usable decision context, with examples and bounded benchmark claims. The materials do not establish universal improvement in agent behavior and explicitly disclose nondeterministic capture, limited guard recall, and token cost per matching call. Value is supported, but the benefit-cost case is not fully established.
README measurements point to methodology, ADRs distinguish positioning from outcome claims, and CI definitions show machine-checkable protocol, build, and benchmark checks. This supports claim traceability and separation of facts from inference. Cross-source corroboration is limited to the supplied file sample, and none of the checks was executed during this review, so full marks are not justified.
- Default directive trust relies on a spoofable commit author string; use signature verification and a repository-local signer allowlist when committers are not trusted.
- Capture depends on the host selecting the skill and does not evaluate every eligible commit; squash merges can lose records unless inheritance is configured.
- Delivery consumes tokens, and records are context rather than enforcement; an empty guard result is not a safety guarantee and does not show that an agent followed a record.
Maintain this project? Add the FARS badge to your README
[](https://followagents.com/en/agents/commitlore)<a href="https://followagents.com/en/agents/commitlore"><img src="https://followagents.com/badge/commitlore.svg" alt="FARS review"></a>Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
init can leave the working tree exactly as it found it If a script runs commitlore init as part of checking that a checkout is clean, this is the release you want. init writes one file inside the working tree: the PreToolUse injection hook at .claude/settings.json. It is untracked, so after init the tree is no longer clean — and a caller whose whole job is to verify a clean checkout then sees its own observation as a change: ```sh git status --porcelain --untracked-files=all # empty commitlore init --mcp-scope none --no-unattended </dev/null …View on GitHub ↗ -
Release notes excerpt
Two production advisories, and the three capture faults a 118.7 MB transcript uncovered Take this one. It patches a high and a critical advisory in dependencies that ship with the CLI. | package | severity | advisory | |---|---|---| | @modelcontextprotocol/sdk → 1.32.1 | high | OAuth client could send credentials to an authorization server the MCP server chose ([GHSA-6qxp-vccf-f47h](https://github.com/advisories/GHSA-6qxp-vccf-f47h)) | …View on GitHub ↗ -
Release notes excerpt
A paragraph that holds no record was being inherited as one If you squash-merge with squash-preserve, take this one. A squash merge in another repository was refused by commitlore validate and could not land: ``` shape failed · 169: unknown-key Claude-Session — got "Claude-Session", want "a key from SPEC §3, or X-Claude-Session if this is your own metadata" ``` The range held an ordinary merge commit with no record at all. Its last paragraph was a single line: ``` Claude-Session: https://claude.ai/code/session_… ``` …View on GitHub ↗
FAQ
Does a repository with no records consume context on every tool call?
Does a default-mode directive authenticate its author?
commitlore.trustedSigner; a missing, empty, or unreadable allowlist authorizes nobody.Will deleting the SQLite database erase decisions?
Does a normal clone always contain every CommitLore record?
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?
Thanks — we use this to improve the page.