Selvedge

selvedge.sh  ·  DevHunt  ·  PyPI  ·  GitHub

为 AI Agent 提供持久化决策记忆。

记录你为何选择某种方案、否决了什么，以及什么情况会让你改变主意。下一次编码会话时，可以通过函数、数据库列、API 路由或依赖项检索这些上下文。

Selvedge 面向所有使用兼容 Agent 的人。通过 stdio 上的本地 MCP 连接，或在具备 shell 访问权限的 Agent 中使用命令行。切换工具时，决策仍保存在 .selvedge/ 中的同一个 SQLite 存储内。 无需托管账户；核心存储和检索不会调用大模型。

开始使用 · 文档 · Agent 兼容性

uv tool install --upgrade selvedge
selvedge demo

需要安装 uv 和 Python。 推荐使用 Python 3.11–3.14；Python 3.10 仍兼容，但已停止维护。 演示会使用临时数据库。按照快速入门 将 Agent 连接到实际项目。

使用 selvedge demo --mcp 通过本地 stdio MCP 服务保存记录，重启服务后再检索同一条记录。添加 --json 可查看已检查的 ID 和版本。 此操作会使用临时数据，测试运行 Selvedge 的 Python 安装； Agent 的配置、激活和钩子仍需单独检查。

Selvedge 面向哪些人

• 独立开发者：在原始对话结束后重新回到项目时使用。
• 团队：需要在会话和编码工具之间传递已记录的决策。

问题

代码展示了所选方案，却可能没有说明促成该选择的限制条件，或被排除的替代方案。Selvedge 在项目中为这些说明提供了存放位置，并提供工具，让你在下一次修改之前检索这些内容。

只有明确保存的决策才能被找回。保存的说明由人或 Agent 提供；Selvedge 不会验证其真实性，也不保证 Agent 会查阅这些说明。通过在两个会话中验证一项决策来测试设置。

v0.3.17 新增内容

审查前检查已记录的决策。 生成 Markdown 摘要，然后运行 selvedge export --format markdown -o DECISIONS.md --check 来检查是否存在偏差。 摘要完全一致时会静默退出，返回码为 0；摘要已过时或缺失时会返回码为 1，并显示统一差异和重新生成指南。检查模式会保留摘要 和已存储的记录。发布前请先审查导出的推理内容。

selvedge demo --mcp 会通过真实的本地 MCP 服务保存一条合成的否决记录，重启服务后再检索同一条记录。它使用一次性状态； 不会验证你的 Agent 配置或钩子是否已激活。

CLI 输出现在会保留用户数据中的字面方括号，而 blame 和 Markdown 导出会区分被否决的方案与尝试后又撤销的更改。 此补丁仍兼容 Python 3.10，但该运行时现已 上游停止支持；新安装请使用经过测试且受支持的 Python 3.11–3.14。没有新增运行时依赖、迁移或 MCP 工具。

v0.3.16 新增内容

将已记录的决策带入代码审查。 selvedge ledger 会显示每项决策由谁记录，以及后续哪条记录明确修订了它。可选的 PR 审查 Action 会从获准发布的基础历史中，为涉及的文件添加原因和被否决的替代方案。归属信息由用户自行报告；Action 为可选功能，绝不会执行 PR 分支头部的代码。

selvedge doctor --agent CLIENT 会检查全部六种设置目标的项目钩子配置，并提供具体的后续步骤。配置检查并不能证明客户端已激活其钩子。

匹配注入试点完成了 24 次合成试验：在没有记忆的情况下，仍然有效的已否决选项在符合条件的运行中有 4/6 次再次出现；注入记录后为 0/6 次。两种条件都通过了过时和无关项对照测试。两个合成任务无法证明一般编码表现或优于受维护文件；此前四组测试结果持平的情况仍有披露。没有新增运行时依赖、迁移或 MCP 工具。

Selvedge 的定位

1. 保存决策。 你或编码 Agent 通过 MCP 或 CLI 记录一项选择、其原因， 以及任何被否决的方案。
2. 将其保存在项目中。 Selvedge 将记录存储在本地 SQLite 中， 并根据相关函数、列、路由或其他实体为其建立索引。
3. 在下一次编辑前回想起来。 后续会话会查询同一存储区， 并检查先前的约束是否仍然适用。

Git 保留代码历史；审查工具检查更改；可观测性展示 运行时行为。Selvedge 补充记录在案的决策原因。 工作原理 · Agent Trace 互操作

Selvedge 对比

选择最契合你工作流的最简记忆机制：

这些方法可以结合使用。阅读源码链接对比与指令、ADR 与决策记忆的对比，了解具体的选择标准与局限。

