Selvedge

What is Selvedge?

Selvedge is decision provenance for AI-coded codebases: the why, and what was already tried and rejected.

Coding agents (Claude Code, Cursor, Copilot) call Selvedge's MCP tools as they work to log structured change events — the entity (DB column, table, function, API endpoint, dependency, env var), the diff, the stated reasoning, and the verdict, including "tried and rejected." Events land in an append-only SQLite store in .selvedge/ next to your code (git-tracked by design). Retrieval is templated and deterministic: no LLM anywhere in the storage or retrieval path, so the same query returns the same answer today and in two years, and a rejection is a permanent, queryable record.

Selvedge exports and imports Agent Trace v0.1.0, so captured history round-trips with the emerging open standard for AI code attribution.

How to use Selvedge?

Install via pip install selvedge, then run selvedge setup — the wizard configures Claude Code, Cursor, and Copilot in one pass. Ask selvedge blame <entity> for the most recent change and its reasoning, or check prior attempts on an entity before re-implementing something the team may already have killed.

Key features of Selvedge

• Append-only event log: entity, change type, diff, reasoning, verdict — rejected paths stay queryable forever (prior_attempts)
• 8 MCP tools at a CI-verified 3,705-token schema tax; deterministic, templated retrieval (no LLM in the path)
• Entity-level attribution (users.email, env/STRIPE_SECRET_KEY, deps/stripe) and changesets across many entities
• Delivery hooks (v0.3.10): a relevance-gated SessionStart digest and an advisory PreCompact heads-up — read-only, fail-open, quiet when there's nothing to say
• selvedge export --format markdown: a deterministic, diff-stable digest to commit next to .selvedge/
• Agent Trace v0.1.0 export and import
• Local SQLite, zero external dependencies, first-class .selvedge/config.toml

FAQ from Selvedge

How does Selvedge differ from git blame?

Git blame tells you who wrote a line. Selvedge tells you what not to write next: the reasoning the agent stated at change time, and whether an approach was already tried and rejected.

Does "no LLM in the path" mean no AI?

The agent supplying the reasoning is an LLM; the storage and retrieval path has no model in it. Nothing downstream re-interprets the record, so the same query is stable across model versions. One opt-in extra (prior-attempts --fuzzy, local embeddings, ~30 MB) ranks records that were already written deterministically — it never generates or rewrites reasoning.

Where does Selvedge store data?

In a SQLite file under .selvedge/ in your project directory (git-tracked by design), or globally at ~/.selvedge/selvedge.db. Transport is MCP over JSON-RPC stdio.