Skip to content
selvedge

selvedge

Long-term memory for AI-coded codebases.

AI writes the code; the reason it chose that approach lives in a chat window that's gone by morning. Selvedge is a git blame for the why — a local MCP server your agent (Claude Code, Cursor, Copilot) calls as it works, recording the intent behind each change in the moment it makes it, not reconstructing it from the diff afterward.

pip install selvedge
Get started Why Selvedge? GitHub

The problem

Section titled “The problem”

Six months ago, your AI agent added a column called user_tier_v2. You don’t know why. git blame points to a commit from claude-code with a generated message that says “Update schema.” The session that made the change is long gone — and so is the prompt that produced it.

With Selvedge, you run this instead:

selvedge blame user_tier_v2 surfaces the reasoning the agent recorded for a change — the why, captured live, right in the terminal.

That reasoning was captured by the agent in the moment — written into Selvedge from the same context that produced the change. Not inferred from the diff afterward by a second LLM. Not a hand-typed commit message.

It also reads back out: Selvedge exports its history as Agent Trace records, so the why travels into whatever observability or audit tooling already speaks that format.

What Selvedge does, in three lines

Section titled “What Selvedge does, in three lines”

Captures the why, live

AI agents call Selvedge’s MCP tools while they work — log_change records what they changed and why, in the same context window that produced the change.

Tracks entities, not lines

Every change is tagged to the thing you actually search for — users.email, env/STRIPE_SECRET_KEY, api/v1/checkout, deps/stripe — not a line number. Search users and you get everything under it.

Stays local, stays simple

Almost nothing to install, nothing to run. A SQLite file under .selvedge/ next to your code. No accounts, no servers, no telemetry.

And it reads back. Before editing an entity, your agent calls prior_attempts — and gets back what was already tried there, and how it ended:

prior_attempts({ "entity_path": "users.auth_token" })
// → one hit, outcome: "reverted" (2026-03-12)
//   "Tokens in the DB meant we couldn't revoke without a write; moved to
//    short-lived JWTs verified statelessly. Column unused."

So the agent doesn’t re-add a column the team already pulled — it plans around the reason instead. No line-attribution tool surfaces a rejected path at all. Full case study, with the plan it chose instead →

Quickstart

Section titled “Quickstart”

Three commands. The third one is interactive — it detects which AI tools are on your machine (Claude Code, Cursor, Copilot) and wires Selvedge into each one’s config. Every modified file gets a .bak written before any change reaches disk.

Terminal window
pip install selvedge
cd your-project
selvedge setup

That’s it. Open a second terminal and run selvedge watch to live-tail events as your agent makes them. Then start asking your codebase questions:

Terminal window
selvedge blame payments.amount         # what changed last and why
selvedge history --entity users --since 30d  # all changes to users in 30 days
selvedge changeset add-stripe-billing  # all events for a feature
selvedge search "stripe"               # full-text search

Full quickstart →  ·  CLI reference →  ·  MCP tool reference →

Add it to your editor

Section titled “Add it to your editor”

selvedge setup already wires the editors it finds. To add the selvedge-server MCP server to one yourself, every editor below has a step-by-step page:

Each page’s config runs the server with uvx, so it works without a global install — just have uv on your machine. Prefer pip? pip install selvedge and point your editor at the selvedge-server command.

Cursor Paste the MCP config, or run selvedge setup.
VS Code A .vscode/mcp.json block.
Claude Code claude mcp add, or the plugin marketplace.
Cline The autonomous VS Code agent.
Windsurf Cascade MCP config.
Continue config.yaml mcpServers block.

Who it’s for

Section titled “Who it’s for”

Teams running long-term, AI-coded codebases. When the project is big enough that someone will touch it again in twelve months, three years — but most of it was written by an agent whose context evaporated the day each PR shipped. git blame tells you what changed. Selvedge tells you why — even after the agent session, the prompt, the developer who asked for it, and the model version are all long gone.

Solo developers using Claude Code on everyday projects. Side projects, weekend builds, the small internal tool you keep poking at. You don’t need enterprise governance — you just need to remember why you (or your agent) did the thing you did yesterday, last week, last sprint.

If you’ve ever come back to your own AI-built project and thought “what was this for again?” — that’s the question Selvedge already has the answer to.

Where Selvedge fits

Section titled “Where Selvedge fits”

AI agents call Selvedge as they work. It captures the why into a durable, queryable store — and exports it in the open Agent Trace format, so the reasoning travels into whatever observability or audit tooling you already run.

Selvedge does not replace git (line-level what/when), PR review tools (review-time quality), agent observability (LLM call traces), or general-purpose code-host AI features. It sits between them — the layer that records why, so git, review, and observability tools finally have something to point at.

See the comparison table →

Listings

Section titled “Listings”

Selvedge is open source (MIT) and lives in four directories beyond GitHub.