Selvedge
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| SELVEDGE_DB | No | Path to the SQLite database file. Overrides project and global defaults. | |
| SELVEDGE_QUIET | No | Set to '1' to suppress warnings about using global database fallback. | |
| SELVEDGE_LOG_LEVEL | No | Logging level for the Selvedge server. One of DEBUG, INFO, WARNING, ERROR. | WARNING |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Selvedge captures the WHY behind every change to a codebase — written live by the agent making the change, before the session context evaporates. The diff is git's job; the reasoning is Selvedge's.
WHEN TO CALL log_change: immediately after you add, remove, or modify a meaningful semantic entity — a DB column, table, function, class, API endpoint, file, dependency, env var, config flag, or index. One log_change per entity. Don't batch.
WHAT GOES IN reasoning: the user's original ask, the constraint or bug that prompted the change, and any decision that wouldn't be obvious from the diff in six months. 'User asked to add 2FA — needs phone for SMS verification' is good. 'user request', 'done', 'fix' are flagged by the quality validator as low-signal placeholders.
GROUP related changes with the same changeset_id (a short slug like 'add-stripe-billing'). Pass the same id to every log_change for that feature so they can later be retrieved together via the changeset tool.
BEFORE EDITING an entity, call prior_attempts on it — if the same change was tried before and reverted, you'll see why and can change your plan instead of repeating a rejected approach. A reverted decision is not a permanent ban: if the constraint that killed it no longer holds, log a change with change_type='supersede' to re-open it (the trail then reads tried -> reverted -> re-opened). Never re-apply a reverted change without superseding it first.
STRUCTURED REASONING (optional): alongside free-text reasoning, log_change accepts constraint (the testable principle behind the decision, e.g. 'card data in our own DB = PCI scope') and stale_when (what would invalidate it, e.g. 'payment provider changed'). stale_decisions matches stale_when against later events and flags decisions worth re-checking.
REVISIT DATES: when you make an architectural change (a table, schema, dependency, or config) that should be reconsidered later, set revisit_after on log_change — an ISO date or a relative offset like '90d'. stale_decisions surfaces those once they age out AND the entity is still in active use.
WHEN TO READ:
prior_attempts — 'was this entity tried-and-rejected before? why?'
blame — 'who/why for THIS entity, most recent change'
diff — 'full history for THIS entity, newest first'
history — 'everything in the last N days/across a project'
changeset — 'all changes that belong to THIS feature'
search — 'anything mentioning these words'
stale_decisions — 'which dated decisions are now due for a revisit?'
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| log_changeA | Record a change to a codebase entity. Call this immediately after making any meaningful change. The event is
written to the local SQLite store and returned with its assigned id and
timestamp. If the reasoning fails the quality validator (empty, too
short, or a generic placeholder), or the entity_path doesn't match the
usual shape for its entity_type, the result includes a Renames: pass the new path in Rejections: when you consider an approach and decide against it WITHOUT
writing the change, record the verdict with Use Superseding a reverted decision: when a reverted change becomes correct
again (the constraint that killed it no longer holds), do NOT delete or
edit history — log with On validation failure (invalid change_type, missing entity_path,
|
| diffA | Get change history for a codebase entity, newest first. Supports prefix matching — e.g. 'users' returns all events for the users
table and any users.* column. Each event carries a derived
|
| blameA | Most recent change to an entity — what changed, when, who, why. Like |
| historyA | Filtered change history across all entities, newest first. Combine |
| changesetA | All events that share a Use to reconstruct the full scope of a feature or task across multiple
entities. If the changeset has no events, returns
|
| searchA | Full-text search across entity paths, diffs, reasoning, and agents. Useful for questions like 'what changes were made for the billing feature?', 'which columns were added by cursor?', or 'show everything related to authentication'. |
| prior_attemptsA | Prior change attempts on an entity, each with an inferred outcome. Call this BEFORE editing an entity. If the same change was tried before
and reverted, you get the prior Each result is a change event plus the trail fields: Conservative by design — |
| stale_decisionsA | Decisions due for a revisit — expired, past their date, or with a triggered stale condition. Three deterministic rules. Expiry-based ( Each result is the change event plus |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 8 tools
Most tools have clearly distinct scopes: log_change is the only writer; diff is entity-scoped history, history is cross-entity, changeset groups by id, and search is full-text. The main ambiguity is diff vs. blame — blame returns only the newest event and adds a status field, but it is effectively the first row of diff, so an agent could reasonably pick either for 'what changed most recently.'
The naming mixes three conventions: git-style single-word verbs (diff, blame, search), bare nouns (history, changeset), and descriptive snake_case phrases (log_change, prior_attempts, stale_decisions). The styles are individually readable and the git-inspired cluster ties the read tools together, but there is no single predictable verb_noun pattern across the set.
Eight tools is well within the ideal 3-15 range and each tool earns its place in the change-logging domain: one writer, four retrieval views (per-entity, latest, global, changeset-grouped), one search, one pre-edit decision helper, and one maintenance/review tool. The count feels tightly scoped with no obvious redundancy or bloat.
The surface fully covers the domain's lifecycle: log_change handles all event types (including rename, reject, revert, and supersede), and the read side provides entity-scoped history, latest state, cross-entity filters, changeset reconstruction, full-text search, pre-edit attempt lookup, and stale-decision review. The append-only design intentionally omits update/delete, which the descriptions explicitly justify, so there are no real dead ends for the stated purpose.