Selvedge
Persistent local decision memory for AI agents: record and retrieve why changes were made, tied to code entities, via MCP tools.
Log changes or decisions with entity path, type, reasoning, diff, constraints, stale/expiry conditions, changesets, and commit metadata.
Record renames, rejections, reverts, and supersedes while preserving append-only history.
Query an entity's change history with prefix matching, see the latest blame and derived status (active/reverted/reopened), and inspect superseded links.
Browse and filter global history by time, project, entity, or changeset.
View all events in a changeset to reconstruct a feature or task.
Full-text search across entity paths, diffs, reasoning, and agents.
Check prior attempts before editing, with inferred outcomes, confidence, and optional fuzzy/semantic matching.
Surface stale decisions due for revisit via expiry, revisit dates, or matched invalidation conditions.
Use read-only retrieval tools and local SQLite storage; core retrieval makes no LLM calls.
Persistent decision memory for AI agents.
Save why you chose an approach, what you rejected, and what would change your mind. Retrieve that context in the next coding session, using a function, database column, API route or dependency as the lookup key.
Selvedge is for anyone using a compatible agent. Connect through local MCP
over stdio, or use the CLI from an agent with shell access. Decisions stay in
the same SQLite store in .selvedge/ when you switch tools.
No hosted account is required; core storage and retrieval make no LLM calls.
Get started · Documentation · Agent compatibility
uv tool install --upgrade selvedge
selvedge demoRequires uv and Python. Python 3.11–3.14 is recommended; Python 3.10 remains compatible but is end of life. The demo uses a temporary database. Follow the quickstart to connect your agent to a real project.
Use selvedge demo --mcp to save through a local stdio MCP server, restart it
and retrieve the same record. Add --json for the checked IDs and versions.
This tests the Python installation running Selvedge with disposable data;
your agent's configuration, activation and hooks still need a separate check.
Who Selvedge is for
Solo developers returning to a project after the original conversation is gone.
Teams that need to pass recorded decisions between sessions and coding tools.
Related MCP server: claude-engram
The problem
Code shows the chosen approach. It may leave out the constraint that shaped it or the alternative you ruled out. Selvedge gives those explanations a place in the project and tools to retrieve them before the next edit.
Only explicitly saved decisions can be recalled. A saved explanation is an account supplied by a person or agent; Selvedge does not verify that it is true or guarantee that an agent will consult it. Verify one decision across two sessions to test your setup.
What's new in v0.3.19
Read an existing decision store without enabling SQL writes.
Use SelvedgeStorage(path, read_only=True) from Python. It checks the
store's current schema without initializing or migrating it, and reads
committed WAL data. Default writable access is unchanged. Each call has
its own snapshot; SQLite may still create or update WAL/SHM sidecars.
This is not filesystem write confinement or an authorization boundary.
See the read-only library contract.
What's new in v0.3.18
Read the recorded reasons before routine review metadata. The optional GitHub review Action puts rejected and reverted approaches, revisions and constraints first. Its comment defaults to a 6,000-character budget, counts omitted events and links to the trusted base store and longer job summary. Unchanged reruns leave the comment untouched.
Healthy runs with no matching history keep the job summary without creating a new comment; an existing comment is refreshed and broken chains remain visible. Missing history is unknown, not approval. The Action still uses only publication-approved base history and never executes PR-head code.
A regression check also protects the library's local save/reopen/retrieve path with site packages unavailable and socket access blocked. No new runtime dependencies, migrations, MCP tools or model calls. Python 3.10 compatibility is retained; use supported Python 3.11–3.14 for new installations. Limited synthetic native Action runs verified comment creation, unchanged reruns, refresh to no matching history, and no comment for a fresh no-history PR. See the validation receipts. Broader native cases and human review usefulness remain unverified.
Where Selvedge fits
Save a decision. You or your coding agent record a choice, its reason, and any rejected approaches through MCP or the CLI.
Keep it with the project. Selvedge stores the record in local SQLite, keyed to the function, column, route or other entity it concerns.
Recall it before the next edit. A later session queries the same store and checks whether the earlier constraint still applies.
Git keeps the code history; review tools check changes; observability shows runtime behavior. Selvedge adds the recorded reasons behind decisions. How it works · Agent Trace interchange
How Selvedge compares
Choose the simplest memory mechanism that fits your workflow:
Need | Useful starting point | What Selvedge adds |
Standing project rules | Maintained agent instruction files | Queryable decisions attached to particular entities |
Reviewed architecture choices | Architecture decision records (ADRs) | Structured outcomes, rejected approaches and revisit signals |
Who changed a line and when | Git history and attribution tools | The stated reason and earlier approaches for an entity |
Carry recorded decisions into another session or client | Shared project documentation | MCP and CLI retrieval from the same local database |
These approaches can be used together. Read the source-linked comparison and instructions versus ADRs versus decision memory for specific selection criteria and limitations.
Why entity history matters. users.email, env/STRIPE_SECRET_KEY,
api/v1/checkout and deps/stripe remain useful query targets when their code
moves. Explicit rejection and superseding records let a later session inspect
what was tried and whether the original constraint still applies.
Why capture time matters. Recording a reason while the context is available can preserve information a diff does not contain. It does not make the reason infallible. Retrieval uses stored records; the coding agent remains responsible for checking applicability and testing its change.
Why changesets matter. Tag events with a shared changeset such as
add-stripe-billing to retrieve a task's decisions across tables, environment
variables, routes and functions.
Agent Trace interchange. selvedge export --format agent-trace and
selvedge import --format agent-trace exchange Agent Trace v0.1.0 records.
Reasoning and entity history travel in the dev.selvedge metadata.
The mapping and limits document the format;
Selvedge vendors the schema and has no runtime dependency on the upstream project.
Quickstart
Connect your agent
With uv installed:
uv tool install --upgrade selvedge
selvedge demo
cd your-project
selvedge setupSetup detects supported clients. To select a preset explicitly, use
--agent with claude-code, codex, copilot, cursor, gemini or windsurf;
repeat the flag for multiple clients. These presets are conveniences, not a
compatibility limit. For another agent with local stdio MCP support, follow
manual setup. Agents with shell access can use the CLI.
Prefer pip? Use python -m pip install --upgrade selvedge in a virtual environment.
The selvedge-server executable must be on your editor's PATH; launch the editor
from that environment or use the executable's absolute path in its MCP config.
Setup asks before changing files, backs up existing content, installs MCP and agent instructions, initializes the project, and offers a Git post-commit hook. Configuration files and lifecycle hooks vary by client. See the compatibility guide for preset paths, activation requirements and limitations.
Restart your agent in the project and approve Selvedge's tools if prompted. Follow your client's project-trust requirements. Ask the agent:
Use Selvedge to record one real approach we considered and rejected in this project. Include the entity, why, and what would change our mind. Do not invent a decision. Show the saved entity path and record ID.
Start a new session and look up the same entity to verify that the decision carries forward. Follow the first-decision verification guide and cross-agent handoff guide for observable checks. MCP access does not automatically capture every decision: the installed instructions guide the agent to use it. Native lifecycle adapters cover supported client events; startup delivery, watched-edit checks and compaction notifications vary by harness. See the agent hook guide before enabling them.
For CI bootstrap or devcontainer.json postCreateCommand:
selvedge setup --non-interactive --yesVerify the wiring — open a second terminal in the same project:
selvedge watchMake any change in your AI tool — add a column, rename a function, add an
env var. selvedge watch should print the new event within a second of
the agent calling log_change. If nothing arrives, run selvedge doctor
for a single-command health check that tells you which step is silently
broken.
Query your history:
selvedge status # recent activity + missing-commit count
selvedge diff users # all changes to the users table
selvedge diff users.email # changes to a specific column
selvedge blame payments.amount # what changed last and why
selvedge history --since 30d # last 30 days of changes
selvedge history --since 15m # last 15 minutes ('m' = minutes)
selvedge changeset add-stripe-billing # all events for a feature/task
selvedge search "stripe" # full-text search
selvedge stats # observed tool calls and explanation quality
selvedge import migrations/ # backfill from migration files
selvedge export --format csv # dump history to CSVIf you don't want to run the wizard, the four manual steps it automates:
1. Initialize in your project
cd your-project
selvedge init2. Register the MCP server
Configure your client to launch selvedge-server as a local stdio MCP server.
Use its absolute path if it is not on the client's PATH, and set SELVEDGE_DB
to the project database if the client starts outside your project. Configuration
syntax varies; see connection examples.
3. Tell your agent to use it
selvedge prompt --install path/to/agent-instructions.mdReplace path/to/agent-instructions.md with the actual file your client reads — the block
itself is identical across clients:
Client | Prompt file |
Claude Code |
|
Codex CLI (and other |
|
Cursor |
|
Gemini CLI |
|
This installs the canonical agent-instructions block, sentinel-bracketed
(<!-- selvedge:start --> / <!-- selvedge:end -->) so future
--install calls update the bracketed region without disturbing
anything else in the file. To print the block for copying:
selvedge promptPrefer to copy-paste? The same block is one click away on the website: selvedge.sh/prompt-block — with a copy button and notes on what your agent does with it.
4. Install the post-commit hook
selvedge install-hookThat's the same four steps the wizard runs.
Works with compatible agents
Selvedge has no required agent brand or model provider. Its MCP interface uses
local stdio: a compatible client must be able to launch selvedge-server and
call its tools. Remote-HTTP-only clients need a separate stdio bridge; Selvedge
does not provide a hosted endpoint. An agent with shell access can instead use
selvedge log and the read commands.
The integrations below are examples. Choose the one matching your client, or configure another stdio MCP client using its own settings format:
Optional Claude Code plugin
Two commands, inside Claude Code. No prior pip install — the plugin
bootstraps the server itself via uvx (or pipx):
/plugin marketplace add masondelan/selvedge
/plugin install selvedge@selvedgeThat's the whole agent-facing surface in one step:
the MCP server — 8 tools (
log_change,prior_attempts,blame,diff,history,changeset,search,stale_decisions);a skill that tells the agent when to call them — before editing a tracked entity, after any substantive change;
the PreToolUse enforcement hook — schema/migration edits are blocked until
prior_attemptshas been checked this session, with the prior reasoning in the block message;slash commands —
/selvedge:status,/selvedge:blame <entity>,/selvedge:history,/selvedge:prior-attempts <entity>.
The store (.selvedge/selvedge.db) creates itself on the first logged change.
Two optional extras stay CLI-side: the post-commit hook that stamps each event
with its commit hash (selvedge install-hook), and — if you want the
selvedge command on your own shell PATH — pip install selvedge, which the
launcher then prefers over uvx for an exact pinned version.
Plugin or
selvedge setupfor Claude Code? Pick one. Both wire the MCP server; running both registers it twice. The plugin is the lighter path and the one that updates itself. If you're on the plugin and only want the post-commit commit-hash stamping, runselvedge install-hookon its own.
Manual MCP connection
claude mcp add selvedge -- selvedge-serverOr commit a project-level .mcp.json so your whole team gets it:
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}Docs: https://code.claude.com/docs/en/mcp
.cursor/mcp.json (project) or ~/.cursor/mcp.json (global):
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}Cursor's newer schema also accepts an explicit "type": "stdio"; the
command-only form works too (Cursor infers stdio from command).
Docs: https://cursor.com/docs/mcp
~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}Windsurf hot-reloads the file — no restart needed. The in-app Plugins → View raw config button opens the exact file Cascade reads. Docs: https://docs.devin.ai/desktop/cascade/mcp
~/.codex/config.toml:
[mcp_servers.selvedge]
command = "selvedge-server"Or run codex mcp add selvedge -- selvedge-server.
Docs: https://learn.chatgpt.com/docs/config-file/config-reference
~/.gemini/settings.json (or .gemini/settings.json per project):
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}Or run gemini mcp add -s user selvedge selvedge-server.
Docs: https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md
Most clients share the same JSON shape — point yours at:
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}If selvedge-server isn't found, use its absolute path (which selvedge-server).
How it works
Selvedge runs as a local MCP server or CLI. Compatible agents call its tools as they work, logging structured change events to a local SQLite database.
Each event records:
What changed (entity path, change type, diff)
When (timestamp)
Who (agent, session ID)
Why (reasoning — captured from the agent's context in the moment)
Where (git commit, project)
The diff is git's job. The why is Selvedge's.
Selvedge tracks its own history
This repo dogfoods Selvedge: its .selvedge/selvedge.db is committed, so a
fresh clone ships with Selvedge's own why-history. Clone it and ask why any
part of Selvedge changed:
git clone https://github.com/masondelan/selvedge
cd selvedge
selvedge status # recent changes to Selvedge itself
selvedge search "telemetry" # why the opt-in heartbeat shipped
selvedge blame selvedge/semantic.py # why semantic search was addedEvery event was logged by the agents that built Selvedge — the same
log_change calls this README asks you to make in your own project.
Entity path conventions
users.email DB column (table.column)
users DB table
src/auth.py::login Function in a file (path::symbol)
src/auth.py File
api/v1/users API route
deps/stripe Dependency
env/STRIPE_SECRET_KEY Environment variablePrefix queries work everywhere: users returns users, users.email,
users.created_at, and any other entity under the users. namespace.
MCP tools
When connected as an MCP server, Selvedge exposes:
Tool | Description |
| Record a change event with entity, diff, and reasoning. |
| History for an entity or entity prefix, each row annotated with |
| Most recent change + context for an exact entity, plus the derived decision |
| Filtered history across all entities |
| All events grouped under a named feature/task slug |
| Full-text search across all events |
| Prior change attempts on an entity + inferred outcome (tried → reverted → re-opened) — call it before editing. Optional |
| Decisions due for a revisit: past their |
CLI reference
selvedge init [--path PATH] Initialize in project
selvedge status Recent activity summary
selvedge diff ENTITY [--limit N] Change history for entity
selvedge blame ENTITY Most recent change + context
selvedge history [--since SINCE] Browse all history
[--entity ENTITY]
[--project PROJECT]
[--changeset CS]
[--summarize]
[--limit N]
selvedge changeset [CHANGESET_ID] Show events in a changeset
[--list] or list all changesets
[--project NAME]
[--since SINCE]
selvedge search QUERY [--limit N] Full-text search
selvedge prior-attempts ENTITY Prior attempts + inferred outcome,
[--description T] with the tried → reverted →
[--all] re-opened trail + status line
[--window 7d] (--all widens recall)
[--fuzzy TEXT] add semantic matches (needs the
semantic extra; substring fallback)
selvedge supersede ENTITY Re-open a reverted decision —
--reasoning TEXT append-only, links the prior
[--constraint TEXT] reverted event (or --supersedes ID)
[--stale-when TEXT]
[--supersedes ID]
selvedge index [--model NAME] Build/update the optional semantic
[--json] embeddings index (selvedge[semantic])
selvedge stale [--entity ENTITY] Decisions due for a revisit: past
[--project NAME] revisit_after + still in use, or
[--agent NAME] stale_when matched by a later change
[--json] ("review suggested")
selvedge stats [--since SINCE] Tool call coverage report (per-tool, per-agent)
selvedge doctor [--agent CLIENT] [--json] Health check; optional project agent-hook diagnostics
selvedge install-hook [--path PATH] Install git post-commit hook
[--window MIN] (default 60 minutes)
selvedge backfill-commit --hash HASH Backfill git_commit on recent events
[--window MIN] (default 60 minutes)
selvedge import PATH Import migrations (SQL / Alembic) or
[--format auto|sql| an Agent Trace file (agent-trace)
alembic|agent-trace]
[--from-git] or walk git history for reverts:
[--since REF|DATE] revert-message commits + deletions
[--project NAME] become change_type="revert" events
[--dry-run] (idempotent on commit + entity)
selvedge export [--format json|csv| Export history (agent-trace =
markdown|agent-trace] Agent Trace v0.1.0 records;
markdown = reviewable digest)
[--since SINCE]
[--entity ENTITY]
[--ndjson] agent-trace: one record per line
[--collapse-by-session] agent-trace: merge a session into one
[--output FILE]
selvedge log ENTITY CHANGE_TYPE Manually log a change
[--diff TEXT] CHANGE_TYPE: add, remove, modify,
[--reasoning TEXT] rename, retype, create, delete,
[--agent NAME] index_add, index_remove, migrate,
[--commit HASH] revert, supersede
[--project NAME]
[--changeset CS]
[--revisit-after WHEN] ISO date or offset (e.g. 90d)
[--rename-from OLD] OLD path when CHANGE_TYPE is 'rename'
[--constraint TEXT] the principle behind the decision
[--stale-when TEXT] what would invalidate it
[--supersedes ID] with CHANGE_TYPE 'supersede'
selvedge migrate-paths Re-canonicalize stored entity paths
[--apply] (dry-run by default; --apply writes)
[--json]All read commands support --json for machine-readable output.
Relative time in --since:
15m→ last 15 minutes (m= minutes)24h→ last 24 hours7d→ last 7 days5mo→ last 5 months (moormon= months)1y→ last year
Unparseable inputs (e.g. --since yesterday) exit with a clear error
rather than silently returning empty results. ISO 8601 timestamps
are also accepted and normalized to UTC.
Configuration
Method | Format | Example |
Env var |
| Per-session override |
Project init |
| Creates |
Global fallback |
| Used if no project DB found |
Hook watch globs |
|
|
Project settings |
| See the key list below — retention, size bounds, redaction patterns |
Global settings |
| Same keys; the project file wins where both set one |
Hook bypass |
| Disables the PreToolUse enforcement hook for the shell |
Semantic extra |
| Enables |
.selvedge/config.toml
Every key is optional; a missing file means the defaults below. Precedence is
CLI flag → env var → project .selvedge/config.toml → global
~/.selvedge/config.toml → default. SELVEDGE_DB is the one exception: it
always wins for database resolution, because the config file is found by
resolving that path. selvedge doctor prints the effective value and the step
that produced it for every setting.
retention_days_events = 0 # 0 = never delete events (the default)
retention_days_tool_calls = 90 # local telemetry retention
backup_keep_last = 7
diff_bytes = 65536 # truncate oversized diffs at log time
reasoning_bytes = 32768 # truncate oversized reasoning
db_size_warn_mb = 500 # doctor warns above this
stale_days = 0 # 0 = off
digest_max_bytes = 4096 # cap on the session-start digest
redaction_patterns = [] # extra secret shapes to warn about
[hook]
watch_globs = ["**/migrations/**", "db/**/*.sql"]Every key also has an env override (SELVEDGE_DIFF_BYTES,
SELVEDGE_RETENTION_DAYS_EVENTS, …).
Reviewing captured intent in a pull request
.selvedge/selvedge.db is a SQLite file, so the reasoning inside it doesn't
show up in a diff. If you want a reviewable copy, export a Markdown digest:
selvedge export --format markdown -o .selvedge/DECISIONS.md
git add .selvedge/DECISIONS.mdThe digest is grouped by entity with reverted and rejected decisions first.
Explicit reject events appear under Considered and rejected, separate from
Tried and reverted. The latest event determines the section; a later
supersede moves either kind to Re-opened while retaining the full history.
Human-readable blame also labels explicit rejections as "rejected". For API
compatibility, JSON status and trail phase keep the existing reverted
negative-verdict category; change_type: "reject" identifies a rejection.
The digest is deterministic — regenerating with no new events produces a zero-line diff, so it stays reviewable instead of becoming noise everyone learns to skip. Heading anchors derive from the entity path, so links into it keep working as it grows. Regenerate it in the same commit as the code, or from a pre-commit hook.
To catch a stale or missing digest in a hook or CI, use the same filters and
output path with --check:
selvedge export --format markdown -o .selvedge/DECISIONS.md --checkThe check exits 0 silently when the UTF-8, LF-terminated bytes match,
1 with a unified diff when stale or missing (or an error when unreadable),
and 2 for invalid arguments. It requires Markdown and an explicit file;
stdout and other formats are rejected. It does not rewrite the digest, create
or migrate a database, change stored records, or start background update and
telemetry checks. Use an existing initialized store in CI, selected through the
normal database resolution or SELVEDGE_DB. SQLite may maintain its normal WAL
locking files while reading. Regenerate without --check to update the digest.
Publishing either the digest or database is optional. Review captured reasoning and metadata for secrets and private information before committing or sharing them; a generated diff can also expose that information in CI logs.
Coverage checking
Wondering how often your agent actually calls log_change? Two ways to check:
# Quick summary in the terminal
selvedge stats
# Cross-reference against git commits
python scripts/coverage_check.py --since 30dThe coverage script compares your git log against Selvedge events and shows
which commits have associated change events. Low coverage usually means the
system prompt needs strengthening — see docs/fallbacks.md for guidance.
In CI (GitHub Action)
The same check ships as the Selvedge Coverage Check composite Action, so you can track agent coverage on every push — and optionally fail the build when it drops:
# .github/workflows/selvedge-coverage.yml
name: Selvedge coverage
on: [push, pull_request]
jobs:
coverage:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # full history so commits can be matched
- uses: masondelan/selvedge@v0.3.19 # pin to a release tag (or @main for latest)
with:
since: 30d
fail-under: "0.5" # optional: fail below 50% coverage; omit to report onlyIt writes a coverage summary to the job summary and exposes coverage-ratio,
covered, and total as step outputs. The action cross-references your git
history against the Selvedge event log, so the runner needs the project's
.selvedge/selvedge.db (commit it, or restore it before this step) and full
git history (fetch-depth: 0). Inputs: since, window, limit,
fail-under, selvedge-version, python-version, working-directory,
db-path.
Contributing
Read the feedback and review process for reporting problems, evaluating feature requests and following up on discussions.
git clone https://github.com/masondelan/selvedge
cd selvedge
pip install -e ".[dev]"
pytestSee CLAUDE.md for architecture details and the phase roadmap.
License
MIT — see LICENSE.
Decision context for reviewers
The shared ledger and PR review Action shows recorded reasons, rejected paths, actor/session attribution and integrity for touched entities. The matched injection pilot reports every trial and limits its conclusion to the tested synthetic tasks.
Available Tools
8 toolsblameBlame an entityARead-onlyIdempotent
Most recent change to an entity — what changed, when, who, why.
Like git blame but for semantic entities (DB columns, functions, env
vars, dependencies) and AI agents. Also carries the derived decision
state: status (active / reverted / reopened) and
superseded_by (id of a later supersede overriding this change, or
""). If no history exists for the entity, returns {"error": "..."}
with protocol-level isError: false.
Inputs: entity_path (required). Returns: id, diff, agent, error, +17 more
changesetGet a changesetARead-onlyIdempotent
All events that share a changeset_id, oldest first.
Use to reconstruct the full scope of a feature or task across multiple
entities. If the changeset has no events, returns
[{"error": "..."}] so the caller can distinguish "unknown changeset"
from "empty history."
Inputs: changeset_id (required). Returns: result
diffDiff an entity's historyARead-onlyIdempotent
Get change history for a codebase entity, newest first.
Supports prefix matching — e.g. 'users' returns all events for the users
table and any users.* column. Each event carries a derived
superseded_by id ("" when nothing overrode it), so the
tried → reverted → re-opened trail reads straight off the history.
Inputs: entity_path (required), limit. Returns: result
historyBrowse historyARead-onlyIdempotent
Filtered change history across all entities, newest first.
Combine since, entity_path, project, and changeset_id to scope
the result. On unparseable since input the response is
[{"error": "..."}] so the caller sees the problem.
Inputs: limit, since, project, entity_path, +1 more. Returns: result
log_changeLog a code changeA
Record a change to a codebase entity.
Call this immediately after making any meaningful change. The event is
written to the local SQLite store and returned with its assigned id and
timestamp. If the reasoning fails the quality validator (empty, too
short, or a generic placeholder), or the entity_path doesn't match the
usual shape for its entity_type, the result includes a warnings
array — the event is still stored.
Renames: pass the new path in entity_path, set change_type="rename",
and pass the old path in rename_from. Selvedge then writes two events —
a rename on the old path and a create on the new path with
metadata.renamed_from set — so the entity's history follows it. Example:
log_change(
entity_path="src/auth/session.py::login", # new path
change_type="rename",
rename_from="src/auth.py::login", # old path
entity_type="function",
reasoning="Split auth.py into an auth/ package; login moved.",
)Rejections: when you consider an approach and decide against it WITHOUT
writing the change, record the verdict with change_type="reject" — the
abandoned path is a first-class event, and the next agent's
prior_attempts query finds it as a high-confidence ("exact") row
instead of re-deriving the dead end. Name what was rejected AND what was
chosen instead, and record the condition that would invalidate the
verdict. Example:
log_change(
entity_path="users.card_pan",
change_type="reject",
entity_type="column",
reasoning="Rejected storing raw card PANs on the user row — "
"went with provider tokens instead; PANs in our own "
"DB put us in PCI scope.",
stale_when="payment provider changed",
expires_when="entity:deps/stripe:changes",
)Use change_type="revert" for the sibling case — the change WAS written
and then rolled back (clearer than a plain remove).
Superseding a reverted decision: when a reverted change becomes correct
again (the constraint that killed it no longer holds), do NOT delete or
edit history — log with change_type="supersede" and the reason. The
new event links the prior revert (auto-resolved when supersedes is
empty) and every read surface then reports the trail
tried → reverted → re-opened. Never re-apply a reverted change without
superseding it first.
On validation failure (invalid change_type, missing entity_path,
rename_from set without change_type='rename', supersedes set without
change_type='supersede', a supersede with nothing to re-open, or an
expires_when outside the closed grammar) the result is
{"status": "error", "error": "..."} with no event written.
Inputs: change_type (required), entity_path (required), diff, agent, +12 more. Returns: id, error, status, warnings, +2 more
prior_attemptsPrior attempts on an entityARead-onlyIdempotent
Prior change attempts on an entity, each with an inferred outcome.
Call this BEFORE editing an entity. If the same change was tried before
and reverted, you get the prior reasoning and change_type plus an
inferred outcome — so you can change your plan instead of repeating a
rejected approach.
Each result is a change event plus the trail fields: outcome
("reverted" — a later removal on the path; "reopened" — closed but a
later supersede re-opened it; "rejected" — a standalone reject event
that closed no earlier attempt, surfaced as its own row whose reasoning
IS the record; "active"), confidence ("exact" — the attempt was closed
by an explicit revert/reject, or the row is a standalone rejection;
"proximity_high" / "proximity_low" — the add->remove window heuristic
for implicit removals), outcome_reasoning (WHY it was rejected),
superseded_by + supersede_reasoning (the re-open, when present), and
current_status — the entity's standing now. Treat "reverted" and
"rejected" as "don't repeat this without a supersede"; "reopened" means
the old verdict no longer stands. Together they read: tried → reverted →
re-opened. Templated and deterministic — no LLM call; pull-only.
Conservative by design — min_confidence defaults to "proximity_high",
so an empty list (nothing clearly tried-and-rejected) is the normal,
preferred answer over a speculative false positive; "exact" rows always
clear that default floor. Pass min_confidence="proximity_low" to widen
recall. Rows carry match_type ("exact" / "substring" / "fuzzy") and
similarity.
Inputs: fuzzy, limit, description, entity_path, +2 more. Returns: result
searchSearch eventsARead-onlyIdempotent
Full-text search across entity paths, diffs, reasoning, and agents.
Useful for questions like 'what changes were made for the billing feature?', 'which columns were added by cursor?', or 'show everything related to authentication'.
Inputs: query (required), limit. Returns: result
stale_decisionsStale decisions due for revisitARead-onlyIdempotent
Decisions due for a revisit — expired, past their date, or with a triggered stale condition.
Three deterministic rules. Expiry-based (flag="expired"): events whose
expires_when condition fired, evaluated from local state only —
date: against now, entity:PATH:changes against the event log,
library:NAME>=VERSION against installed dist metadata; the pattern
kind that fired is in expired_pattern. A library: condition whose
dependency isn't locally observable surfaces as flag="manual_review"
instead of a guess; manual:LABEL never auto-fires. Date-based
(flag="revisit_due"): events whose revisit_after has passed AND the
entity is still live (queried via blame/diff/prior_attempts after
the decision, or its changeset saw later activity) — pure age alone
never surfaces. Condition-based (flag="review_suggested"): events
whose stale_when text shares keywords with a LATER change event — the
named invalidation evidence may have happened. Surfacing only: nothing
is un-retired automatically; follow up with a supersede if the
condition really was triggered. A later supersede that re-opens the
candidate (explicit supersedes id, or the same id-less auto-link
prior_attempts uses) drops it from this list; a same-path sibling
the supersede did not target still surfaces.
Each result is the change event plus flag, revisit_due,
days_overdue, active_use_signals, matched_terms,
matched_event_id, expires_status, expired_pattern,
expires_detail, and a one-line stale_reason. Date-due rows first,
most-overdue leading; filter by entity_path, project, or agent.
Templated and deterministic; no LLM call, no network.
Inputs: agent, limit, project, entity_path. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools have clearly distinct scopes: log_change is the only writer; diff is entity-scoped history, history is cross-entity, changeset groups by id, and search is full-text. The main ambiguity is diff vs. blame — blame returns only the newest event and adds a status field, but it is effectively the first row of diff, so an agent could reasonably pick either for 'what changed most recently.'
The naming mixes three conventions: git-style single-word verbs (diff, blame, search), bare nouns (history, changeset), and descriptive snake_case phrases (log_change, prior_attempts, stale_decisions). The styles are individually readable and the git-inspired cluster ties the read tools together, but there is no single predictable verb_noun pattern across the set.
Eight tools is well within the ideal 3-15 range and each tool earns its place in the change-logging domain: one writer, four retrieval views (per-entity, latest, global, changeset-grouped), one search, one pre-edit decision helper, and one maintenance/review tool. The count feels tightly scoped with no obvious redundancy or bloat.
The surface fully covers the domain's lifecycle: log_change handles all event types (including rename, reject, revert, and supersede), and the read side provides entity-scoped history, latest state, cross-entity filters, changeset reconstruction, full-text search, pre-edit attempt lookup, and stale-decision review. The append-only design intentionally omits update/delete, which the descriptions explicitly justify, so there are no real dead ends for the stated purpose.
Maintenance
Related MCP Connectors
One searchable history across every AI coding tool, with secret scanning and a shared task board.
Shared, scoped, reviewable team memory for AI coding agents.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Codebase intelligence for AI coding agents: graph, git history, docs, decisions, code health.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceThe shared AI context engine for git — save, search, and share the reasoning behind code changes. Captures the why behind every commit and slide on PRs for coding agents.MIT
- AlicenseBqualityBmaintenancePersistent memory and session intelligence for AI coding assistants. Auto-tracks mistakes, decisions, and context via hooks. Mines your full session history for patterns, predictions, and cross-session search.2116MIT
- AlicenseAqualityAmaintenanceLocal-first memory layer for AI coding agents — captures issues, attempts, fixes, and decisions, and warns at git commit before you repeat a mistake.19978 PyPI877MIT
- AlicenseNot gradedqualityDmaintenanceProvides a memory layer for AI coding agents with Git-powered version control, enabling automatic tracking of prompts, context, and code diffs.194MIT