AI代码记忆

Quickstart

pip install selvedge
cd your-project
selvedge setup

That's it. selvedge setup is an interactive wizard: it detects which AI tools you have (Claude Code, Cursor, Copilot), writes the MCP entry into each one's config, drops the canonical agent-instructions block into your project's prompt file (CLAUDE.md / .cursorrules / copilot-instructions.md), runs selvedge init, and installs the post-commit hook. Every modified file gets a .bak written next to it before any change reaches disk. Re-running is a no-op.

For CI bootstrap or devcontainer.json postCreateCommand:

selvedge setup --non-interactive --yes

Configuration

---

CLI reference

selvedge init [--path PATH]               Initialize in project
selvedge status                           Recent activity summary
selvedge diff ENTITY [--limit N]          Change history for entity
selvedge blame ENTITY                     Most recent change + context
selvedge history [--since SINCE]          Browse all history
              [--entity ENTITY]
              [--project PROJECT]
              [--changeset CS]
              [--summarize]
              [--limit N]
selvedge changeset [CHANGESET_ID]         Show events in a changeset
                  [--list]                or list all changesets
                  [--project NAME]
                  [--since SINCE]
selvedge search QUERY [--limit N]         Full-text search
selvedge stats [--since SINCE]            Tool call coverage report (per-tool, per-agent)
selvedge doctor [--json]                  Health check: DB path, schema, hook, MCP wiring
selvedge install-hook [--path PATH]       Install git post-commit hook
                     [--window MIN]       (default 60 minutes)
selvedge backfill-commit --hash HASH      Backfill git_commit on recent events
                        [--window MIN]    (default 60 minutes)
selvedge import PATH                      Import migration files (SQL / Alembic)
              [--format auto|sql|alembic]
              [--project NAME]
              [--dry-run]
selvedge export [--format json|csv]       Export history to JSON or CSV
              [--since SINCE]
              [--entity ENTITY]
              [--output FILE]
selvedge log ENTITY CHANGE_TYPE           Manually log a change
             [--diff TEXT]                CHANGE_TYPE: add, remove, modify,
             [--reasoning TEXT]           rename, retype, create, delete,
             [--agent NAME]               index_add, index_remove, migrate
             [--commit HASH]
             [--project NAME]
             [--changeset CS]

All read commands support --json for machine-readable output.

Relative time in --since: - 15m → last 15 minutes (m = minutes) - 24h → last 24 hours - 7d → last 7 days - 5mo → last 5 months (mo or mon = months) - 1y → last year

Unparseable inputs (e.g. --since yesterday) exit with a clear error rather than silently returning empty results. ISO 8601 timestamps are also accepted and normalized to UTC.

---

Cross-reference against git commits

python scripts/coverage_check.py --since 30d ```

The coverage script compares your git log against Selvedge events and shows which commits have associated change events. Low coverage usually means the system prompt needs strengthening — see docs/fallbacks.md for guidance.

---

How Selvedge compares

There's a fast-growing "git blame for AI agents" category. Here's where Selvedge fits — and where it deliberately doesn't.

Why "captured live" matters. AgentDiff and Origin generate reasoning after the change is made, by feeding the diff back to a second LLM call. Selvedge's reasoning is the agent's own intent, written from the same context window that produced the change — no inference, no hallucinated explanations, and an empty reasoning field is itself a useful signal (the agent didn't have one).

Why "entity-level" matters. Most tools attribute lines. Selvedge attributes things you actually search for: users.email, env/STRIPE_SECRET_KEY, api/v1/checkout, deps/stripe. The first question after git blame is usually "what's the history of this column", not "what's the history of lines 40–48 of users.py".

Why "changesets" matter. A Stripe billing rollout touches the users table, two new env vars, three new API routes, one dependency, and four functions across the codebase. Tag every event with changeset:add-stripe-billing and you can pull the entire scope back later — even if the original PR was broken into eight smaller ones over a month.

Selvedge ↔ Agent Trace. Agent Trace (Cursor + Cognition AI, RFC Jan 2026, backed by Cloudflare, Vercel, Google Jules, Amp, OpenCode, and git-ai) is an emerging open standard for AI code attribution traces. Selvedge isn't a competitor to it — it's a compatible producer. The design for selvedge export --format agent-trace is at docs/agent-trace-interop.md. Agent Trace is the wire format. Selvedge is the live capture + query layer that emits it.

---

Claude Code plugin marketplace (alternative)

If you're a Claude Code user and want to install Selvedge through the official plugin marketplace flow, run these inside Claude Code after pip install selvedge:

/plugin marketplace add masondelan/selvedge
/plugin install selvedge@selvedge

The plugin system wires the MCP server into Claude Code, but it does not install the Python package for you — `pip install selvedge first, otherwise the selvedge-server` command won't exist on your PATH and the plugin can't start. For the full setup (post-commit hook, project CLAUDE.md instructions block, etc.), selvedge setup is still the recommended path; the plugin marketplace install is just the lightweight Claude-Code-only entry point.

Verify the wiring — open a second terminal in the same project:

selvedge watch

Make any change in your AI tool — add a column, rename a function, add an env var. selvedge watch should print the new event within a second of the agent calling log_change. If nothing arrives, run selvedge doctor for a single-command health check that tells you which step is silently broken.

Query your history:

selvedge status                        # recent activity + missing-commit count
selvedge diff users                    # all changes to the users table
selvedge diff users.email              # changes to a specific column
selvedge blame payments.amount         # what changed last and why
selvedge history --since 30d           # last 30 days of changes
selvedge history --since 15m           # last 15 minutes ('m' = minutes)
selvedge changeset add-stripe-billing  # all events for a feature/task
selvedge search "stripe"               # full-text search
selvedge stats                         # log_change coverage report (per-agent)
selvedge import migrations/            # backfill from migration files
selvedge export --format csv           # dump history to CSV

<details> <summary><b>Manual install</b> — if you'd rather wire it up yourself</summary>

If you don't want to run the wizard, the four manual steps it automates:

1. Initialize in your project

cd your-project
selvedge init

2. Add to your Claude Code config

~/.claude/config.json:

{
  "mcpServers": {
    "selvedge": {
      "command": "selvedge-server"
    }
  }
}

For Cursor: ~/.cursor/mcp.json. For Copilot: .github/copilot-instructions.md (different format — see selvedge prompt --help).

3. Tell your agent to use it

selvedge prompt --install CLAUDE.md

This installs the canonical agent-instructions block, sentinel-bracketed (` / `) so future --install calls update the bracketed region without disturbing anything else in the file. Or pipe it:

selvedge prompt | tee -a CLAUDE.md

4. Install the post-commit hook

selvedge install-hook

That's the same four steps the wizard runs.

</details>

---