What can you do with this server?

CommitLore MCP server exposes read-only lookup and experimental guard tools plus a three-step assisted capture workflow for Git-backed decision records. * Report the exact CommitLore runtime identity (entrypoint, package root, version, index schema). * Query active records by kind (context, limits, ruled-out, warnings) and optional repository-relative path. * List stale records: superseded, past a date-form Expires:, or flagged by a condition-form expiry. * Guard a proposal against ruled-out alternatives for a path; experimental advisory, not a safety net. * Get combined context and optional guard before editing a path: active decisions, verification gaps, possible revival matches, guard confidence, cache key. * Prepare a capture transaction from a transcript and optional repository assertion; binds HEAD, staged diff, tree, policy hash, returns nonce. * Verify a capture draft against the prepared transcript and diff; evidence citations are checked verbatim, fabricated quotes discarded. * Stage a verified capture transaction with the nonce and optional receipt, making it eligible for the prepare-commit-msg hook.

Which integrations are available for this server?

Uses Git as the storage backend, preserving decision records in trailers and notes so they branch, merge, clone, and survive provider changes with the code. Uses SQLite only as a rebuildable index for the decision records; Git remains the source of truth.

de en ja ko ru zh

CommitLore

by MongLong0214

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

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

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

# Or skip the script: the checkout it makes is one you can make yourself.
git clone --depth 1 --branch v1.7.2 https://github.com/MongLong0214/commitlore
node commitlore/dist/commitlore.mjs --version

