A
licenseNot graded
qualityD
maintenanceThe 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.
37 npm
MIT
Selvedge
by masondelan
面向 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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| entity_path | Yes | Exact entity path (no prefix matching). Examples: 'users.email', 'src/auth.py::login', 'env/STRIPE_SECRET_KEY'. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| diff | Yes | |
| agent | Yes | |
| error | Yes | |
| status | Yes | |
| project | Yes | |
| metadata | Yes | |
| reasoning | Yes | |
| timestamp | Yes | |
| constraint | Yes | |
| git_commit | Yes | |
| session_id | Yes | |
| stale_when | Yes | |
| supersedes | Yes | |
| change_type | Yes | |
| entity_path | Yes | |
| entity_type | Yes | |
| changeset_id | Yes | |
| expires_when | Yes | |
| revisit_after | Yes | |
| superseded_by | Yes |
TDQS
A4.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate safe read-only idempotent operation. The description adds value by detailing return fields (status, superseded_by) and error handling behavior (returns error object with isError: false). No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short paragraphs, no fluff. The first sentence immediately states the core purpose. Every sentence adds necessary context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single parameter, existing output schema, and comprehensive annotations, the description covers the tool's functionality, return data, and error case fully and clearly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter with 100% schema coverage. The description adds the constraint 'exact entity path (no prefix matching)' and provides examples, enhancing the schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the most recent change to an entity, likening it to git blame for semantic entities. It distinguishes from siblings like history or diff by focusing on the latest change and including decision state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does and notes error behavior when no history exists. It lacks explicit guidance on when not to use or alternatives, but the purpose is clear enough for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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."
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| changeset_id | Yes | The changeset identifier (the same slug or UUID passed to `log_change`'s changeset_id parameter). Examples: 'add-stripe-billing', 'fix-auth-redirect'. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.3/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive. Description adds ordering (oldest first) and specific error format, going beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each with clear purpose. No wasted words. First sentence states what the tool does, second gives usage context and error handling.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-parameter tool with full schema coverage and an output schema, the description sufficiently covers ordering, error condition, and intended use. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and fully describes the changeset_id parameter. Description adds no new parameter semantics beyond what the schema provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'All events that share a changeset_id, oldest first.' It specifies the resource (events) and ordering, distinguishing it from siblings like 'history' (likely broader) and 'search' (different target).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use to reconstruct the full scope of a feature or task across multiple entities,' providing clear context. Also describes error behavior for empty changesets. Lacks explicit when-not or alternative comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of events to return. | |
| entity_path | Yes | Entity path, or a DOTTED prefix of one: 'users' also covers 'users.email'. Not a raw string prefix — 'src/' matches nothing, and 'src/auth.py' does not cover 'src/auth.py::login'. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A3.8/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context: newest-first ordering, dotted-prefix matching scope, and the derived `superseded_by` id with empty-string semantics for the latest event. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: the first sentence gives the core purpose, and the second provides high-value examples of prefix matching and derived data. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema and safety annotations, the description sufficiently covers the essential behavior: ordering, prefix semantics, and the derived superseded_by trail. It does not discuss sibling-tool selection, but the core functionality is thoroughly described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters fully (100% coverage), so the baseline is 3. The description restates prefix matching with an example but does not add new parameter-level semantics beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns change history for a codebase entity, newest first, and highlights unique behaviors like prefix matching and the derived `superseded_by` field. However, it does not explicitly differentiate from the similarly-named sibling tool `history`, so it stops short of full sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied: call this when you need a chronological change history for an entity, especially with prefix matching. But the description does not compare this tool to alternatives like `history` or `blame`, nor does it mention exclusions or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results. | |
| since | No | Time window — ISO 8601 datetime OR relative shorthand: '15m' (last 15 minutes), '24h' (last 24 hours), '7d' (last 7 days), '5mo' (last 5 months), '1y' (last year). 'm' means minutes; 'mo' or 'mon' means months. Unparseable values produce an error rather than silently returning empty results. Empty = all time. | |
| project | No | Filter to a specific project/repository. | |
| entity_path | No | Filter to an entity, or a DOTTED prefix of one ('users' also covers 'users.email'). Not a raw string prefix. | |
| changeset_id | No | Filter to a specific changeset (feature/task group). |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly=true, idempotent=true, and destructive=false, so safety is covered. The description goes beyond by disclosing the error behavior for unparseable 'since' input, returning a JSON error array instead of silently returning empty results. This is valuable behavioral context not in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states purpose and ordering, the second gives usage guidance and error handling. It is front-loaded, with no wasted words, and every sentence contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and the description covers purpose, filtering, ordering, and error behavior, the tool is fully specified for an agent. The description is complete for this 5-parameter optional-input tool without needing to explain return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for each parameter, so the baseline is 3. The description adds minor value by explicitly stating these parameters can be combined, but it does not explain syntax or semantics beyond what the schema already provides. No compensation needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Filtered change history across all entities, newest first.' It uses a specific verb ('browse' implicitly via 'history') and resource ('all entities'), and the 'newest first' ordering adds precision. This distinguishes it from siblings like log_change, diff, and search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on how to combine filter parameters ('since', 'entity_path', 'project', 'changeset_id') to scope results. It does not explicitly mention when not to use this tool or name alternatives, but the usage context is clear enough for an agent to know when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| diff | No | The actual change — SQL migration text, code diff, or a human-readable description of what changed. Optional but strongly recommended for non-trivial changes. | |
| agent | No | Name/ID of the AI agent making the change (e.g. 'claude-code', 'cursor', 'copilot', 'human'). | |
| project | No | Repository or project name. Useful when one DB tracks multiple projects. | |
| reasoning | No | Why the change was made. Include the user's original request, the problem being solved, or any context that won't be obvious from the diff alone. Good example: 'User asked to add 2FA — needs phone number to send SMS verification codes.' Avoid generic placeholders like 'user request' or 'done' — these are flagged by the quality validator and returned in `warnings`. | |
| constraint | No | Optional: the testable principle behind the decision, kept queryable (e.g. 'card data in our own DB = PCI scope'). | |
| git_commit | No | The git commit hash this change will land in. Can be backfilled later via `selvedge backfill-commit` or the post-commit hook. | |
| session_id | No | The agent session or conversation ID, if available. | |
| stale_when | No | Optional: what would invalidate this decision (e.g. 'payment provider changed'). stale_decisions matches it against later events and flags 'review suggested' — surfacing only. | |
| supersedes | No | Id of the prior event this change overrides; only valid with change_type='supersede'. Empty auto-links the entity's most recent removal event (remove/delete/index_remove/revert/reject) — so after a standalone rejection it re-opens the rejection. Append-only — the old verdict is never edited, just derived as superseded. | |
| change_type | Yes | What kind of change. One of: add, remove, modify, rename, retype, create, delete, index_add, index_remove, migrate, revert (tried and rolled back), reject (considered and decided against, without writing the change), supersede (re-open a reverted decision). Invalid values are rejected — pick the closest match. | |
| entity_path | Yes | Dot/slash-notation path to the entity. Required and non-empty. Examples: 'users.email' (DB column), 'users' (DB table), 'src/auth.py::login' (function in file), 'src/auth.py' (file), 'api/v1/users' (API route), 'deps/stripe' (dependency), 'env/STRIPE_SECRET_KEY' (env variable). | |
| entity_type | No | Category of entity. One of: column, table, file, function, class, endpoint, dependency, env_var, index, schema, config, other. Unknown values are coerced to 'other'. | other |
| rename_from | No | The entity's previous path, when this change is a rename. Set it together with change_type='rename' and put the NEW path in entity_path. Selvedge records the dual-event rename pattern: a 'rename' event on the old path and a 'create' event on the new path whose metadata.renamed_from points back to the old one, so blame/diff/prior_attempts on the new path still see the history. Leave empty for any non-rename change. | |
| changeset_id | No | Optional grouping ID for related changes that belong to the same feature or task. Use a short slug like 'add-stripe-billing'. All events sharing a changeset_id can be queried together via the `changeset` tool. | |
| expires_when | No | Optional machine-checkable expiry condition for this decision. Closed grammar, validated at write time: 'library:NAME>=VERSION' (revisit when the named dependency reaches a version, e.g. 'library:django>=5.0'), 'entity:PATH:changes' (revisit when that entity next changes, e.g. 'entity:users.email:changes'), 'date:ISO' (revisit on a date, e.g. 'date:2027-01-01'), or 'manual:LABEL' (opaque label for human review; never auto-fires). `stale_decisions` evaluates these from local state — no network, no LLM — and flags 'expired' with the pattern that fired. Values outside the grammar are rejected. | |
| revisit_after | No | Optional revisit date for an architectural decision (table, schema, dependency, config). An ISO date OR a relative offset from this event's timestamp (e.g. '90d', '6mo'). `stale_decisions` surfaces it once it passes, if the entity is still in active use. Leave empty otherwise. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| error | Yes | |
| status | Yes | |
| warnings | Yes | |
| timestamp | Yes | |
| supersedes | Yes |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations carry near-zero information (all false except openWorldHint), so the description carries the full burden. It comprehensively discloses: the warnings array on quality-validator failure, the exact error shape on validation failure, the dual-event rename behavior, supersede auto-linking, and append-only semantics. No contradiction with annotations (readOnlyHint=false correctly implies a write).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Long, but every section earns its place given the complexity — headers ('Renames:', 'Rejections:', 'Superseding a reverted decision:') with code examples make it scannable. Slightly verbose in repeating rename semantics already in the schema's rename_from field, but organized enough that the density is justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive for a 16-parameter write tool with 5 complex change_type workflows. The description covers all change types, the validation grammar, failure/error shapes, examples for each major flow, and the output schema exists. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, giving a baseline of 3, but the description adds genuine orchestration semantics beyond the schema: rename's dual-event pattern (rename on old path + create on new path with metadata.renamed_from), the reject naming requirement ('name what was rejected AND what was chosen instead'), and that empty supersedes auto-links the most recent removal event. This is behavioral glue the schemas don't spell out.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — 'Record a change to a codebase entity' — and immediately distinguishes itself: call it after a meaningful change, while siblings diff/blame/history/prior_attempts are read surfaces. An agent can clearly separate it from the sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use for each change_type: 'Call this immediately after making any meaningful change,' with dedicated workflows for rename, reject, revert, and supersede. Names why reject is preferable to re-deriving dead ends ('the next agent's prior_attempts query finds it as a high-confidence row') and why supersede beats editing history. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fuzzy | No | Optional semantic query: also return attempts on entities whose prior reasoning is similar to this text — catches renames (payment_token vs card_token). Rows are labeled match_type='fuzzy' with a similarity score; without the selvedge[semantic] extra it falls back to substring matching and says so in a leading note row. | |
| limit | No | Maximum number of results. | |
| description | No | Free-text description of what you're about to do, when you don't have an exact entity_path. Matched as a substring against prior reasoning, diffs, and entity paths. Provide this OR `entity_path` (entity_path takes precedence if both are given). | |
| entity_path | No | The entity you're about to change. Exact path with prefix matching — 'users' also covers 'users.email'. Examples: 'src/auth.py::login', 'users.email', 'env/STRIPE_SECRET_KEY'. Provide this OR `description`. | |
| min_confidence | No | Confidence floor. 'proximity_high' (default) returns the high-signal rows: attempts closed by an explicit revert/reject (confidence 'exact' — always clears this floor, including standalone rejections) plus attempts reverted within the window. Pass 'proximity_low' to also see the noisy tail (still-active changes and far-apart reverts). | proximity_high |
| window_minutes | No | Proximity window in minutes for the add->remove revert heuristic — the tiebreaker for IMPLICIT removal types only. An attempt removed within this many minutes is 'proximity_high'; beyond it, 'proximity_low'. Attempts closed by an explicit revert/reject are 'exact' regardless of the window. Default 10080 (7 days). |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.3/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior, and the description reinforces and expands this with 'Templated and deterministic — no LLM call; pull-only.' It discloses nuanced behaviors: conservative defaults, the meaning of outcome/confidence values, and that an empty list is the preferred normal answer. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but information-dense, with a sensible structure: core purpose, usage timing, outcome semantics, and confidence policy. Every sentence carries meaningful guidance, though some sections could be tightened. The front-loading is effective; the most important instruction appears early.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description covers purpose, usage timing, result semantics, confidence filtering, recall widening, and edge cases like standalone rejections and reopen events. The output schema exists and the description also explains return fields thoroughly. Nothing critical is missing for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema itself documents all parameters. The description adds meaningful extra context, such as the default min_confidence behavior, how 'exact' rows clear the confidence floor, and the role of window_minutes as a tiebreaker for implicit removals. This goes beyond simple schema repetition, though it could have been slightly more parameter-by-parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's purpose: retrieving prior change attempts on an entity with inferred outcomes. It states a specific action context ('Call this BEFORE editing an entity') and distinguishes the data it returns. However, it does not explicitly differentiate itself from siblings like 'history' or 'changeset', so an agent must infer which tool covers which kind of history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs when to use the tool: before editing an entity, to avoid repeating a rejected approach. It also explains how to widen recall via min_confidence. However, it does not say when NOT to use it or name any alternative tool, so the usage guidance is strong on 'when' but missing exclusions and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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'.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results. | |
| query | Yes | Search string (case-insensitive substring). Searches across entity_path, diff, reasoning, and agent fields. SQL LIKE wildcards (`_` and `%`) are escaped, so 'stripe_customer_id' matches the literal underscore rather than any single char. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds search semantics: full-text across four fields and substring matching with escaped wildcards (from schema). This contextualizes behavior beyond annotations, though pagination/ordering are not mentioned (but output schema covers returns).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: one declarative purpose statement and one illustrative set of examples. No redundant content and the main intent is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with two parameters, full schema coverage, output schema, and clear annotations, the description adequately conveys what it searches. The example questions help the agent map natural language to tool invocation; however, it does not mention result ordering or the limit parameter behavior (though schema covers limit).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, including the case-insensitive substring behavior and wildcard escaping. The tool description adds only usage examples, not new parameter semantics, so it meets baseline but does not exceed schema detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'search' and names the exact resources (entity paths, diffs, reasoning, agents). Example queries like 'what changes were made for the billing feature?' clarify the scope and distinguish it from sibling tools like diff or blame.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit example questions that signal appropriate use cases, such as cross-cutting search across multiple entities. It does not directly name alternatives or state when not to use this tool, but the examples imply broad search rather than targeted diffs or history queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agent | No | Optional filter to the agent that logged the decision. | |
| limit | No | Maximum number of results. | |
| project | No | Optional filter to a specific project/repository. | |
| entity_path | No | Optional filter to a single entity or path prefix — 'users' also covers 'users.email'. Empty = every entity. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.4/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even with annotations marking readOnly, deterministic, and non-destructive, the description adds substantial behavioral detail: no LLM call, no network, no automatic un-retiring, fallback to manual_review when dependency state is unobservable, and effects of later supersede events. This is far beyond what annotations alone convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average, but the tool has complex deterministic rules and edge cases that warrant the detail. It is front-loaded with the core purpose and organized by flag type, followed by output fields, ordering, and guarantees. The output field enumeration is slightly redundant with the existing output schema, preventing a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with this complexity, the description is complete: it explains all three surfacing mechanisms, non-obvious edge cases like manual_review, output shape, ordering, filtering, and determinism guarantees. Combined with the rich annotations and output schema, an agent has everything needed to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline of 3 applies. The description mentions filtering by entity_path, project, or agent, which reinforces the schema but does not add much new semantic depth. It does not describe parameter formats beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Decisions due for a revisit,' then enumerates the three deterministic rules and their resulting flags. It clearly distinguishes this tool from siblings by emphasizing it is surfacing-only, deterministic, and local-state-based.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when results surface: expiry-based, date-based, and condition-based rules, with explicit caveats like 'pure age alone never surfaces' and 'manual:LABEL never auto-fires.' It does not explicitly name sibling alternatives for exclusion, but the behavioral specificity makes intended usage unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
1 tool update
v0.3.14- Changed
prior_attempts1 field changed- changed
Input schema / properties / window_minutes / maximumPrevious value: -1000New value: +10080
2 tool updates
- Changed
log_change3 fields changed- changed
Input schema / properties / change_type / descriptionPrevious value: -"What kind of change. One of: add, remove, modify, rename, retype, create, delete, index_add, index_remove, migrate, revert (tried and rolled back), supersede (re-open a reverted decision). Invalid values are rejected — pick the closest match."New value: +"What kind of change. One of: add, remove, modify, rename, retype, create, delete, index_add, index_remove, migrate, revert (tried and rolled back), reject (considered and decided against, without writing the change), supersede (re-open a reverted decision). Invalid values are rejected — pick the closest match." - added
Input schema / properties / expires_whenAdded value: +{ + "default": "", + "description": "Optional machine-checkable expiry condition for this decision. Closed grammar, validated at write time: 'library:NAME>=VERSION' (revisit when the named dependency reaches a version, e.g. 'library:django>=5.0'), 'entity:PATH:changes' (revisit when that entity next changes, e.g. 'entity:users.email:changes'), 'date:ISO' (revisit on a date, e.g. 'date:2027-01-01'), or 'manual:LABEL' (opaque label for human review; never auto-fires). `stale_decisions` evaluates these from local state — no network, no LLM — and flags 'expired' with the pattern that fired. Values outside the grammar are rejected.", + "title": "Expires When", + "type": "string" +} - changed
Input schema / properties / supersedes / descriptionPrevious value: -"Id of the prior event this change overrides; only valid with change_type='supersede'. Empty auto-links the entity's most recent remove/delete. Append-only — the old verdict is never edited, just derived as superseded."New value: +"Id of the prior event this change overrides; only valid with change_type='supersede'. Empty auto-links the entity's most recent removal event (remove/delete/index_remove/revert/reject) — so after a standalone rejection it re-opens the rejection. Append-only — the old verdict is never edited, just derived as superseded."
- Changed
prior_attempts2 fields changed- changed
Input schema / properties / min_confidence / descriptionPrevious value: -"Confidence floor. 'proximity_high' (default) returns only attempts that were clearly tried and then reverted within the window — the high-signal 'rejected before' cases. Pass 'proximity_low' to also see the noisy tail (still-active changes and far-apart reverts)."New value: +"Confidence floor. 'proximity_high' (default) returns the high-signal rows: attempts closed by an explicit revert/reject (confidence 'exact' — always clears this floor, including standalone rejections) plus attempts reverted within the window. Pass 'proximity_low' to also see the noisy tail (still-active changes and far-apart reverts)." - changed
Input schema / properties / window_minutes / descriptionPrevious value: -"Proximity window in minutes for the add->remove revert heuristic. An attempt removed within this many minutes is 'proximity_high'; beyond it, 'proximity_low'. Default 10080 (7 days)."New value: +"Proximity window in minutes for the add->remove revert heuristic — the tiebreaker for IMPLICIT removal types only. An attempt removed within this many minutes is 'proximity_high'; beyond it, 'proximity_low'. Attempts closed by an explicit revert/reject are 'exact' regardless of the window. Default 10080 (7 days)."
5 tool updates
v0.3.11- Changed
diff2 fields changed- changed
Input schema / properties / entity_path / descriptionPrevious value: -"Entity path or path prefix. Prefix matching is supported: 'users' returns history for the users table AND all its columns ('users.email', 'users.created_at', etc.). Use a more specific path to narrow the result."New value: +"Entity path, or a DOTTED prefix of one: 'users' also covers 'users.email'. Not a raw string prefix — 'src/' matches nothing, and 'src/auth.py' does not cover 'src/auth.py::login'." - added
Input schema / properties / limit / maximumAdded value: +1000
- Changed
history2 fields changed- changed
Input schema / properties / entity_path / descriptionPrevious value: -"Filter to a specific entity or path prefix."New value: +"Filter to an entity, or a DOTTED prefix of one ('users' also covers 'users.email'). Not a raw string prefix." - added
Input schema / properties / limit / maximumAdded value: +1000
- Changed
prior_attempts2 fields changed- added
Input schema / properties / limit / maximumAdded value: +1000 - added
Input schema / properties / window_minutes / maximumAdded value: +1000
- Changed
search1 field changed- added
Input schema / properties / limit / maximumAdded value: +1000
- Changed
stale_decisions1 field changed- added
Input schema / properties / limit / maximumAdded value: +1000
3 tool updates
v0.3.10- Changed
blame6 fields changed- added
Output schema / properties / constraintAdded value: +{ + "title": "Constraint", + "type": "string" +} - added
Output schema / properties / stale_whenAdded value: +{ + "title": "Stale When", + "type": "string" +} - added
Output schema / properties / statusAdded value: +{ + "title": "Status", + "type": "string" +} - added
Output schema / properties / superseded_byAdded value: +{ + "title": "Superseded By", + "type": "string" +} - added
Output schema / properties / supersedesAdded value: +{ + "title": "Supersedes", + "type": "string" +} - changed
Output schema / requiredPrevious value: -[ - "id", - "timestamp", - "entity_type", - "entity_path", - "change_type", - "diff", - "reasoning", - "agent", - "session_id", - "git_commit", - "project", - "changeset_id", - "metadata", - "revisit_after", - "expires_when", - "error" -]New value: +[ + "id", + "timestamp", + "entity_type", + "entity_path", + "change_type", + "diff", + "reasoning", + "agent", + "session_id", + "git_commit", + "project", + "changeset_id", + "metadata", + "revisit_after", + "expires_when", + "supersedes", + "constraint", + "stale_when", + "superseded_by", + "status", + "error" +]
- Changed
log_change6 fields changed- changed
Input schema / properties / change_type / descriptionPrevious value: -"What kind of change. One of: add, remove, modify, rename, retype, create, delete, index_add, index_remove, migrate. Invalid values are rejected — pick the closest match."New value: +"What kind of change. One of: add, remove, modify, rename, retype, create, delete, index_add, index_remove, migrate, revert (tried and rolled back), supersede (re-open a reverted decision). Invalid values are rejected — pick the closest match." - added
Input schema / properties / constraintAdded value: +{ + "default": "", + "description": "Optional: the testable principle behind the decision, kept queryable (e.g. 'card data in our own DB = PCI scope').", + "title": "Constraint", + "type": "string" +} - added
Input schema / properties / stale_whenAdded value: +{ + "default": "", + "description": "Optional: what would invalidate this decision (e.g. 'payment provider changed'). stale_decisions matches it against later events and flags 'review suggested' — surfacing only.", + "title": "Stale When", + "type": "string" +} - added
Input schema / properties / supersedesAdded value: +{ + "default": "", + "description": "Id of the prior event this change overrides; only valid with change_type='supersede'. Empty auto-links the entity's most recent remove/delete. Append-only — the old verdict is never edited, just derived as superseded.", + "title": "Supersedes", + "type": "string" +} - added
Output schema / properties / supersedesAdded value: +{ + "title": "Supersedes", + "type": "string" +} - changed
Output schema / requiredPrevious value: -[ - "id", - "timestamp", - "status", - "error", - "warnings" -]New value: +[ + "id", + "timestamp", + "status", + "error", + "warnings", + "supersedes" +]
- Changed
prior_attempts1 field changed- added
Input schema / properties / fuzzyAdded value: +{ + "default": "", + "description": "Optional semantic query: also return attempts on entities whose prior reasoning is similar to this text — catches renames (payment_token vs card_token). Rows are labeled match_type='fuzzy' with a similarity score; without the selvedge[semantic] extra it falls back to substring matching and says so in a leading note row.", + "title": "Fuzzy", + "type": "string" +}
4 tool updates
v0.3.8- Changed
blame3 fields changed- added
Output schema / properties / expires_whenAdded value: +{ + "title": "Expires When", + "type": "string" +} - added
Output schema / properties / revisit_afterAdded value: +{ + "title": "Revisit After", + "type": "string" +} - changed
Output schema / requiredPrevious value: -[ - "id", - "timestamp", - "entity_type", - "entity_path", - "change_type", - "diff", - "reasoning", - "agent", - "session_id", - "git_commit", - "project", - "changeset_id", - "metadata", - "error" -]New value: +[ + "id", + "timestamp", + "entity_type", + "entity_path", + "change_type", + "diff", + "reasoning", + "agent", + "session_id", + "git_commit", + "project", + "changeset_id", + "metadata", + "revisit_after", + "expires_when", + "error" +]
- Changed
log_change2 fields changed- added
Input schema / properties / rename_fromAdded value: +{ + "default": "", + "description": "The entity's previous path, when this change is a rename. Set it together with change_type='rename' and put the NEW path in entity_path. Selvedge records the dual-event rename pattern: a 'rename' event on the old path and a 'create' event on the new path whose metadata.renamed_from points back to the old one, so blame/diff/prior_attempts on the new path still see the history. Leave empty for any non-rename change.", + "title": "Rename From", + "type": "string" +} - added
Input schema / properties / revisit_afterAdded value: +{ + "default": "", + "description": "Optional revisit date for an architectural decision (table, schema, dependency, config). An ISO date OR a relative offset from this event's timestamp (e.g. '90d', '6mo'). `stale_decisions` surfaces it once it passes, if the entity is still in active use. Leave empty otherwise.", + "title": "Revisit After", + "type": "string" +}
- Added
prior_attempts - Added
stale_decisions
6 tool updates
v0.3.2- Changed
blame2 fields changed- added
Input schema / properties / entity_path / descriptionAdded value: +"Exact entity path (no prefix matching). Examples: 'users.email', 'src/auth.py::login', 'env/STRIPE_SECRET_KEY'." - changed
Output schema / (root)Previous value: -nullNew value: +{ + "properties": { + "agent": { + "title": "Agent", + "type": "string" + }, + "change_type": { + "title": "Change Type", + "type": "string" + }, + "changeset_id": { + "title": "Changeset Id", + "type": "string" + }, + "diff": { + "title": "Diff", + "type": "string" + }, + "entity_path": { + "title": "Entity Path", + "type": "string" + }, + "entity_type": { + "title": "Entity Type", + "type": "string" + }, + "error": { + "title": "Error", + "type": "string" + }, + "git_commit": { + "title": "Git Commit", + "type": "string" + }, + "id": { + "title": "Id", + "type": "string" + }, + "metadata": { + "additionalProperties": true, + "title": "Metadata", + "type": "object" + }, + "project": { + "title": "Project", + "type": "string" + }, + "reasoning": { + "title": "Reasoning", + "type": "string" + }, + "session_id": { + "title": "Session Id", + "type": "string" + }, + "timestamp": { + "title": "Timestamp", + "type": "string" + } + }, + "required": [ + "id", + "timestamp", + "entity_type", + "entity_path", + "change_type", + "diff", + "reasoning", + "agent", + "session_id", + "git_commit", + "project", + "changeset_id", + "metadata", + "error" + ], + "title": "BlameResult", + "type": "object" +}
- Changed
changeset1 field changed- added
Input schema / properties / changeset_id / descriptionAdded value: +"The changeset identifier (the same slug or UUID passed to `log_change`'s changeset_id parameter). Examples: 'add-stripe-billing', 'fix-auth-redirect'."
- Changed
diff3 fields changed- added
Input schema / properties / entity_path / descriptionAdded value: +"Entity path or path prefix. Prefix matching is supported: 'users' returns history for the users table AND all its columns ('users.email', 'users.created_at', etc.). Use a more specific path to narrow the result." - added
Input schema / properties / limit / descriptionAdded value: +"Maximum number of events to return." - added
Input schema / properties / limit / minimumAdded value: +1
- Changed
history6 fields changed- added
Input schema / properties / changeset_id / descriptionAdded value: +"Filter to a specific changeset (feature/task group)." - added
Input schema / properties / entity_path / descriptionAdded value: +"Filter to a specific entity or path prefix." - added
Input schema / properties / limit / descriptionAdded value: +"Maximum number of results." - added
Input schema / properties / limit / minimumAdded value: +1 - added
Input schema / properties / project / descriptionAdded value: +"Filter to a specific project/repository." - added
Input schema / properties / since / descriptionAdded value: +"Time window — ISO 8601 datetime OR relative shorthand: '15m' (last 15 minutes), '24h' (last 24 hours), '7d' (last 7 days), '5mo' (last 5 months), '1y' (last year). 'm' means minutes; 'mo' or 'mon' means months. Unparseable values produce an error rather than silently returning empty results. Empty = all time."
- Changed
log_change11 fields changed- added
Input schema / properties / agent / descriptionAdded value: +"Name/ID of the AI agent making the change (e.g. 'claude-code', 'cursor', 'copilot', 'human')." - added
Input schema / properties / change_type / descriptionAdded value: +"What kind of change. One of: add, remove, modify, rename, retype, create, delete, index_add, index_remove, migrate. Invalid values are rejected — pick the closest match." - added
Input schema / properties / changeset_id / descriptionAdded value: +"Optional grouping ID for related changes that belong to the same feature or task. Use a short slug like 'add-stripe-billing'. All events sharing a changeset_id can be queried together via the `changeset` tool." - added
Input schema / properties / diff / descriptionAdded value: +"The actual change — SQL migration text, code diff, or a human-readable description of what changed. Optional but strongly recommended for non-trivial changes." - added
Input schema / properties / entity_path / descriptionAdded value: +"Dot/slash-notation path to the entity. Required and non-empty. Examples: 'users.email' (DB column), 'users' (DB table), 'src/auth.py::login' (function in file), 'src/auth.py' (file), 'api/v1/users' (API route), 'deps/stripe' (dependency), 'env/STRIPE_SECRET_KEY' (env variable)." - added
Input schema / properties / entity_type / descriptionAdded value: +"Category of entity. One of: column, table, file, function, class, endpoint, dependency, env_var, index, schema, config, other. Unknown values are coerced to 'other'." - added
Input schema / properties / git_commit / descriptionAdded value: +"The git commit hash this change will land in. Can be backfilled later via `selvedge backfill-commit` or the post-commit hook." - added
Input schema / properties / project / descriptionAdded value: +"Repository or project name. Useful when one DB tracks multiple projects." - added
Input schema / properties / reasoning / descriptionAdded value: +"Why the change was made. Include the user's original request, the problem being solved, or any context that won't be obvious from the diff alone. Good example: 'User asked to add 2FA — needs phone number to send SMS verification codes.' Avoid generic placeholders like 'user request' or 'done' — these are flagged by the quality validator and returned in `warnings`." - added
Input schema / properties / session_id / descriptionAdded value: +"The agent session or conversation ID, if available." - changed
Output schema / (root)Previous value: -nullNew value: +{ + "properties": { + "error": { + "title": "Error", + "type": "string" + }, + "id": { + "title": "Id", + "type": "string" + }, + "status": { + "title": "Status", + "type": "string" + }, + "timestamp": { + "title": "Timestamp", + "type": "string" + }, + "warnings": { + "items": { + "type": "string" + }, + "title": "Warnings", + "type": "array" + } + }, + "required": [ + "id", + "timestamp", + "status", + "error", + "warnings" + ], + "title": "LogChangeResult", + "type": "object" +}
- Changed
search3 fields changed- added
Input schema / properties / limit / descriptionAdded value: +"Maximum number of results." - added
Input schema / properties / limit / minimumAdded value: +1 - added
Input schema / properties / query / descriptionAdded value: +"Search string (case-insensitive substring). Searches across entity_path, diff, reasoning, and agent fields. SQL LIKE wildcards (`_` and `%`) are escaped, so 'stripe_customer_id' matches the literal underscore rather than any single char."
6 tool updates
v0.3.1- First observed
blame - First observed
changeset - First observed
diff - First observed
history - First observed
log_change - First observed
search
TDQS
A4.2/5.0
Scored across 8 tools
Disambiguation4/5
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.'
Naming Consistency3/5
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.
Tool Count5/5
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.
Completeness5/5
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
ActivityActive
ResponsivenessResponsive
Related MCP Connectors
One searchable history across every AI coding tool, with secret scanning and a shared task board.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Codebase graphs, caller impact analysis, and recorded project context for AI coding agents.
Related MCP Servers
- 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.17850MIT
- AlicenseNot gradedqualityCmaintenanceProvides a memory layer for AI coding agents with Git-powered version control, enabling automatic tracking of prompts, context, and code diffs.194MIT
