selvedge

Selvedge is a tool that provides "persistent decision memory" for AI agents. Its core goal is to fill in a missing link in code history: code can show the final chosen approach, but it often fails to reveal the constraints that shaped it, as well as the alternatives that were ruled out at the time. Selvedge gives these explanations a place in the project and provides tools to retrieve them before the next edit.

Who it is for

• Independent developers returning to a project long after the original conversation has been lost.
• Teams that need to pass recorded decisions across different sessions and different coding tools.

How it works Selvedge runs as a local MCP server or CLI. Compatible agents call its tools during their work, writing 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 (rationale—captured at the moment from the agent's context);
• where (Git commit, project). diff is Git's responsibility, while "why" is Selvedge's responsibility.

Core features

• Save decisions via MCP or CLI: record a choice, the rationale, and the rejected options.
• Save alongside the project: records are stored in local SQLite, keyed by function, column, route, or other relevant entity.
• Recall before the next edit: subsequent sessions query the same store to check whether earlier constraints still apply.
• ledger: shows who recorded each decision, and which later record explicitly revised it.
• doctor: checks the project hook configuration for six setup targets and gives specific next steps.
• watch: verifies that the wiring is working correctly, printing a new event within one second after the agent calls log_change.
• Query history: supports retrieval by entity, time, and other conditions.
• Agent Trace exchange: selvedge export --format agent-trace and selvedge import --format agent-trace can exchange Agent Trace v0.1.0 records, with rationale and entity history passed along with dev.selvedge metadata.
• All read commands support --json to output machine-readable results.
• --since supports relative times: 15m (15 minutes), 24h (24 hours),7d (7 days), 5mo (5 months). Unparseable input raises an explicit error rather than silently returning an empty result; ISO 8601 timestamps are also accepted and normalized to UTC.

Entity path conventions Prefix queries work everywhere: querying users returns users, users.email, users.created_at, and other entities under the users. namespace. users.email, env/STRIPE_SECRET_KEY, api/v1/checkout, and deps/stripe remain valid query targets after code moves.

Usage Requires uv and Python 3.10+. Installation options include:

• via uv (see the official docs for the install command);
• if you prefer pip, run python -m pip install --upgrade selvedge in a virtual environment;
• it can also be enabled as a plugin in Claude Code; the plugin bootstraps the server itself via uvx (or pipx), and includes an 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, a PreToolUse enforcement hook, and slash commands such as /selvedge:status, /selvedge:blame <entity>, /selvedge:history, /selvedge:prior-attempts <entity>. The storage file .selvedge/selvedge.db is created automatically on the first recorded change.

Setup flow Setup automatically detects supported clients. Use --agent to explicitly choose a preset: claude-code, codex, copilot, cursor, gemini, or windsurf; repeat the flag to select multiple clients. These presets are conveniences, not compatibility limits. For other agents that support local stdio MCP, follow the manual setup; agents with shell access can use the CLI. Setup asks before modifying files, backs up existing content, installs MCP and agent instructions,initializes the project, and provides a Git post-commit hook. Manual four steps:

1. Initialize in the project;
2. Register the MCP server: configure the client to start selvedge-server as a local stdio MCP server, using an absolute path if it is not on PATH, and point SELVEDGE_DB at the project database if the client starts outside the project;
3. Tell the agent to use it: write the canonical agent-instructions block (marked by <!-- selvedge:start --> / <!-- selvedge:end -->) into the file the client reads;
4. Install the post-commit hook.

Configuration Every key in .selvedge/config.toml is optional, and a missing file means defaults are used. Precedence is: CLI flags → environment variables → project .selvedge/config.toml → global ~/.selvedge/config.toml → defaults. SELVEDGE_DB is the only exception: it always takes precedence in database resolution. Every key has a corresponding environment variable override (such as SELVEDGE_DIFF_BYTES, SELVEDGE_RETENTION_DAYS_EVENTS, etc.). selvedge doctor prints the effective value of each setting and the step that produced it.

Using it in code review selvedge ledger shows who recorded each decision and which later records explicitly revise it. An optional PR review Action adds rationale and rejected alternatives for changed files from the published approved base history. Attribution is self-reported; the Action is optional and never executes PR head code.

Version update highlights v0.3.16: ledger supports code review; doctor --agent CLIENT checks hook configuration for all six targets; the match-injection pilot completed 24 synthetic trials (two synthetic tasks are insufficient to establish general coding performance or superiority over maintaining files, and the earlier four-arm tie is still disclosed); no new runtime dependencies, migrations, or MCP tools. v0.3.15: native lifecycle adapters for all six setup targets (Codex, Cursor, VS Code Copilot Local, Gemini CLI, Windsurf/Cascade, and Claude Code); startup context and watched-edit checks are available where the client supports them, compaction notices are advisory, and Windsurf provides only edit and command checks; existing configuration is preserved, with backups and conflicts shown for custom hooks.

Limitations and caveats

• Only explicitly saved decisions can be recalled. A saved explanation is a statement provided by a person or agent; Selvedge does not verify its truthfulness, nor does it guarantee that an agent will consult it.
• A decision should be verified across two sessions to test the setup.
• MCP access does not automatically capture every decision: the installed instructions merely guide the agent to use it.
• Native lifecycle adapters cover supported client events; startup delivery, watched-edit checks, and compaction notices vary by runtime environment.
• Clients that support only remote HTTP require a separate stdio bridge; Selvedge does not provide a hosted endpoint.
• A configuration check does not prove that the client has activated its hooks (for example, selvedge doctor's configuration check).
• The tool does not claim to be superior to maintaining the same information in files or prompts.

Selvedge tracks its own history: the repository dogfoods its own tool, and .selvedge/selvedge.db is committed, so a fresh clone comes with Selvedge's own "why" history, in which every event was recorded by the agents that built Selvedge through the same log_change call.