为何实体历史很重要。 当 users.email、env/STRIPE_SECRET_KEY、api/v1/checkout 和 deps/stripe 的代码发生迁移时，它们仍是有用的查询目标。明确的否决与取代记录能让后续会话查看曾尝试过什么，以及原始约束是否仍然适用。

为何记录时间很重要。 在上下文尚可用时记录理由，可以保留 diff 中不包含的信息。这并不意味着理由绝对可靠。检索使用的是已存储的记录；编码 Agent 仍需负责核验适用性并测试其改动。

为何变更集很重要。 用共享的变更集（如 add-stripe-billing）标记事件，即可跨表、环境变量、路由与函数检索某个任务的全部决策。

Agent Trace 交换。 selvedge export --format agent-trace 与 selvedge import --format agent-trace 用于交换 Agent Trace v0.1.0 记录。推理与实体历史随 dev.selvedge 元数据一同传递。映射与限制文档说明了该格式；Selvedge 内置了该 schema，对上游项目没有运行时依赖。

快速开始

连接你的 Agent

在已安装 uv 的情况下：

uv tool install --upgrade selvedge
selvedge demo
cd your-project
selvedge setup

安装程序会检测支持的客户端。若要显式选择预设，可使用 --agent 搭配 claude-code、codex、copilot、cursor、gemini 或 windsurf；为多个客户端重复该标志即可。这些预设只是便利手段，并非兼容性限制。对于其他支持本地 stdio MCP 的 Agent，请遵循手动设置。有 shell 访问权限的 Agent 可以使用 CLI。偏好 pip？请在虚拟环境中使用 python -m pip install --upgrade selvedge。selvedge-server 可执行文件必须位于编辑器的 PATH 中；请从该环境启动编辑器，或在其 MCP 配置中使用该可执行文件的绝对路径。

安装程序在更改文件前会先询问，备份现有内容，安装 MCP 与 Agent 指令，初始化项目，并可选提供 Git post-commit 钩子。配置文件和生命周期钩子因客户端而异。关于预设路径、激活要求与局限，请参阅兼容性指南。

在项目中重启你的 Agent，并在提示时批准 Selvedge 的工具。遵循你所使用客户端的项目信任要求。向 Agent 提问：

使用 Selvedge 记录我们在此项目中考虑并否决的一个真实方案。 包含实体、原因，以及什么会让我们改变主意。不要编造决策。 显示保存的实体路径和记录 ID。 启动一个新会话并查找同一实体，以验证该决策是否得以延续。按照首次决策验证指南和跨 Agent 交接指南进行可观测的检查。MCP 访问不会自动捕获每一项决策：已安装的指令会引导 Agent 使用它。原生生命周期适配器覆盖受支持的客户端事件；启动交付、监视编辑检查和压缩通知因 harness 而异。启用之前，请参阅 Agent 钩子指南。

用于 CI 引导或 devcontainer.json 的 postCreateCommand：

selvedge setup --non-interactive --yes

验证接线 — 在同一项目中打开第二个终端：

selvedge watch

在你的 AI 工具中做任意更改 — 添加一列、重命名一个函数、添加一个 环境变量。selvedge watch 应在 Agent 调用 log_change 后一秒内 打印新事件。如果没有收到任何内容，请运行 selvedge doctor 进行单命令健康检查，它会告诉你哪一步在悄无声息地失效。

查询你的历史记录：

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                         # observed tool calls and explanation quality
selvedge import migrations/            # backfill from migration files
selvedge export --format csv           # dump history to CSV

cd your-project
selvedge init

selvedge prompt --install path/to/agent-instructions.md

selvedge prompt

selvedge install-hook

适用于兼容的 Agent

Selvedge 不要求特定的 Agent 品牌或模型提供商。其 MCP 接口使用 本地 stdio：兼容的客户端必须能够启动 selvedge-server 并 调用其工具。仅支持远程 HTTP 的客户端需要单独的 stdio 桥接；Selvedge 不提供托管端点。具有 shell 访问权限的 Agent 可以改为使用 selvedge log 和读取命令。

以下集成仅为示例。选择与你的客户端匹配的那个，或 使用其自身设置格式配置另一个 stdio MCP 客户端：

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

claude mcp add selvedge -- selvedge-server

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

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

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

[mcp_servers.selvedge]
command = "selvedge-server"

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

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

工作原理

Selvedge 以本地 MCP 服务或命令行的形式运行。兼容的 Agent 在工作过程中调用其工具， 将结构化变更事件记录到本地 SQLite 数据库。

每个事件记录：

• 什么发生了变化（实体路径、变更类型、diff）
• 何时（时间戳）
• 谁（Agent、会话 ID）
• 为什么（推理 —— 在当下从 Agent 的上下文中捕获）
• 何处（git 提交、项目）

diff 是 git 的职责。为什么是 Selvedge 的职责。

