Selvedge

What is Selvedge?

Selvedge is a long-term memory system for AI-coded codebases that captures the reasoning behind code changes as they are made by AI agents. It stores why a change was made, not just what changed, using an MCP server that agents call during development.

How to use Selvedge?

Install via pip install selvedge, run selvedge init once, and add configuration lines to your CLAUDE.md. Use commands like selvedge blame <entity> to see the history and reasoning behind any code change.

Key features of Selvedge

• Captures agent reasoning live during code changes, not inferred post-hoc
• Entity-level attribution for database columns, tables, env vars, APIs, functions
• Changeset grouping across multiple entities for complex feature rollouts
• SQLite storage with zero external dependencies
• Concurrent write support with retry logic and WAL mode
• CLI commands: blame, status, diff, search, history, import

Use cases of Selvedge

• Debugging schema decisions months after the AI agent session has ended
• Understanding why a specific database column or API endpoint was added
• Auditing dependency changes across long-running AI-coded projects
• Solo developers tracking reasoning across weekend builds and side projects
• Pulling up the full scope of a billing migration that touched multiple files

FAQ from Selvedge

How does Selvedge differ from git blame?

Git blame tells you what changed and when. Selvedge captures why the change was made, with reasoning written by the AI agent from the same context that produced the change.

What are the dependencies and runtime requirements?

Selvedge uses SQLite for storage with zero external dependencies. Install via pip.

Where does Selvedge store data?

In a SQLite file under .selvedge/ in your project directory, or globally at ~/.selvedge/selvedge.db.

What transports and authentication does Selvedge use?

Selvedge communicates via MCP protocol over JSON-RPC stdio transport.

How does reasoning capture work?

Reasoning is captured live by the AI agent during the change, written from the same context window that produced the modification. This contrasts with tools that infer reasoning post-hoc from the diff.