It installs a pinned source checkout and a wrapper that runs node <checkout>/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

	Behavior	Product path
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`
Preserves	Stores accepted records in Git trailers or notes instead of a hosted memory database.	commit hooks · `refs/notes/commitlore`
Tracks lifecycle	Keeps active, superseded, and expired decisions distinct.	`commitlore stale`
Scopes	Selects decisions for the path an agent is about to edit.	`commitlore context`
Grades trust	Delivers records as directives, claims, or withheld content.	default / signed mode
Delivers	Gives supported agents current context before an edit.	plugin hook · MCP

Most commits should carry no record. CommitLore is for judgment the code cannot preserve, not for narrating every change.

Related MCP server: memini

60 seconds to decision-aware agents

1. Install the CLI

macOS and Linux:

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

Windows:

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

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

Capture — an agent drafts only decision context the diff cannot show.
Verify — CommitLore checks the draft against the session and staged diff.
Preserve — the accepted record lives in Git with identity and lifecycle.
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 <hook>.commitlore-chained, and calls it first; commitlore hooks uninstall puts it back.

What happens automatically

Host	Pre-edit delivery	Verified capture workflow	Deterministic every-commit capture
Claude Code	Automatic through the plugin	Available through the plugin skill	Not certified
Codex	Automatic through the plugin	Available through the plugin skill	Not certified
Hermes	Available after `commitlore hermes install`	Available after host install	Not certified
Gemini CLI, Cursor, Windsurf, opencode	MCP delivery where the host uses the registration	Procedure exposed over MCP	No
`AGENTS.md` hosts	Procedure only	Procedure only	No

"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:

How the squash happens	What carries the record	Setup
`git merge --squash` locally	The installed `prepare-commit-msg` hook, from `SQUASH_MSG`	None — `commitlore init` already did it
GitHub's Squash and merge button	The `action/preserve` GitHub Action	The workflow below

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.2
          path: .commitlore-cli
          persist-credentials: false

      - uses: MongLong0214/commitlore/action/preserve@v1.7.2
        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 merge commits or rebase, records survive on their own and this setup is unnecessary.

A field report, not a measurement

One run, on an unrelated repository, by someone installing v1.2.1 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

	General memory / RAG	CommitLore
Primary question	What old text is related?	Which decisions still apply here now?
Authority	Memory store or provider	Git
Scope	Semantic similarity	Repository paths
Lifecycle	Often append-first	Active · superseded · expired
Trust	Retrieved text	Directive · claim · blocked
Capture	Transcript or note storage	Evidence-checked decision record
Portability	Backend-dependent	Ordinary Git

CommitLore is intentionally narrower. It is not a general user-memory system, conversation archive, or vector database replacement.

Evidence

Question	Measured result	Boundary
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
Did lifecycle filtering deliver retired records in the measured active projection?	0 retired records	superseded records were present; expiry was not
Does indexed lookup scale?	496 ms p50 at 100k commits	the no-index fallback is much slower

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:

route	model-visible records	relevant records	model-visible tokens
inject everything	10,002	2/2	1,004,554
top-k lexical	2	1/2	190
CommitLore path scope	2	2/2	335

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. commitlore coverage reports what a scan reached.
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

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 →

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 →

Records are ordinary Git trailers or notes. Protocol 2.0 defines lifecycle, trust grades, validation, and compatibility.

Human guide → · Normative specification →

The repository publishes the methods, exclusions, unsuccessful measurements, and the cases where the original benchmark or diagnosis was wrong.

Evidence → · Self-audit →

Documentation

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.

Available Tools

8 tools

commitlore_before_changeA

Read-only

Everything recorded about a path, before editing it: the active decisions, the gaps in what could be verified, and any ruled-out alternative a proposal would revive. Returns active_decisions, verification_gaps, possible_revival_matches, guard_confidence and cache_key. Pass path alone for context. Pass proposal as well to also run the guard against that path's Ruled-out records; without it guard_confidence is "not-run" and possible_revival_matches is empty because nothing was checked, not because nothing matched. The guard is an experimental advisory: precision 44.8%, recall 22.0% on the 417-decision corpus. An empty possible_revival_matches does not guarantee the proposal avoids every ruled-out alternative.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	repository-relative path whose Ruled-out records to check against
`proposal`	No	the proposed approach, in the words it would be carried out in; omit for context only (no guard run)

TDQS

A4.2/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the read-only annotations, it discloses that the guard is experimental, gives precision/recall numbers, explains that an empty match list means nothing checked rather than no match, and warns that empty results do not guarantee safety. This is significant extra behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense and front-loaded with the core purpose, then return keys, then usage modes, then the guard caveat. It is longer than average but every clause carries necessary information, so it earns its length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

It names all returned keys and explains the guard-related result semantics, which is important because there is no output schema. It does not detail the internal structure of `active_decisions` or `verification_gaps`, but the names and context make them understandable enough for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description adds behavioral meaning to `proposal` by explaining how its presence changes the guard run and the returned fields. It also clarifies that `path` is repository-relative, reinforcing the schema without repeating it verbatim.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns recorded context for a path before editing, including active decisions, verification gaps, and ruled-out alternatives. It distinguishes its scope ('before editing') and guard behavior from the sibling set, though it does not explicitly name an alternative tool to contrast with.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit mode guidance: pass `path` alone for context, and pass `proposal` to also run the guard. It explains the consequences of omitting `proposal` (guard_confidence 'not-run', possible_revival_matches empty). It does not explicitly say when to prefer this over sibling tools like commitlore_guard, but the context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

commitlore_guardA

Read-only

Check a proposal against the Ruled-out records for a path before acting on it. Returns every record whose alternative matches, with the reason it was rejected. Experimental advisory: precision 44.8%, recall 22.0% on the 417-decision corpus. An empty matched array does not guarantee the proposal avoids every ruled-out alternative.

ParametersJSON Schema

Name	Required	Description	Default
`path`	No	repository-relative path whose Ruled-out records to check against
`proposal`	Yes	the proposed approach, in the words it would be carried out in

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already indicate read-only and non-destructive behavior, and the description adds transparency about the output ('Returns every record whose alternative matches') and the important caveat that an empty result does not guarantee safety. It does not describe error behavior, but the main behavioral characteristics are disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, each conveying essential information: the action, the return behavior, and the experimental limitations. No filler or redundant phrasing is present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains what the tool returns and includes a critical limitation about false negatives. There is no output schema, but the return shape is described well enough for basic use; error cases and exact record structure are not specified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description does not add significant semantic detail beyond the schema. 'Path' and 'proposal' are both described in the schema, so the description mostly repeats rather than enriches parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Check a proposal'), a specific resource ('Ruled-out records for a path'), and a clear purpose ('before acting on it'). It clearly distinguishes this tool's role from generic query or mutation tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear timing guidance ('before acting on it') and warns that the tool is experimental and advisory, with precision/recall metrics. It does not explicitly name alternative sibling tools, but the usage context and limitations are sufficiently clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

commitlore_prepare_captureA

Prepare a capture transaction: computes binding conditions (HEAD, staged diff, tree, policy hash), generates the prompt contract for the agent to use, and persists a phase:"prepared" pending transaction. Returns the nonce needed for verify and stage. The prompt carries the end of the transcript rather than all of it; transcript_window says which lines, numbered as the whole transcript numbers them. Verification still reads the whole transcript, so quote only what the prompt shows you. The transaction binds to THIS server's checkout, returned as repository; if your working directory is a linked worktree or another clone, pass repository to assert it and this refuses rather than binding to the wrong HEAD.

ParametersJSON Schema

Name	Required	Description
`repository`	No	your own working directory, asserted. This server is registered against one checkout and binds every transaction to it; if you are in a linked worktree or another clone, pass this and the call refuses instead of binding to a tree you never touched. It cannot change the binding, only assert it. Omit to accept this server's repository, which is returned as `repository`
`transcript`	Yes	the session transcript to compute source hashes from
`unattended`	No	declare this capture unattended: nobody was asked before staging. Refused unless the repository opted in (.commitlore-policy.json: "unattended": true, mode "auto")

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, the description reveals substantial behavior: it persists a phase:'prepared' pending transaction, computes binding conditions, returns only the end of the transcript in the prompt, notes that verification still reads the whole transcript, and refuses to bind when the repository assertion fails. None of this contradicts the annotations, and the readOnlyHint=false is consistent with the described persistence.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence earns its place: purpose and output are front-loaded, followed by critical quoting guidance and binding behavior. There is no filler or repetition of schema details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with no output schema, the description covers the essential return values (`nonce`, `repository`, `transcript_window`), the persistence side effect, the transcript quoting rule, and the refusal behavior. It does not enumerate the complete shape of the returned prompt contract or all possible error cases, but it provides enough context to call the tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the schema already explains each parameter meaningfully, especially `repository` and `unattended`. The description adds workflow context around the transcript and repository assertion, but it does not add substantial parameter-level semantics beyond the schema, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource: 'Prepare a capture transaction' and details the concrete outputs (binding conditions, prompt contract, pending transaction, nonce). It also distinguishes this step from the sibling tools by explicitly relating the nonce to 'verify and stage', so an agent can tell it apart from commitlore_stage_capture and commitlore_verify_capture.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear workflow context: this prepares the transaction and returns the nonce needed for later verify and stage steps. It also includes a conditional usage rule for passing `repository` when working from a linked worktree or another clone. It does not explicitly enumerate when not to use the tool versus each sibling, but the phase workflow is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

commitlore_queryA

Read-only

Active CommitLore records for a path: the constraints, ruled-out alternatives and warnings recorded in git history. Same answer as commitlore <kind> --json.

ParametersJSON Schema

Name	Required	Description	Default
`kind`	Yes	context = every kind at once; limits = Limit:; ruled-out = Ruled-out:; warnings = Warn:
`path`	No	repository-relative path to scope the answer to (renames are followed); omit for the whole repository

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds that records are 'active' and that it returns the same answer as a CLI command, implying a JSON response. This adds meaningful context beyond the annotations without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with zero waste. The core purpose is front-loaded, and the second sentence clarifies the CLI equivalence. No redundant phrasing or unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 2-parameter read-only query tool with no output schema, the description explains the content returned (active records of kinds), the scope via path, and the JSON format via CLI reference. It is sufficiently complete for an agent to invoke it correctly, though it does not detail the exact response structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both parameters (kind and path) already fully described in the schema. The description does not add parameter-specific details beyond the schema, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States it retrieves active CommitLore records (constraints, ruled-out alternatives, warnings) for a path, and mentions it is equivalent to `commitlore <kind> --json`. This clearly distinguishes it from sibling tools that handle guard, capture, identity, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context (querying records for a path) but does not explicitly compare to alternative commitlore tools or state when not to use it. It lacks explicit exclusions or alternative selection guidance, relying on the purpose to convey when it should be invoked.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

commitlore_runtime_identityA

Read-only

Report the exact CommitLore entrypoint, package root, version and index schema this MCP server executes.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already indicate readOnlyHint: true and destructiveHint: false, and the description's 'Report' action aligns perfectly with these. It further discloses the exact content of the report, leaving no ambiguity about the tool's behavior or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that lists all reported items without unnecessary words. It is highly concise and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that there are no parameters and no output schema, the description is complete. It fully informs the agent of what the tool reports, with no missing context needed to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and the description does not need to explain any. Since there are no params to clarify, the baseline score of 4 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with the specific verb 'Report' and lists the exact items reported (entrypoint, package root, version, index schema). It is distinct from the sibling tools, which focus on query, capture, and guard operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or conditions. It is a self-explanatory reporting tool, but the absence of any usage context leaves the agent without direction on when to invoke it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

commitlore_stage_captureA

Stage a verified capture transaction: advances the pending record from verified to staged, stamps expires_at (staged_at + 5 minutes), and makes it eligible for the prepare-commit-msg hook. All bindings are server-owned and computed from stored state; the only inputs are the nonce and, optionally, the receipt your verification was issued.

ParametersJSON Schema

Name	Required	Description	Default
`nonce`	Yes	the 32-character lowercase hex nonce returned by prepare_capture
`receipt`	No	the receipt verify_capture returned to you. Required whenever the transaction was bound by a verification that issued one, which is every transaction this build binds; a receipt that was not issued by that verification is refused. Omit it only for a transaction prepared by a build older than receipts. Always send the one you were given.

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses key behaviors beyond the annotations: it advances the record from verified to staged, sets expires_at to staged_at + 5 minutes, and makes it eligible for the prepare-commit-msg hook. It also explains that bindings are server-owned and computed from stored state, and that receipt verification is enforced. This is rich context that annotations (only readOnlyHint, openWorldHint, destructiveHint as false) do not provide, so it earns a high score.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise—two sentences—but packs critical information: the action, the state transition, the timing, the eligibility, and the parameter guidance. Every sentence adds value, and it is front-loaded with the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity, the description covers all essential aspects: the state transition, the time constraint, the eligibility for the hook, and the parameter handling. There is no output schema, so the description doesn't need to explain return values, and the parameter semantics are already covered in the schema. The only minor gap is not explicitly stating what the response or result looks like, but that is not critical for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the description adds minimal extra meaning beyond what the schema already explains. The description reinforces the receipt's requirement and its origin, but since the schema already provides detailed descriptions, the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to stage a verified capture transaction by advancing a pending record from verified to staged, and it explicitly mentions the stamping of expires_at. It distinguishes itself from sibling tools like verify_capture and prepare_capture by describing the specific state transition.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly indicates when to use the tool ('after a verification has been issued') and explains when to omit the receipt (for older builds). However, it does not explicitly state when NOT to use this tool or mention alternative tools by name, so it's not a perfect 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

commitlore_staleA

Read-only

Records that are no longer carrying their weight: superseded, past a date-form Expires:, or flagged for review by a condition-form one. Same answer as commitlore stale --json.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by defining what 'stale' means (superseded, past Expires:, flagged for review), which goes beyond the annotation. No contradiction; it reinforces the read-only nature by focusing on listing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no filler. The core purpose and criteria are front-loaded, and the command equivalence is a concise note. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter listing tool with read-only annotations, the description is sufficiently complete. It explains what is returned (stale records) and the criteria. No output schema exists, but the tool's purpose is simple enough that return format is implied.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so schema coverage is trivially 100%. The baseline for 0 params is 4, and the description does not need to explain parameters. It appropriately omits parameter details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists stale CommitLore records, with specific criteria (superseded, past Expires:, flagged for review). The verb 'list' and resource 'stale records' are clear. It doesn't explicitly differentiate from siblings like commitlore_query, but the specific criteria make it distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for viewing stale records but provides no guidance on when to use it versus other tools or when not to use it. The mention of 'Same answer as commitlore stale --json' is a command equivalence, not an alternative selection. No exclusions or context are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

commitlore_verify_captureA

Verify a capture draft against the transcript and diff that were hashed at prepare time. Evidence citations are checked mechanically (verbatim match); fabricated quotes are discarded. Stores the verified result in the pending transaction for stage to consume.

ParametersJSON Schema

Name	Required	Description
`diff`	No	optional: the staged diff, if you have it. Omit it and the server reads the staged diff itself and checks it against the hash prepare stored — the same guarantee, without asking you to reproduce content the server produced.
`draft`	Yes	The agent's draft, as the harvest contract specifies it: a JSON object with a "records" array. A bare JSON array of records is also accepted.
`nonce`	Yes	the 32-character lowercase hex nonce returned by prepare_capture
`transcript`	Yes	the session transcript (same content hashed at prepare time)

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing that it stores the verified result in a pending transaction and that evidence citations are mechanically checked, with fabricated quotes discarded. This adds meaningful behavioral context about the mutation and verification logic.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no redundancy. The purpose is front-loaded, and each sentence delivers distinct information: the core verification action, the citation-checking behavior, and the storage outcome.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description does not specify the return value or what happens if verification fails, which is important given there is no output schema. It mentions the workflow (prepare, stage) but leaves response format and error handling unspecified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

While the schema already covers 100% of parameters, the description adds extra nuance: it explains the diff parameter can be omitted for the server to read the staged diff itself, and it clarifies the draft format (JSON object with a 'records' array, bare array accepted). This supplements the schema descriptions meaningfully.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('verify') and resource ('capture draft'), and clarifies the context by referencing 'hashed at prepare time' and 'for stage to consume'. This makes the tool's role in the workflow unambiguous and distinguishes it from the sibling prepare and stage tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage in the prepare→verify→stage workflow but does not explicitly state when to use this tool over alternatives or when not to use it. There is no exclusions or alternative routing, so the guidance is only implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

1 tool updatev1.5.0Sep 19, 2026

Changedcommitlore_prepare_capture1 field changed

addedInput schema / properties / repository

Added value: +{
+  "description": "your own working directory, asserted. This server is registered against one checkout and binds every transaction to it; if you are in a linked worktree or another clone, pass this and the call refuses instead of binding to a tree you never touched. It cannot change the binding, only assert it. Omit to accept this server's repository, which is returned as `repository`",
+  "type": "string"
+}

2 tool updatesv1.4.0Sep 15, 2026

Changedcommitlore_stage_capture1 field changed

addedInput schema / properties / receipt

Added value: +{
+  "description": "the receipt verify_capture returned to you. Required whenever the transaction was bound by a verification that issued one, which is every transaction this build binds; a receipt that was not issued by that verification is refused. Omit it only for a transaction prepared by a build older than receipts. Always send the one you were given.",
+  "type": "string"
+}

Changedcommitlore_verify_capture2 fields changed

changedInput schema / properties / diff / description

Previous value: -"the staged diff (same content hashed at prepare time)"New value: +"optional: the staged diff, if you have it. Omit it and the server reads the staged diff itself and checks it against the hash prepare stored — the same guarantee, without asking you to reproduce content the server produced."

changedInput schema / required

Previous value: -[
-  "nonce",
-  "draft",
-  "transcript",
-  "diff"
-]New value: +[
+  "nonce",
+  "draft",
+  "transcript"
+]

8 tool updatesv0.1.0Sep 8, 2026
- First observedcommitlore_before_change
- First observedcommitlore_guard
- First observedcommitlore_prepare_capture
- First observedcommitlore_query
- First observedcommitlore_runtime_identity
- First observedcommitlore_stage_capture
- First observedcommitlore_stale
- First observedcommitlore_verify_capture

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored 2026-09-19 08:00 across 8 tools

Disambiguation3/5

The capture lifecycle tools (prepare/verify/stage) are clearly separated by phase, and stale/runtime_identity are distinct. However, before_change, query, and guard overlap: before_change already runs the guard when a proposal is supplied, and query also returns ruled-out alternatives for a path. The descriptions help, but an agent could easily pick the wrong one for a pre-edit context lookup.

Naming Consistency4/5

All tools share the commitlore_ prefix and use lowercase snake_case, which is a clear and consistent pattern. The capture tools use verb_noun (prepare_capture, verify_capture, stage_capture), but before_change, stale, and runtime_identity are stylistic deviations, so the set is mostly consistent rather than fully uniform.

Tool Count5/5

Eight tools is well-scoped for this server's purpose: three for the capture pipeline, three for reading/guarding context, plus stale and runtime identity. Each tool has a place and the set feels neither bloated nor thin.

Completeness4/5

The core workflow is covered: retrieving records/context, checking proposals, and the prepare/verify/stage capture pipeline. Minor gaps exist—such as no direct way to update, dismiss, or resolve stale records—but these are workable and may be intentionally outside the MCP surface.

Maintenance

ActivityActive

ResponsivenessResponsive

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

FairMind Project Context
ai.fairmind
Project memory for coding agents: requirements, decisions, code graph and delivery telemetry.
Knowledge & Memory Code Analysis
1
TeamShared C
io.github.xhad
Shared memory for coding agents. Stop re-explaining your codebase every session.
Knowledge & Memory Developer Tools
991
SeturosOAuth
com.seturos
Shared work memory for Claude Code, Codex, Cursor and chat, scoped to each repository.
Knowledge & Memory Developer Tools
1
Stele AOAuth
dev.stele-ai
Shared project memory for AI coding agents: decisions, lessons, risks and tasks in one graph.
Developer Tools Knowledge & Memory
201

Related MCP Servers

Projectmem
Knowledge & Memory Developer Tools
riponcm
A
license
A
quality
A
maintenance
Local-first memory layer for AI coding agents — captures issues, attempts, fixes, and decisions, and warns at git commit before you repeat a mistake.
Updated 4 days ago (2026-09-30 00:35 UTC)
17
173 PyPI
846
MIT
memini
Knowledge & Memory Developer Tools
lumayapartners
A
license
A
quality
C
maintenance
Local-first project memory for AI coding agents. Records failed attempts, fragile files, and decisions per repo, and warns the agent via hooks before it repeats a recorded mistake.
Updated 2 months ago (2026-07-22 13:48 UTC)
6
47 npm
MIT
robo-cortexofficial
Knowledge & Memory Developer Tools Version Control
robotel-limited
A
license
A
quality
A
maintenance
Provides a git-aware knowledge base for AI coding agents to store and retrieve memories anchored to code changes, with automatic staleness detection.
Updated a month ago (2026-08-31 02:12 UTC)
8
1
MIT
gitmem
Knowledge & Memory Project Management Developer Tools
KuraPiee
A
license
Not graded
quality
C
maintenance
Gives AI coding agents persistent, branch-aware memory and a dependency-tracked task graph by storing decisions, lessons, and tasks as plain JSON and Markdown committed directly into the repository. Agents can record and fuzzy-search past decisions, dump instant project context, and create, claim, complete, and query tasks whose completion automatically unblocks downstream work.
Updated 21 days ago (2026-09-12 17:23 UTC)
MIT

What CommitLore does

60 seconds to decision-aware agents

1. Install the CLI

2. Connect your agent

3. Initialize a repository

What the agent receives

Why Git?

Finding an old decision is not enough

How it works

What happens automatically

Squash-merge repositories

A field report, not a measurement

Unlike memory storage

Evidence

Limits, trust and privacy

Documentation

Contributing

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

robo-cortexofficial