Selvedge compatibility and capabilities

Persistent decision memory for AI agents. Selvedge works with any compatible agent through local stdio MCP or the CLI. Save why code changed and which approaches were rejected, then retrieve that context in later sessions.

These facts describe Selvedge 0.3.17. The package’s released source is the authority for shipped behavior. Client permissions and instruction support also affect actual use.

Connection requirements

Selvedge is for anyone using a compatible agent. Agent names and model providers do not select different storage or history behavior. Compatibility is about the interface available in your agent environment:

• Local stdio MCP: the client can launch selvedge-server and call its tools.
• CLI: the agent can run selvedge commands with shell access.

A remote-HTTP-only MCP client cannot connect directly to the stdio server. Both supported interfaces use the same project database. See manual setup for other compatible agents.

Optional setup presets

These six presets automate configuration and project instructions. They are not a complete list of compatible agents. All use the same eight MCP tools; paths without ~/ are relative to the project.

MCP access is available for every listed target. The hooks column describes Selvedge’s shipped integrations; it does not inspect your installation. Review client activation and validation limits in the lifecycle guide.

Agent	Setup flag	MCP configuration	Instructions	Selvedge lifecycle hooks
Claude Code	claude-code	.mcp.json	CLAUDE.md	Startup, edit gate, compaction reminder
Codex	codex	.codex/config.toml	AGENTS.md	Startup, edit gate, compaction notice
Copilot (VS Code Local)	copilot	.vscode/mcp.json	.github/copilot-instructions.md	Startup, edit gate, compaction notice
Cursor	cursor	~/.cursor/mcp.json	.cursorrules	Startup, edit gate, compaction notice
Gemini CLI	gemini	.gemini/settings.json	GEMINI.md	Startup, edit gate, compaction notice
Windsurf	windsurf	~/.codeium/windsurf/mcp_config.json	.windsurfrules	Edit and command gates

All six targets have native hook adapters as of 0.3.15. Codex, Cursor, VS Code Copilot Local and Gemini CLI support startup context, a watched-edit gate, and advisory compaction notifications. Windsurf/Cascade provides edit and command checks. A notification does not inject model context or save a decision automatically.

Read the capabilities, activation and validation limits. The new adapters have contract and subprocess coverage; Codex’s edit denial and retry were also observed in CLI 0.154.0-alpha.6.2. The other four new clients have not yet been tested end to end. Copilot CLI/cloud/Agent Host are not covered by the Local adapter. Other MCP clients can be configured manually through the MCP reference.

As of 0.3.16, selvedge doctor --agent CLIENT checks the selected client’s project hook configuration and reports next steps. Activation still requires client review. selvedge ledger adds a read-only attributed history view; the optional PR review Action surfaces publication-approved base history. Actor labels are self-reported.

As of 0.3.17, selvedge demo --mcp saves and retrieves the same synthetic record across two local server processes. It checks the installed server, while client configuration, activation and hooks remain separate checks. The optional Markdown export --check checks a review digest against existing history without rewriting it.

When Selvedge is useful

Need	What Selvedge provides	What you still need to do
Preserve why code changed	Stated rationale tied to a function, table, route, dependency or other entity	Record useful reasons while the context is available
Check earlier rejected approaches	Explicit rejected/reverted outcomes and queryable history	Retrieve the relevant record and assess whether its constraint applies
Carry decisions between coding tools	MCP and CLI access to the same local store	Connect both clients to the same database
Reconsider an old decision	Review dates, supported expiry conditions and superseding events	Inspect current evidence; review signals do not decide correctness
Keep storage under your control	Local SQLite, MIT license, no required account or hosted service	Back up the database and control who can read it

What “reasoning” means

Selvedge stores explanations explicitly supplied by people or agents. It does not extract a model’s hidden internal reasoning or establish that a saved explanation is correct. Imported history is limited to what its source contains. Recorded versus inferred reasoning explains the distinction.

Storage, dependencies and privacy

Run selvedge init or setup to create .selvedge/selvedge.db in your project. A global fallback and overrides also exist; use selvedge doctor to inspect the effective path. The package accepts Python 3.10+ for compatibility; use an upstream-supported Python release as described in the quickstart. Declared runtime dependencies are required. Default history queries need neither an LLM nor embeddings; optional fuzzy lookup uses local embeddings.

Your coding client may send retrieved records to its model provider. Local storage does not change that client’s policy. An optional usage heartbeat is off by default; the CLI also has a PyPI version check. See the FAQ and configuration reference.

Choose and verify

Standing rules and reviewed architecture decisions may be well served by maintained instruction files or ADRs. Selvedge adds entity queries and explicit outcome history. Read the comparison, then verify a real decision in a fresh session. A successful lookup demonstrates retrieval; a tested change demonstrates how the agent used it.

For a controlled comparison, evaluate decision memory with alternative information delivery and cases where old advice no longer applies.