Selvedge 跟踪自己的历史

本仓库自用 Selvedge：其 .selvedge/selvedge.db 已被提交，因此全新克隆就自带 Selvedge 自己的 why 历史。克隆它，然后询问 Selvedge 的任何部分为何变更：

git clone https://github.com/masondelan/selvedge
cd selvedge
selvedge status                       # recent changes to Selvedge itself
selvedge search "telemetry"           # why the opt-in heartbeat shipped
selvedge blame selvedge/semantic.py   # why semantic search was added

每个事件都由构建 Selvedge 的 Agent 记录 —— 正是本 README 要求你在自己项目中进行的那同样的 log_change 调用。

实体路径约定

users.email           DB column (table.column)
users                 DB table
src/auth.py::login    Function in a file (path::symbol)
src/auth.py           File
api/v1/users          API route
deps/stripe           Dependency
env/STRIPE_SECRET_KEY Environment variable

前缀查询在任何地方都有效：users 会返回 users、users.email、 users.created_at，以及 users. 命名空间下的任何其他实体。

MCP 工具

作为 MCP 服务连接时，Selvedge 会提供：

CLI 参考

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 prior-attempts ENTITY            Prior attempts + inferred outcome,
                       [--description T]   with the tried → reverted →
                       [--all]             re-opened trail + status line
                       [--window 7d]       (--all widens recall)
                       [--fuzzy TEXT]      add semantic matches (needs the
                                           semantic extra; substring fallback)
selvedge supersede ENTITY                 Re-open a reverted decision —
                  --reasoning TEXT         append-only, links the prior
                  [--constraint TEXT]      reverted event (or --supersedes ID)
                  [--stale-when TEXT]
                  [--supersedes ID]
selvedge index [--model NAME]             Build/update the optional semantic
              [--json]                     embeddings index (selvedge[semantic])
selvedge stale [--entity ENTITY]          Decisions due for a revisit: past
              [--project NAME]            revisit_after + still in use, or
              [--agent NAME]              stale_when matched by a later change
              [--json]                    ("review suggested")
selvedge stats [--since SINCE]            Tool call coverage report (per-tool, per-agent)
selvedge doctor [--agent CLIENT] [--json] Health check; optional project agent-hook diagnostics
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 migrations (SQL / Alembic) or
              [--format auto|sql|         an Agent Trace file (agent-trace)
                 alembic|agent-trace]
              [--from-git]                or walk git history for reverts:
              [--since REF|DATE]          revert-message commits + deletions
              [--project NAME]            become change_type="revert" events
              [--dry-run]                 (idempotent on commit + entity)
selvedge export [--format json|csv|       Export history (agent-trace =
                 markdown|agent-trace]      Agent Trace v0.1.0 records;
                                            markdown = reviewable digest)
              [--since SINCE]
              [--entity ENTITY]
              [--ndjson]                  agent-trace: one record per line
              [--collapse-by-session]     agent-trace: merge a session into one
              [--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]              revert, supersede
             [--project NAME]
             [--changeset CS]
             [--revisit-after WHEN]       ISO date or offset (e.g. 90d)
             [--rename-from OLD]          OLD path when CHANGE_TYPE is 'rename'
             [--constraint TEXT]          the principle behind the decision
             [--stale-when TEXT]          what would invalidate it
             [--supersedes ID]            with CHANGE_TYPE 'supersede'
selvedge migrate-paths                    Re-canonicalize stored entity paths
                      [--apply]           (dry-run by default; --apply writes)
                      [--json]

所有读取命令都支持 --json，以输出机器可读的结果。

--since 中的相对时间：

• 15m → 最近 15 分钟（m = 分钟）
• 24h → 最近 24 小时
• 7d → 最近 7 天
• 5mo → 最近 5 个月（mo 或 mon = 月）
• 1y → 最近 1 年

无法解析的输入（例如 --since yesterday）会以清晰的错误退出， 而不会静默返回空结果。也接受 ISO 8601 时间戳，并会将其标准化为 UTC。

配置

.selvedge/config.toml

所有键均为可选；缺少文件时使用下方默认值。优先级为 CLI 标志 → 环境变量 → 项目 .selvedge/config.toml → 全局 ~/.selvedge/config.toml → 默认值。SELVEDGE_DB 是唯一例外：它 始终优先用于数据库解析，因为配置文件是通过解析该路径来找到的。 selvedge doctor 会显示每项设置的有效值及其来源步骤。

retention_days_events     = 0       # 0 = never delete events (the default)
retention_days_tool_calls = 90      # local telemetry retention
backup_keep_last          = 7
diff_bytes                = 65536   # truncate oversized diffs at log time
reasoning_bytes           = 32768   # truncate oversized reasoning
db_size_warn_mb           = 500     # doctor warns above this
stale_days                = 0       # 0 = off
digest_max_bytes          = 4096    # cap on the session-start digest
redaction_patterns        = []      # extra secret shapes to warn about

