SuperAPI AI 工具集
合作ENAI 行业资讯收藏
全部工具AI编程工具selvedge

selvedge

Selvedge 是一款面向 AI 智能体的持久化决策记忆工具。它让使用兼容智能体的开发者或团队，把“为什么选择某个方案、拒绝了哪些替代方案、什么情况下会改变主意”这类决策理由记录下来，并在下一次编码会话中按函数、数据库列、API 路由或依赖等实体键进行检索。Selvedge 可通过本地 stdio 上的 MCP 连接，也可通过 CLI 使用；无论切换哪种工具，决策都保存在项目 .selvedge/ 目录下的同一个 SQLite 存储中，无需托管账户，核心存储与检索过程不会调用大语言模型。它记录每次结构化变更事件的内容（实体路径、变更类型、diff）、时间戳、记录者（智能体、会话 ID）、理由以及所属 Git 提交与项目。提供 ledger、doctor、watch 等命令，支持 --json 输出与相对时间查询，还支持 Agent Trace 格式的导入导出。仓库自身也使用 Selvedge 记录其开发决策历史。

访问官网

工具介绍

Selvedge 是一款为 AI 智能体提供“持久化决策记忆”的工具。它的核心目标是补上代码历史中缺失的一环：代码能展示最终选择的方案，却往往看不出塑造它的约束条件，以及当初被排除的替代方案。Selvedge 给这些解释在项目中留出位置，并提供在下次编辑前取回它们的工具。

适用对象

  • 在原始对话早已丢失后重新回到项目的独立开发者。
  • 需要在不同会话和不同编码工具之间传递已记录决策的团队。

工作原理 Selvedge 以本地 MCP 服务器或 CLI 形式运行。兼容的智能体在工作过程中调用其工具，把结构化变更事件写入本地 SQLite 数据库。每个事件记录：

  • 改了什么（实体路径、变更类型、diff）；
  • 何时（时间戳）；
  • 谁（智能体、会话 ID）；
  • 为什么（理由——在当下从智能体的上下文中捕获）；
  • 在哪里（Git 提交、项目）。 diff 是 Git 的职责，而“为什么”由 Selvedge 负责。

核心功能

  • 通过 MCP 或 CLI 保存决策：记录一个选择、理由以及被拒绝的方案。
  • 与项目一起保存：记录存于本地 SQLite，以函数、列、路由或其他相关实体为键。
  • 在下次编辑前召回：后续会话查询同一存储，检查早先的约束是否仍然适用。
  • ledger：展示每条决策由谁记录，以及后续哪条记录明确修订了它。
  • doctor：检查六个设置目标的项目钩子配置，并给出具体的下一步。
  • watch：验证接线是否正常，智能体调用 log_change 后一秒内打印新事件。
  • 查询历史：支持按实体、时间等条件检索。
  • Agent Trace 交换：selvedge export --format agent-trace 与 selvedge import --format agent-trace 可交换 Agent Trace v0.1.0 记录，理由与实体历史随 dev.selvedge 元数据一起传递。
  • 将所有读命令支持 --json 以输出机器可读结果。
  • --since 支持相对时间：15m（15 分钟）、24h（24 小时）、7d（7 天）、5mo（5 个月）。无法解析的输入会明确报错，而不是静默返回空结果；也接受 ISO 8601 时间戳并归一化为 UTC。

实体路径约定 前缀查询在所有地方都适用：查询 users 会返回 users、users.email、users.created_at 以及 users. 命名空间下的其他实体。users.email、env/STRIPE_SECRET_KEY、api/v1/checkout 和 deps/stripe 等在代码移动后仍然是有效的查询目标。

使用方式 需要 uv 和 Python 3.10+。安装方式包括：

  • 通过 uv 使用（安装命令详见官方文档）；
  • 偏好 pip 时，在虚拟环境中运行 python -m pip install --upgrade selvedge；
  • 也可在 Claude Code 中以插件形式启用，插件会通过 uvx（或 pipx）自行引导服务器，包含 MCP 服务器（8 个工具：log_change、prior_attempts、blame、diff、history、changeset、search、stale_decisions）、告知智能体何时调用它们的技能、PreToolUse 强制钩子、以及 /selvedge:status、/selvedge:blame <entity>、/selvedge:history、/selvedge:prior-attempts <entity> 等斜杠命令。 存储文件 .selvedge/selvedge.db 会在第一次记录变更时自行创建。

