# Selvedge

Selvedge is for anyone using a compatible agent, regardless of brand or model provider. Connect through local stdio MCP or invoke the CLI with shell access. Setup presets and native lifecycle adapters are optional conveniences, not an exhaustive list of compatible agents. Remote-HTTP-only clients cannot connect directly to the stdio server.

> Selvedge is a local MCP server and CLI for recording code decisions, stated reasoning, and rejected approaches. Selvedge's log_change writes events; Selvedge's prior_attempts retrieves recorded attempts and outcomes before a later edit. SQLite storage, MIT licensed, no LLM in the core. Capture and retrieval require the agent or user to call the tools.

Save a decision while the context is available, then retrieve the recorded reason in a later session. Retrospective records and imports can preserve explanations supplied by their source; they cannot recover missing reasoning. With [uv installed](https://docs.astral.sh/uv/getting-started/installation/), run `uv tool install --upgrade selvedge`, then `selvedge setup`.

## Start here

- [Evaluate decision memory](https://selvedge.sh/guides/evaluate-decision-memory/): Controls, observable evidence, failures and pilot limitations.
- [Native lifecycle hooks](https://selvedge.sh/guides/agent-lifecycle-hooks/): per-client activation, edit gates, startup context, compaction notifications and validation limits.
- [Compatibility and capabilities](https://selvedge.sh/reference/compatibility/): released behavior, setup targets, native lifecycle capabilities, storage and limitations.
- [Verify your first decision](https://selvedge.sh/guides/verify-first-decision/): check recording, fresh-session retrieval and application separately.
- [Share memory between agents](https://selvedge.sh/guides/share-memory-between-agents/): a repeatable handoff using the same database, including worktree and context-loss caveats.
- [Home](https://selvedge.sh): what Selvedge is, who it's for, the quickstart.
- [Quickstart](https://selvedge.sh/start/quickstart/): `uv tool install --upgrade selvedge`, the optional setup presets, and manual MCP or CLI connection for any compatible agent.
- [Agent prompt block](https://selvedge.sh/prompt-block/): the copy-paste `CLAUDE.md` / `.cursorrules` block that tells an agent when and how to call Selvedge. Also emitted by `selvedge prompt`.
- [How to stop AI coding agents repeating mistakes](https://selvedge.sh/prior-attempts/): a copyable project rule and hypothetical caching example. Record a rejected approach, retrieve it before editing, and reconsider it when the constraint changes; retrieval does not guarantee compliance.
- [The MCP server that tracks why your AI agent changed code](https://selvedge.sh/track-why/): the write path (`log_change`, live, in the agent's own words) and the read path (`blame`, `history`) for decision provenance.
- [AI coding agent memory across sessions](https://selvedge.sh/agent-memory/): preserve decision records and retrieve them in later sessions. Default lookup uses entity paths and deterministic rules; optional fuzzy lookup ranks candidates with local embeddings.
- [A local decision audit trail for AI-written code](https://selvedge.sh/audit-trail/): who/what/when/why per entity, searchable, exportable as Agent Trace records.
- [How Selvedge compares](https://selvedge.sh/compare/agent-tools/): Selvedge vs. AgentDiff / Origin / Git AI / BlamePrompt — captured-live + entity-level + changesets.
- [Codebase memory MCP servers, compared](https://selvedge.sh/compare/codebase-memory-mcp-servers/): a sourced comparison of code navigation, session context, general memory and decision history. Includes overlap between tools and a later-session retrieval checklist.

- [Revisit a rejected approach](https://selvedge.sh/guides/revisit-a-rejected-approach/): tested CLI walkthrough.
- [Instruction files and ADRs](https://selvedge.sh/compare/instructions-and-adrs/): choose a record format your team will maintain.
- [Codex setup](https://selvedge.sh/mcp/codex/): MCP configuration and project instructions.
- [Gemini CLI setup](https://selvedge.sh/mcp/gemini/): MCP configuration and project instructions.

An empty query result means no qualifying record was found, not that the approach was never tried. MCP clients may send retrieved records to their model providers. Keep private records in a private destination.

## MCP tools (8, over stdio)
- `log_change`: record a change event with entity, diff, and reasoning (pass `rename_from` with `change_type="rename"` for renames).
- `prior_attempts`: prior change attempts on an entity + outcome — was it tried and reverted, or considered and rejected? Stated outcomes (explicit `revert`/`reject` events) report `confidence: "exact"`; proximity inference is the tiebreaker. Call it *before* editing.
- `blame`: most recent change + context for an exact entity.
- `diff`: history for an entity or entity prefix.
- `history`: filtered history across all entities.
- `changeset`: all events grouped under a named feature/task slug.
- `search`: full-text search across all events.
- `stale_decisions`: decisions due for a revisit — a machine-checkable `expires_when` condition fired, `revisit_after` passed while the entity is still in active use (pure age never surfaces), or a later change matched the decision's `stale_when`.

## Concepts
- [Agent memory and code decision concepts](https://selvedge.sh/concepts/): Definitions, examples, and practical guides for agent memory, code provenance, prior attempts, and decisions that need review.
- [What is code provenance? An AI coding example](https://selvedge.sh/concepts/ai-code-provenance/): Understand code provenance, AI attribution, and decision history with a concrete example. Learn which fields to record and how to retrieve them.
- [What is agent memory for a coding project?](https://selvedge.sh/concepts/agent-memory/): Agent memory is information retained beyond an agent’s current context and made available to later work.
- [What is a prior attempt in a coding decision?](https://selvedge.sh/concepts/prior-attempt/): A prior attempt is an earlier approach considered or implemented for a task or part of a codebase.
- [What is entity-level tracking for code decisions?](https://selvedge.sh/concepts/entity-level-tracking/): Entity-level tracking associates a record with an identifiable part of a system, such as a function, database column, route, or dependency.
- [What is a changeset in Selvedge?](https://selvedge.sh/concepts/changeset/): In Selvedge, a changeset is a group of recorded events sharing a changeset identifier for a feature, task, or other unit of work.
- [What is a stale decision in an AI-coded project?](https://selvedge.sh/concepts/stale-decision/): A stale decision is a recorded choice whose assumptions, constraints, or review conditions may no longer match the current project.
- [Recorded versus inferred reasoning: what is the difference?](https://selvedge.sh/concepts/captured-live-vs-inferred/): Recorded reasoning is an explanation explicitly supplied by an agent or person and preserved with a decision.

## Reference
- [README](https://github.com/masondelan/selvedge/blob/main/README.md): full overview, MCP tool table, CLI reference, entity-path conventions.
- [Changelog](https://github.com/masondelan/selvedge/blob/main/CHANGELOG.md): what shipped, per version.
- [Architecture](https://github.com/masondelan/selvedge/blob/main/docs/architecture.md): data model, phase plan, non-goals.
- [Agent Trace interop](https://selvedge.sh/compare/agent-trace/): Selvedge supports Agent Trace v0.1.0 import and export. Verify field preservation in receiving tools.
- [prior_attempts demo](https://github.com/masondelan/selvedge/blob/main/docs/demos/prior-attempts.md): worked transcript of an agent checking history and changing its plan.

## Install
- PyPI: https://pypi.org/project/selvedge/ — `uv tool install --upgrade selvedge`
- GitHub: https://github.com/masondelan/selvedge
- Claude Code plugin: `/plugin marketplace add masondelan/selvedge` then `/plugin install selvedge@selvedge`