[hook]
watch_globs = ["**/migrations/**", "db/**/*.sql"]

每个键也都有对应的环境变量覆盖项（SELVEDGE_DIFF_BYTES、 SELVEDGE_RETENTION_DAYS_EVENTS，……）。

在拉取请求中审查已记录的意图

.selvedge/selvedge.db 是一个 SQLite 文件，因此其中的推理不会显示在差异中。如果你需要一份可供审查的副本，可以导出为 Markdown 摘要：

selvedge export --format markdown -o .selvedge/DECISIONS.md
git add .selvedge/DECISIONS.md

摘要按实体分组，已撤销和已拒绝的决策优先显示。明确的 reject 事件会显示在已考虑并拒绝下，与已尝试并撤销分开。最新事件决定所属分区；后续的 supersede 会将这两类事件移至重新打开，同时保留完整历史记录。人类可读的 blame 也会将明确拒绝标记为“已拒绝”。为兼容 API，JSON status 和轨迹 phase 保留现有的 reverted 负面判定类别；change_type: "reject" 用于标识拒绝。

该摘要是确定性的——没有新事件时重新生成不会产生任何差异行，因此它始终便于审查，不会变成大家习惯性跳过的噪声。标题锚点源自实体路径，因此随着内容增长，指向其中的链接仍然有效。请在提交代码的同一提交中重新生成，或通过 pre-commit hook 重新生成。

要在 hook 或 CI 中检查摘要是否过时或缺失，请使用相同的筛选条件和输出路径，并添加 --check：

selvedge export --format markdown -o .selvedge/DECISIONS.md --check

如果 UTF-8、以 LF 结尾的字节内容匹配，检查会静默退出并返回 0；如果内容过时或缺失，则会返回 1 并显示统一差异（无法读取时则显示错误）；参数无效时会返回 2。检查要求使用 Markdown 和显式文件；不接受 stdout 和其他格式。它不会重写摘要、创建或迁移数据库、更改已存储的记录，也不会启动后台更新和遥测检查。在 CI 中使用现有的已初始化存储，通过常规数据库解析方式或 SELVEDGE_DB 选择。读取时，SQLite 可能会维护其正常的 WAL 锁定文件。若要更新摘要，请在不带 --check 的情况下重新生成。

是否发布摘要或数据库均由你自行决定。提交或分享之前，请检查记录的推理和元数据中是否包含机密和私人信息；生成的差异也可能会在 CI 日志中暴露这些信息。

覆盖率检查

想知道你的 Agent 实际调用 log_change 的频率吗？可以通过两种方式检查：

# Quick summary in the terminal
selvedge stats

# Cross-reference against git commits
python scripts/coverage_check.py --since 30d

覆盖率脚本会将你的 git 日志与 Selvedge 事件进行比较，并显示哪些提交关联了变更事件。覆盖率较低通常意味着系统提示词需要加强——请参阅 docs/fallbacks.md 获取指导。

在 CI 中（GitHub Action）

同一项检查也以 Selvedge Coverage Check 复合 Action 的形式提供，因此你可以在每次推送时跟踪 Agent 的覆盖率——并可选择在覆盖率下降时让构建失败：

# .github/workflows/selvedge-coverage.yml
name: Selvedge coverage
on: [push, pull_request]
jobs:
  coverage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0            # full history so commits can be matched
      - uses: masondelan/[email protected]   # pin to a release tag (or @main for latest)
        with:
          since: 30d
          fail-under: "0.5"         # optional: fail below 50% coverage; omit to report only

该 Action 会将覆盖率摘要写入作业摘要，并将 coverage-ratio、covered 和 total 作为步骤输出提供。该 Action 会交叉比对你的 git 历史记录与 Selvedge 事件日志，因此运行器需要项目的 .selvedge/selvedge.db（提交该文件，或在此步骤之前还原它）和完整的 git 历史记录（fetch-depth: 0）。输入：since、window、limit、fail-under、selvedge-version、python-version、working-directory、db-path。

贡献

请阅读反馈与审查流程，了解如何报告问题、评估功能请求以及跟进讨论。

git clone https://github.com/masondelan/selvedge
cd selvedge
pip install -e ".[dev]"
pytest

架构详情和阶段路线图请参阅 CLAUDE.md。

许可证

MIT — 请参阅 LICENSE。

面向审查者的决策背景

共享账本和 PR 审查 Action会展示已记录的原因、被拒绝的路径、执行者／会话归属信息，以及受影响实体的完整性。匹配注入试点报告了每一次试验，并将结论限定在经过测试的合成任务范围内。