Selvedge
面向 AI 编写代码库的长期记忆——包括那些已经尝试过并被否决的方案。
行级归属(line attribution)告诉你谁写了什么。Selvedge 告诉你的智能体下一步不要写什么:这个代码库已经尝试过、回退过以及为什么的方案。它是面向 AI 智能体的 git blame,关注的是为什么,而不是哪个模型碰过哪一行——由智能体在变更发生时实时捕获,这样下游任何环节都无需猜测。
Selvedge 是一个本地 MCP 服务器。AI 编码智能体(Claude Code、Cursor、Copilot)在工作时调用它来记录带有推理过程的结构化变更事件。你的数据保存在代码旁边的 .selvedge/ 目录下的 SQLite 文件中。
默认本地优先,团队服务器按需选择,始终零 LLM。
六个月前,你的 AI 智能体添加了一个名为 user_tier_v2 的列。你不知道为什么。git blame 指向一个来自 claude-code 的提交,生成的消息写着"Update schema."。做出这个变更的会话早已消失——产生它的提示词也一并消失了。
有了 Selvedge,你只需运行:
$ selvedge blame user_tier_v2
user_tier_v2
Changed 2025-10-14 09:31:02
Agent claude-code
Commit 3e7a991
Reasoning User asked to add a grandfathering flag for legacy free-tier
users during the pricing migration. Stores the original tier
so we can backfill discounts without touching billing history.这段推理过程是智能体在当下捕获的——从产生变更的同一上下文中写入 Selvedge。不是事后由第二个 LLM 从 diff 中推断出来的。也不是手打的提交消息。
Selvedge 面向谁
Selvedge 有两类受众。同一个工具,同一个 pip install,同一个 .selvedge/ 目录下的 SQLite 文件。只是痛苦的程度不同。
长期运行 AI 编码代码库的团队。
当项目大到足以让你(或其他人)在六个月、十二个月、三年后再次触碰它——但其中大部分是由一个上下文在每次 PR 合并当天就蒸发的智能体编写的。git blame 告诉你发生了什么变化。Selvedge 告诉你为什么——即使智能体会话、提示词模板、提出需求的开发者以及模型版本都早已消失。这是最初的使用场景:生产代码库、schema 决策、迁移、需要经得起人员更替的审计追踪的依赖变更。
在日常项目中使用 Claude Code 的独立开发者。
副业项目、周末构建、你不断摆弄的小型内部工具。你不需要企业级治理——你只需要记住为什么你(或你的智能体)在昨天、上周、上个迭代做了那件事。运行一次 selvedge init。在 CLAUDE.md 中添加四行。从那时起,selvedge blame 就成了肌肉记忆——一种在你过去的自己是个 LLM 时与过去的自己对话的方式。
如果你曾经回到自己用 AI 构建的项目,心想"这到底是干什么的?",Selvedge 就是你缺失的那块拼图。
Related MCP server: claude-engram
问题所在
人类编写的代码到处泄露意图——提交消息、PR 描述、行内注释、之前的 Slack 讨论串。AI 编写的代码不会。智能体对自己每个决策的原因有着完全的清晰度,但那个上下文存在于提示词中,在对话结束时便蒸发了。
六个月后,你的团队在调试一个没有任何线索的 schema 决策。git blame 告诉你什么变了、何时变的。它无法告诉你为什么。
Selvedge 捕获"为什么"——实时地,由智能体本身,在变更发生时。 diff 是 git 的工作。"为什么"是 Selvedge 的工作。
v0.3.10 的新内容
记忆主动送达智能体,存储库装上了调节旋钮。 两个主题一起发布,因为配置这一半正是其余部分读取设置所需的基础。
投递。 Selvedge 已经能阻止对已回退实体的重新编辑。缺少的是在没有需要否决的内容时的投递能力。两个新钩子:
SessionStart 在会话开始时注入一份紧凑摘要——需要重新审视的决策、已尝试并回退的实体、最近的变更集。
PreCompact 在上下文压缩销毁本会话的推理过程之前触发,并列出你编辑过但从未记录的被监视实体。
两者在无话可说时保持安静,有大小上限,只读,且基于模板。两者都不能阻止任何操作——PreCompact 刻意拒绝了钩子 API 提供给它的否决权。这是对一种已测得的失败模式的回应:2026 年的两篇论文记录了拉取式记忆工具被完全弃用(在 114 轮对话中针对预置存储库的主动记忆操作次数为零),而确定性注入每次都成功落地。
selvedge export --format markdown 将存储库渲染为可审阅的摘要,可提交到存储库旁边,这样捕获的意图会出现在拉取请求中,而不是藏在二进制文件里。确定性——在没有新事件的情况下重新生成是零行 diff。
配置。 .selvedge/config.toml 现在是一等公民,具有规范的优先级链,selvedge doctor 会按设置逐项打印。它带来了:
selvedge prune --include-events—— 第一条可以删除已捕获推理的路径,因此它需要同时有确认和SELVEDGE_DESTRUCTIVE=1。单独一个都不够,因为 cron 条目中的--yes会绕过提示,而 shell 配置文件会绕过环境变量。事件保留默认从不删除。事件大小上限(
diff_bytes、reasoning_bytes),超限时大声截断——文本中有标记,写入时有警告,selvedge stats中有计数。log_change时的秘密形态警告,可通过redaction_patterns扩展,外加一个扫描已存储内容的doctor行。只警告,绝不拒绝。
另外: 关闭了五个审查问题。强制钩子的放行路径快了 40%(每次门控调用从 33.6 ms 降至 20.1 ms),SELVEDGE_HOOK_DISABLE=1 终于在其文档声称要跳过的导入之前就短路了;log_change 在重命名和取代时不再丢弃 revisit_after / constraint / stale_when;CLI 的 --json 和 MCP 工具现在返回完全相同的结构;Docker 镜像不再附带维护者自己的数据库。测试从 826 增至 984。
v0.3.9.3 的新内容
修复了一个损坏的安装,并完成了一轮全面的代码质量检查。 mcp 2.0.0(2026-07-28 发布)移除了 mcp.server.fastmcp,而 Selvedge 声明了 mcp>=1.0.0 且没有上限——所以该日期之后任何 pip install selvedge 都会拉取 2.0.0,导致 selvedge-server 在导入时失败。此版本固定了依赖。如果你的服务器停止启动了,原因就在这里——请升级。
它同时附带了一轮审查:对代码库进行了九次独立检查,然后在处理每个发现之前试图反驳它。修复了十七个已确认的缺陷。你实际会注意到的那些:
强制钩子不再阻止它不该阻止的东西。 读取被跟踪的文件——
cat、git diff、pytest、ruff check——曾被阻止,而错误消息告诉你要运行的补救措施又被同一道门挡住,所以从 CLI 无路可走。还有两条路径导致了同样的误阻止:一行被注释掉的 SQL 被算作真正的删除,任何仅包含"revert"一词的提交消息都会将其触及的每个文件标记为已回退。查找在大规模下变快了。 主要实体读取曾扫描每一行——在 10 万事件下测得从 7.4 ms 降至 0.35 ms,而钩子在大存储库上曾需要数秒。
selvedge setup不再能删除你CLAUDE.md的部分内容,中断的备份不再能摧毁你最后一个完好的备份,在两个 Selvedge 进程同时运行时升级也不再以看起来像数据库损坏的错误崩溃。
测试从 739 增至 826。没有 schema 变更,也没有工具表面变更,所以这对任何使用 0.3.9.x 的人来说都是直接替换。
Selvedge 的定位
AI 智能体在工作时调用 Selvedge。Selvedge 将为什么捕获到持久化、可查询的存储库中,并将其输出——作为 Agent Trace 记录供跨工具读者使用,作为链接到 Sentry/Datadog 堆栈跟踪的可观测性元数据,以及作为 SOC 2 和 EU AI Act 审计的合规工件。
Selvedge 不替代 git(行级什么/何时)、PR 审查工具(审查时质量)、智能体可观测性(LLM 调用跟踪)或通用代码托管平台的 AI 功能。它位于它们之间——将来源作为一等公民的层,其他一切都会引用它。
Selvedge 的对比
"面向 AI 智能体的 git blame"这一类别正在快速增长。以下是 Selvedge 的定位——以及它刻意不涉足的地方。
被拒绝的路径 | 推理来源 | 粒度 | 机制 | 分组 | 存储 | |
Selvedge | 可查询 — | 实时捕获,由代理在产生该变更的同一上下文中记录 | 实体 — 数据库列、表、环境变量、依赖、API 路由、函数 | MCP 服务器 — 代理在变更发生时调用它 | 变更集 — 跨多个实体的命名功能/任务 slug | SQLite,零依赖 |
已清除 — | 派生 — 基于 tree-sitter 对代码状态的静态分析,加上提交门控的决策注释 | AST 节点(18 种语言 + 12 种 IaC) | MCP 服务器 — 一次性索引 + 提交时证书 | 调用图边 |
| |
无 | 事后推断,由 Claude Haiku 在会话结束时根据 diff 推断 | 行 | Claude Code 生命周期钩子 → 本地守护进程 | 会话/任务 | 磁盘上的 JSONL | |
无 | ed25519 签名的跨代理来源证明 | 行 | 每代理编辑器钩子 + git 钩子(提交时签名) | 无 | git 引用中的签名追踪 | |
无 — | 提示收据,每轮实时捕获 | 行 | 代理生命周期钩子 + git 提交后钩子 | 无 | Git notes + sessions 分支 | |
无 | 归因元数据 | 行 | 代理调用的检查点 → 提交时的 Git notes | 无 | Git notes | |
无 | 提示收据 — 提示、成本、工具;未说明理由 | 行 | 代理生命周期钩子 + 提交后钩子 | 无 | Git notes |
为什么"被拒绝的路径"很重要 — 这是无法复制的那一个。 代价高昂的
失败不是忘记某列为什么存在。而是代理在团队出于充分理由已经否决某个方案六个月后,
自信地重新实现它,而此时所有知情者都已离开上下文窗口。上述
逐行归因工具都没有呈现被拒绝的路径,而且这不是它们通过一次发布就能弥补的
功能缺口 — 面向行的存储无法表示一个在 尝试 → 回退 → 重试 周期中持续存在的实体。参见
docs/demos/prior-attempts.md。
为什么确定性很重要。 Selvedge 的推理是代理自身的意图, 由产生该变更的同一上下文窗口写出。存储或检索路径中 没有任何模型,因此相同的查询在今天和两年后、跨模型版本都会返回 相同的答案。事后推断推理的工具是在运行一个从未见过原始 提示的第二个 LLM:它产生的是转述,而重新运行可能对同一变更产生 不同的分类。正如一位 Hacker News 评论者针对一种竞争方法所说, "grep 找不到你的提交,因为你否决了 'oauth-library'… 除非有确定性的强制机制" (0x457)。
仅靠确定性已不再是区分因素 — OpenLore 也是原生确定性的, 并且也这样宣称。真正的区分因素是仅追加的证词: 代理自己写下的推理,保存在一个拒绝是头等记录 而非待清理的非活动状态的存储中。
为什么"实体级"很重要。 大多数工具归因于行。Selvedge
归因于你实际会搜索的东西:users.email、
env/STRIPE_SECRET_KEY、api/v1/checkout、deps/stripe。
git blame 之后的第一个问题通常是*"这个列的历史是什么",
而不是"users.py 第 40–48 行的历史是什么"*。
为什么"实时捕获"很重要。 单独来看并非区分因素 —
这里每个工具都声称有某种形式的实时捕获 — 但它是使推理
可信的机制。在变更发生的时刻、从产生该变更的上下文中
写入,这就是路径中没有第二个模型来幻觉出解释的原因。空的
reasoning 字段本身就是诚实的信号:代理当时没有理由。
对比截至 2026-08-05;OpenLore 为 v2.1.8 / 265★, 已对照其源码验证。欢迎通过 issue 提交更正。
为什么"变更集"很重要。 一次 Stripe 计费上线会触及 users
表、两个新环境变量、三个新 API 路由、一个依赖,以及代码库中
的四个函数。为每个事件打上 changeset:add-stripe-billing 标签,
之后就能拉回整个范围 — 即使原始 PR 在一个月内被拆成了八个更小的 PR。
Selvedge ↔ Agent Trace。 Agent Trace 是
Cursor 发布的一种开放 AI 代码归因线格式(RFC,2026 年 1 月)。其
原始 GitHub 主页在 2026 年 8 月返回 404,背后的多厂商
势头也已消退,但规范和 schema 仍在 agent-trace.dev 可访问,
冻结在 v0.1.0。自 v0.3.9 起,selvedge export --format agent-trace
输出 Agent Trace v0.1.0 记录,selvedge import --format agent-trace
可读回这些记录 — 一种可移植、有文档的文件/行 AI 归因
交换格式,推理和实体级来源信息携带在每条
记录的 dev.selvedge 元数据中。映射关系见
docs/agent-trace-interop.md;Selvedge
内置了该 schema,对上游项目没有运行时依赖。
快速开始
Claude Code — 安装插件(推荐)
两条命令,在 Claude Code 内部执行。无需事先 pip install — 插件
会通过 uvx(或 pipx)自行引导服务器:
/plugin marketplace add masondelan/selvedge
/plugin install selvedge@selvedge一步完成整个代理可见面:
MCP 服务器 — 8 个工具(
log_change、prior_attempts、blame、diff、history、changeset、search、stale_decisions);一个技能,告诉代理何时调用它们 — 在编辑受追踪实体之前、 在任何实质性变更之后;
PreToolUse 强制钩子 — schema/迁移编辑会被阻止, 直到本会话中已检查
prior_attempts,阻止消息中带有先前的推理;斜杠命令 —
/selvedge:status、/selvedge:blame <entity>、/selvedge:history、/selvedge:prior-attempts <entity>。
存储(.selvedge/selvedge.db)在首次记录变更时自动创建。
两个可选附加项保留在 CLI 侧:为每个事件盖上提交哈希的提交后钩子
(selvedge install-hook),以及 — 如果你希望 selvedge
命令出现在自己的 shell PATH 中 — pip install selvedge,启动器
会优先使用它而非 uvx,以获得精确固定的版本。
插件还是
selvedge setup(用于 Claude Code)?二选一。 两者都会 接入 MCP 服务器;同时运行会注册两次。插件是更轻量的路径, 也是会自我更新的那个。如果你使用插件且只需要 提交后提交哈希盖章,单独运行selvedge install-hook即可。
任何其他 MCP 客户端 — selvedge setup
Cursor、Copilot、Windsurf、Codex CLI、Gemini CLI 等:
pip install selvedge
cd your-project
selvedge setup就这样。selvedge setup 是一个交互式向导:它检测你已安装的
AI 工具(Claude Code、Cursor、Copilot),将 MCP 条目写入
每个工具的配置,将规范的代理指令块放入项目的
提示文件(CLAUDE.md / .cursorrules /
copilot-instructions.md),将 PreToolUse 强制钩子安装到
.claude/settings.json(仅限 Claude Code — 阻止 schema/迁移编辑,
直到已检查 prior_attempts;使用 --skip-enforcement-hook 可
选择退出),运行 selvedge init,并安装提交后钩子。每个
被修改的文件在磁盘上发生任何变更之前,旁边都会写入一个 .bak。
重复运行是空操作。
用于 CI 引导或 devcontainer.json 的 postCreateCommand:
selvedge setup --non-interactive --yes验证接线 — 在同一项目中打开第二个终端:
selvedge watch在你的 AI 工具中做任何变更 — 添加一列、重命名一个函数、添加一个
环境变量。selvedge watch 应在代理调用 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 # log_change coverage report (per-agent)
selvedge import migrations/ # backfill from migration files
selvedge export --format csv # dump history to CSV如果你不想运行向导,它自动化的四个手动步骤:
1. 在项目中初始化
cd your-project
selvedge init2. 注册 MCP 服务器
Selvedge 是一个标准的 stdio MCP 服务器,因此可与任何 MCP 客户端配合使用 — Claude Code、Cursor、Windsurf、Codex CLI、Gemini CLI 等。每个客户端的 确切配置见 [适用于任何 MCP 客户端。对于 Claude Code:
claude mcp add selvedge -- selvedge-server3. 告诉你的代理使用它
selvedge prompt --install CLAUDE.md将 --install 指向你的客户端读取的提示文件 — 该块本身
在所有客户端中都是相同的:
客户端 | 提示词文件 |
Claude Code |
|
Codex CLI(以及其他支持 |
|
Cursor |
|
Gemini CLI |
|
这会安装规范化的 agent 指令块,并用哨兵括号(<!-- selvedge:start --> / <!-- selvedge:end -->)包裹,这样以后执行 --install 时只会更新括号内的区域,不会影响文件中的其他内容。或者通过管道传入:
selvedge prompt | tee -a CLAUDE.md更喜欢复制粘贴?同样的指令块在网站上只需一次点击即可获得: selvedge.sh/prompt-block —— 带有复制按钮,以及关于你的 agent 会如何使用它的说明。
4. 安装 post-commit 钩子
selvedge install-hook这与向导运行的四个步骤完全相同。
适用于任何 MCP 客户端
Selvedge 是一个标准的 stdio MCP 服务器 —— 它的启动命令是 selvedge-server,由 pip install selvedge 放入你的 PATH。任何支持 MCP 的客户端都可以运行它。选择你的客户端:
claude mcp add selvedge -- selvedge-server或者提交一个项目级的 .mcp.json,让整个团队都能使用:
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}文档:https://code.claude.com/docs/en/mcp
.cursor/mcp.json(项目级)或 ~/.cursor/mcp.json(全局):
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}Cursor 的新版 schema 也接受显式的 "type": "stdio";仅使用 command 的形式同样有效(Cursor 会从 command 推断出 stdio)。文档:https://cursor.com/docs/mcp
~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}Windsurf 会热重载该文件 —— 无需重启。应用内的 Plugins → View raw config 按钮会打开 Cascade 实际读取的那个文件。文档:https://docs.windsurf.com/windsurf/cascade/mcp
~/.codex/config.toml:
[mcp_servers.selvedge]
command = "selvedge-server"或者运行 codex mcp add selvedge -- selvedge-server。文档:https://developers.openai.com/codex/config-reference
~/.gemini/settings.json(或按项目使用 .gemini/settings.json):
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}或者运行 gemini mcp add -s user selvedge selvedge-server。文档:https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md
大多数客户端共享相同的 JSON 结构 —— 将你的客户端指向:
{
"mcpServers": {
"selvedge": { "command": "selvedge-server" }
}
}如果找不到 selvedge-server,请使用其绝对路径(which selvedge-server)。
工作原理
Selvedge 以 MCP 服务器的方式运行。Claude Code 等工具中的 AI agent 在工作时调用 Selvedge 的工具 —— 将结构化的变更事件记录到本地 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 暴露以下工具:
工具 | 描述 |
| 记录包含实体、diff 和推理的变更事件。 |
| 某个实体或实体前缀的历史,每行都标注了 |
| 某个精确实体的最近一次变更 + 上下文,以及推导出的决策 |
| 跨所有实体的过滤历史 |
| 某个命名功能/任务 slug 下分组的所有事件 |
| 跨所有事件的全文本搜索 |
| 某个实体上之前的变更尝试 + 推断结果(尝试 → 回退 → 重新打开)—— 编辑前调用它。可选的 |
| 需要重新审视的决策:已超过 |
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 [--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 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→ 最近一年
无法解析的输入(例如 --since yesterday)会以清晰的错误信息退出,而不是静默返回空结果。也接受 ISO 8601 时间戳,并会规范化为 UTC。
配置
方法 | 格式 | 示例 |
环境变量 |
| 按会话覆盖 |
项目初始化 |
| 在当前工作目录创建 |
全局回退 |
| 如果找不到项目数据库则使用 |
钩子监视 glob |
|
|
项目设置 |
| 见下面的键列表 —— 保留期、大小上限、脱敏模式 |
全局设置 |
| 相同的键;两者都设置时项目文件优先 |
钩子绕过 |
| 为 shell 禁用 PreToolUse 强制钩子 |
语义附加包 |
| 启用 |
.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 文件,因此其中的推理不会出现在 diff 中。在其旁边导出一份 Markdown 摘要并一起提交:
selvedge export --format markdown -o .selvedge/DECISIONS.md
git add .selvedge/摘要按实体分组,回退的决策排在最前面,并且是确定性的 —— 在没有新事件的情况下重新生成会产生零行 diff,因此它始终保持可审查性,而不会变成人人都跳过的噪音。标题锚点由实体路径派生,因此随着它的增长,指向其中的链接仍然有效。在与代码相同的提交中重新生成它,或通过 pre-commit 钩子生成。
覆盖率检查
想知道你的 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/selvedge@v0.3.10 # 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它会将覆盖率摘要写入 job summary,并将 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。
Available Tools
8 toolsblameBlame an entityARead-onlyIdempotent
Most recent change to an entity — what changed, when, who, why.
Like git blame but for semantic entities (DB columns, functions, env
vars, dependencies) and AI agents. Also carries the derived decision
state: status (active / reverted / reopened) and
superseded_by (id of a later supersede overriding this change, or
""). If no history exists for the entity, returns {"error": "..."}
with protocol-level isError: false.
Inputs: entity_path (required). Returns: id, diff, agent, error, +17 more
changesetGet a changesetARead-onlyIdempotent
All events that share a changeset_id, oldest first.
Use to reconstruct the full scope of a feature or task across multiple
entities. If the changeset has no events, returns
[{"error": "..."}] so the caller can distinguish "unknown changeset"
from "empty history."
Inputs: changeset_id (required). Returns: result
diffDiff an entity's historyARead-onlyIdempotent
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
superseded_by id ("" when nothing overrode it), so the
tried → reverted → re-opened trail reads straight off the history.
Inputs: entity_path (required), limit. Returns: result
historyBrowse historyARead-onlyIdempotent
Filtered change history across all entities, newest first.
Combine since, entity_path, project, and changeset_id to scope
the result. On unparseable since input the response is
[{"error": "..."}] so the caller sees the problem.
Inputs: limit, since, project, entity_path, +1 more. Returns: result
log_changeLog a code 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 warnings
array — the event is still stored.
Renames: pass the new path in entity_path, set change_type="rename",
and pass the old path in rename_from. Selvedge then writes two events —
a rename on the old path and a create on the new path with
metadata.renamed_from set — so the entity's history follows it. Example:
log_change(
entity_path="src/auth/session.py::login", # new path
change_type="rename",
rename_from="src/auth.py::login", # old path
entity_type="function",
reasoning="Split auth.py into an auth/ package; login moved.",
)Rejections: when you consider an approach and decide against it WITHOUT
writing the change, record the verdict with change_type="reject" — the
abandoned path is a first-class event, and the next agent's
prior_attempts query finds it as a high-confidence ("exact") row
instead of re-deriving the dead end. Name what was rejected AND what was
chosen instead, and record the condition that would invalidate the
verdict. Example:
log_change(
entity_path="users.card_pan",
change_type="reject",
entity_type="column",
reasoning="Rejected storing raw card PANs on the user row — "
"went with provider tokens instead; PANs in our own "
"DB put us in PCI scope.",
stale_when="payment provider changed",
expires_when="entity:deps/stripe:changes",
)Use change_type="revert" for the sibling case — the change WAS written
and then rolled back (clearer than a plain remove).
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 change_type="supersede" and the reason. The
new event links the prior revert (auto-resolved when supersedes is
empty) and every read surface then reports the trail
tried → reverted → re-opened. Never re-apply a reverted change without
superseding it first.
On validation failure (invalid change_type, missing entity_path,
rename_from set without change_type='rename', supersedes set without
change_type='supersede', a supersede with nothing to re-open, or an
expires_when outside the closed grammar) the result is
{"status": "error", "error": "..."} with no event written.
Inputs: change_type (required), entity_path (required), diff, agent, +12 more. Returns: id, error, status, warnings, +2 more
prior_attemptsPrior attempts on an entityARead-onlyIdempotent
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 reasoning and change_type plus an
inferred outcome — so you can change your plan instead of repeating a
rejected approach.
Each result is a change event plus the trail fields: outcome
("reverted" — a later removal on the path; "reopened" — closed but a
later supersede re-opened it; "rejected" — a standalone reject event
that closed no earlier attempt, surfaced as its own row whose reasoning
IS the record; "active"), confidence ("exact" — the attempt was closed
by an explicit revert/reject, or the row is a standalone rejection;
"proximity_high" / "proximity_low" — the add->remove window heuristic
for implicit removals), outcome_reasoning (WHY it was rejected),
superseded_by + supersede_reasoning (the re-open, when present), and
current_status — the entity's standing now. Treat "reverted" and
"rejected" as "don't repeat this without a supersede"; "reopened" means
the old verdict no longer stands. Together they read: tried → reverted →
re-opened. Templated and deterministic — no LLM call; pull-only.
Conservative by design — min_confidence defaults to "proximity_high",
so an empty list (nothing clearly tried-and-rejected) is the normal,
preferred answer over a speculative false positive; "exact" rows always
clear that default floor. Pass min_confidence="proximity_low" to widen
recall. Rows carry match_type ("exact" / "substring" / "fuzzy") and
similarity.
Inputs: fuzzy, limit, description, entity_path, +2 more. Returns: result
searchSearch eventsARead-onlyIdempotent
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'.
Inputs: query (required), limit. Returns: result
stale_decisionsStale decisions due for revisitARead-onlyIdempotent
Decisions due for a revisit — expired, past their date, or with a triggered stale condition.
Three deterministic rules. Expiry-based (flag="expired"): events whose
expires_when condition fired, evaluated from local state only —
date: against now, entity:PATH:changes against the event log,
library:NAME>=VERSION against installed dist metadata; the pattern
kind that fired is in expired_pattern. A library: condition whose
dependency isn't locally observable surfaces as flag="manual_review"
instead of a guess; manual:LABEL never auto-fires. Date-based
(flag="revisit_due"): events whose revisit_after has passed AND the
entity is still live (queried via blame/diff/prior_attempts after
the decision, or its changeset saw later activity) — pure age alone
never surfaces. Condition-based (flag="review_suggested"): events
whose stale_when text shares keywords with a LATER change event — the
named invalidation evidence may have happened. Surfacing only: nothing
is un-retired automatically; follow up with a supersede if the
condition really was triggered. A later supersede that re-opens the
candidate (explicit supersedes id, or the same id-less auto-link
prior_attempts uses) drops it from this list; a same-path sibling
the supersede did not target still surfaces.
Each result is the change event plus flag, revisit_due,
days_overdue, active_use_signals, matched_terms,
matched_event_id, expires_status, expired_pattern,
expires_detail, and a one-line stale_reason. Date-due rows first,
most-overdue leading; filter by entity_path, project, or agent.
Templated and deterministic; no LLM call, no network.
Inputs: agent, limit, project, entity_path. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
One searchable history across every AI coding tool, with secret scanning and a shared task board.
Shared, scoped, reviewable team memory for AI coding agents.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Codebase intelligence for AI coding agents: graph, git history, docs, decisions, code health.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceThe shared AI context engine for git — save, search, and share the reasoning behind code changes. Captures the why behind every commit and slide on PRs for coding agents.MIT
- AlicenseBqualityBmaintenancePersistent memory and session intelligence for AI coding assistants. Auto-tracks mistakes, decisions, and context via hooks. Mines your full session history for patterns, predictions, and cross-session search.2116MIT
- AlicenseAqualityAmaintenanceLocal-first memory layer for AI coding agents — captures issues, attempts, fixes, and decisions, and warns at git commit before you repeat a mistake.19978 PyPI877MIT
- AlicenseNot gradedqualityDmaintenanceProvides a memory layer for AI coding agents with Git-powered version control, enabling automatic tracking of prompts, context, and code diffs.194MIT