设置流程 设置会自动检测受支持的客户端。可用 --agent 显式选择预设：claude-code、codex、copilot、cursor、gemini 或 windsurf；重复该标志可选择多个客户端。这些预设是便利选项，而非兼容性限制。对于其他支持本地 stdio MCP 的智能体，按手动设置操作；有 shell 访问权限的智能体可使用 CLI。设置会在修改文件前询问、备份现有内容、安装 MCP 与智能体指令、初始化项目，并提供 Git post-commit 钩子。 手动四步：

  1. 在项目中初始化；
  2. 注册 MCP 服务器：配置客户端以本地 stdio MCP 服务器方式启动 selvedge-server，若不在 PATH 上则使用绝对路径，若客户端在项目外启动则用 SELVEDGE_DB 指向项目数据库；
  3. 告知智能体使用它：将规范的 agent-instructions 块（以 <!-- selvedge:start --> / <!-- selvedge:end --> 为标记）写入客户端读取的文件；
  4. 安装 post-commit 钩子。

配置 .selvedge/config.toml 中每个键都是可选的，文件缺失即使用默认值。优先级为：CLI 标志 → 环境变量 → 项目 .selvedge/config.toml → 全局 ~/.selvedge/config.toml → 默认值。SELVEDGE_DB 是唯一例外：它在数据库解析上始终优先。每个键都有对应的环境变量覆盖（如 SELVEDGE_DIFF_BYTES、SELVEDGE_RETENTION_DAYS_EVENTS 等）。selvedge doctor 会打印每个设置的有效值及产生它的步骤。

在代码评审中使用 selvedge ledger 展示每条决策的记录者以及后续明确修订它的记录。可选的 PR 评审 Action 会从已发布批准的基础历史中，为被改动文件添加理由与被拒绝的替代方案。归因是自我报告的；该 Action 为可选项，且绝不执行 PR 头部代码。

版本更新要点 v0.3.16：ledger 支持代码评审；doctor --agent CLIENT 检查全部六个目标的钩子配置；匹配注入试点完成 24 次合成试验（两项合成任务不足以确立通用编码性能或优于维护文件，早先四臂平局仍被披露）；无新增运行时依赖、迁移或 MCP 工具。 v0.3.15：为全部六个设置目标提供原生生命周期适配器（Codex、Cursor、VS Code Copilot Local、Gemini CLI、Windsurf/Cascade 以及 Claude Code）；启动上下文与受监视编辑检查在客户端支持处可用，压缩通知为建议性质，Windsurf 仅提供编辑与命令检查；保留现有配置，带备份并对定制钩子显示冲突。

限制与注意事项

  • 只有显式保存的决策才能被召回。保存的解释是个人或智能体提供的陈述，Selvedge 不验证其真实性，也不保证智能体会查阅它。
  • 应跨两个会话验证一条决策以测试设置。
  • MCP 访问不会自动捕获每条决策：安装的指令只是引导智能体使用它。
  • 原生生命周期适配器覆盖受支持的客户端事件；启动传递、受监视编辑检查与压缩通知因运行环境而异。
  • 仅支持远程 HTTP 的客户端需要单独的 stdio 桥接；Selvedge 不提供托管端点。
  • 配置检查并不证明客户端已激活其钩子（例如 selvedge doctor 的配置检查）。
  • 该工具不宣称优于维护文件或提示词中保存同样信息的方式。

Selvedge 追踪自身历史：该仓库 dogfood 了自己的工具，.selvedge/selvedge.db 被提交，因此新克隆即自带 Selvedge 自己的“为什么”历史，其中每条事件都由构建 Selvedge 的智能体通过相同的 log_change 调用记录。

同类工具

查看分类