Skip to main content
Glama
deenesjakoruzh
masondelan

Selvedge

by masondelan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

AIが書いたコードベースのための長期記憶——試して却下された経緯も含めて。

行単位の帰属（line attribution）は誰が書いたかを教えてくれます。Selvedgeはエージェントに次に書くべきでないことを教えます：このコードベースがすでに試し、リバートし、その理由まで。これはAIエージェントのためのgit blameであり、どのモデルがどの行に触れたかではなく、なぜに焦点を当てたものです——変更が起きるその瞬間に、エージェント自身によってライブで記録されるため、後続の誰も推測する必要がありません。

SelvedgeはローカルMCPサーバーです。AIコーディングエージェント（Claude Code、Cursor、Copilot）は作業中にこれを呼び出し、推論付きの構造化された変更イベントを記録します。データはコードの隣の.selvedge/にあるSQLiteファイルに保存されます。

デフォルトでローカルファースト、チームサーバーは選択制、常にゼロLLM。

6ヶ月前、あなたのAIエージェントはuser_tier_v2というカラムを追加しました。なぜ追加したのか、あなたにはわかりません。git blameは「スキーマを更新」という生成されたメッセージを持つclaude-codeからのコミットを指し示します。その変更を行ったセッションはとっくに消えています——そしてそれを生み出したプロンプトも同様です。

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には2つの対象があります。同じツール、同じpip install、.selvedge/の下の同じSQLiteファイル。ただ、痛みの規模が異なります。

長期的にAIが書いたコードベースを運用するチーム。 プロジェクトが十分に大きくなり、6ヶ月後、12ヶ月後、3年後にあなた（または他の誰か）が再び触れることになる——しかし、その大部分は、各PRが出荷された日にコンテキストが蒸発したエージェントによって書かれたもの。git blameは何が変わったかを教えます。Selvedgeはなぜを教えます——エージェントのセッションも、プロンプトテンプレートも、それを依頼した開発者も、モデルバージョンも、すべてが消え去った後でも。これが本来のユースケースです：本番コードベース、スキーマの決定、マイグレーション、離職を生き延びる監査証跡が必要な依存関係の変更。

日常のプロジェクトでClaude Codeを使う個人開発者。 サイドプロジェクト、週末のビルド、ちょこちょこ触る小さな社内ツール。エンタープライズ向けのガバナンスは必要ありません——昨日、先週、前スプリントに自分（またはエージェント）がやったことを思い出せれば十分です。selvedge initを一度実行し、CLAUDE.mdに4行追加するだけ。以降、selvedge blameは筋肉記憶になります——自分の過去の自分がLLMだったときの、その過去の自分と話す方法です。

自分がAIで作ったプロジェクトに戻ってきて「これ、何のためだったっけ？」と思ったことがあるなら、Selvedgeが欠けていたピースです。

Related MCP server: claude-engram

問題

人間が書いたコードは意図を至る所に漏らします——コミットメッセージ、PR説明、インラインコメント、その前のSlackスレッド。AIが書いたコードはそうではありません。エージェントは各決定の理由を完全に把握していますが、そのコンテキストはプロンプトの中にあり、会話が終わると蒸発します。

6ヶ月後、あなたのチームは証跡のないスキーマの決定をデバッグしています。git blameは何が変わったかといつを教えます。なぜは教えてくれません。

Selvedgeは「なぜ」を捕捉します——ライブで、エージェント自身によって、変更が行われるその瞬間に。 diffはgitの仕事です。「なぜ」はSelvedgeの仕事です。

v0.3.10の新機能

記憶がエージェントのもとへ届き、ストアに調整ダイヤルが付きます。 2つのテーマを同時にリリースしました。設定側が、残りの機能が設定を読み取るために必要だったからです。

配信。 Selvedgeはすでにリバートされたエンティティの再編集をブロックしていました。欠けていたのは、拒否（veto）するものがないときの配信です。2つの新しいフック：

  • SessionStartはセッション開始時にコンパクトなダイジェストを注入します——再訪が必要な決定、試してリバートされたエンティティ、最近のチェンジセット。

  • PreCompactはコンテキスト圧縮がこのセッションの推論を破壊する直前に発火し、編集したがログしていない監視対象エンティティを指名します。

どちらも、言うことがないときは静かで、サイズ上限付き、読み取り専用、テンプレート化されています。どちらも何もブロックできません——PreCompactはフックAPIが提供する拒否権を意図的に辞退します。これは測定された失敗モードへの回答です：2026年の2本の論文が、プル型の記憶ツールが完全に使われないままになること（事前にシードされたストアに対して114ターンでゼロの自発的記憶操作）を記録した一方、決定論的な注入は毎回成功したことを記録しました。

selvedge export --format markdown はストアをレビュー可能なダイジェストとしてレンダリングし、その隣にコミットできるようにします。捕捉された意図がバイナリの中に隠れるのではなく、プルリクエストに現れるようになります。決定論的——新しいイベントなしで再生成するとゼロ行のdiffになります。

設定。 .selvedge/config.tomlが第一級市民になり、selvedge doctorが設定ごとに表示する正規の優先順位チェーンを持ちます。含まれるもの：

  • selvedge prune --include-events — 捕捉された推論を削除できる最初のパス。そのため、確認とSELVEDGE_DESTRUCTIVE=1の両方が必要です。どちらか一方だけでは不十分です。cronエントリの--yesはプロンプトを無効化し、シェルプロファイルは環境変数を無効化するからです。イベントの保持期間はデフォルトで無期限です。

  • イベントサイズの上限（diff_bytes、reasoning_bytes）は大きな音を立てて切り詰めます——テキスト内のマーカー、書き込み時の警告、selvedge stats内のカウント。

  • シークレット形状の警告はlog_change時に行われ、redaction_patternsで拡張可能。さらに、すでに保存されているものをスキャンするdoctor行もあります。警告はしますが、拒否はしません。

その他： 5件のレビュー問題をクローズ。強制フックの許可パスは40%高速化（ゲート付き呼び出しあたり33.6ms → 20.1ms）、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がインポート時に失敗しました。このリリースは依存関係を固定します。サーバーが起動しなくなった場合、これが原因です——アップグレードしてください。

これは、コードベースに9回の独立したパスをかけ、その後にすべての所見を反証しようとしてから対処したレビューとともにリリースされます。17件の確認済み欠陥を修正。実際に気づいたであろうもの：

  • 強制フックがブロックすべきでないものをブロックしなくなりました。 追跡対象ファイルの読み取り——cat、git diff、pytest、ruff check——がブロックされ、エラーメッセージが実行するよう指示した是正策も同じゲートでブロックされていたため、CLIから抜け出す方法がありませんでした。さらに2つのパスが同じ誤ブロックを生んでいました：コメントアウトされたSQL行が実際の削除としてカウントされ、「revert」という単語を含むコミットメッセージが、触れたすべてのファイルをリバート済みとしてマークしていました。

  • ルックアップがスケールで高速化。 主要なエンティティ読み取りが全行をスキャンしていました——10万イベントで7.4ms → 0.35msと測定され、フックは大規模ストアで数秒かかっていました。

  • selvedge setupがCLAUDE.mdの一部を削除できなくなりました、中断されたバックアップが最後の正常なバックアップを破壊できなくなり、2つのSelvedgeプロセスが実行中にアップグレードしても、データベース破損のように見えるエラーでクラッシュしなくなりました。

テストは739 → 826。スキーマ変更もツールサーフェスの変更もないため、0.3.9.xを使用している人にとってはドロップインです。

Selvedgeの位置づけ

AIエージェントは作業中にSelvedgeを呼び出します。Selvedgeはなぜを耐久性のある検索可能なストアに捕捉し、それを外部に出力します——クロスツールの読み手向けのAgent Traceレコードとして、Sentry/Datadogのスタックトレースにリンクする可観測性メタデータとして、SOC 2およびEU AI Act監査のコンプライアンス成果物として。

Selvedgeはgit（行レベルの何を/いつ）、PRレビューツール（レビュー時の品質）、エージェント可観測性（LLM呼び出しトレース）、または汎用のコードホストAI機能を置き換えません。それらの間に位置します——他のすべてが参照する、来歴（provenance）を第一級市民として扱うレイヤーです。

Selvedgeの比較

「AIエージェントのためのgit blame」というカテゴリは急速に成長しています。Selvedgeがどこに当てはまるか——そして意図的に当てはまらない場所はどこか、ここに示します。

却下されたパス（Rejected paths）

推論の源泉（Reasoning source）

粒度（Granularity）

仕組み（Mechanism）

グループ化（Grouping）

保存（Storage）

Selvedge

検索可能 — prior_attempts は試行 → 差し戻し → 再オープンの履歴を返す

ライブで捕捉 — 変更を生んだのと同じコンテキストでエージェント自身が記録

エンティティ — DBカラム、テーブル、環境変数、依存、APIルート、関数

MCPサーバー — 作業の発生と同時にエージェントが呼び出す

チェンジセット — 多数のエンティティにまたがる名前付き機能/タスクのスラッグ

SQLite、依存ゼロ

OpenLore

パージされる — rejected は非アクティブなステータスであり、各決定同期の後に検索可能ストアから削除される（注釈は同期された仕様マークダウンに残る）

導出 — コード状態のtree-sitter静的解析＋コミットでゲートされた決定ノート

ASTノード（18言語＋12のIaC）

MCPサーバー — 一度きりのインデックス＋コミット時証明書

コールグラフのエッジ

.openlore/ 内のSQLiteグラフ

AgentDiff (sunilmallya)

なし

事後推論 — セッション終了時にClaude Haikuがdiffから推論

行

Claude Codeライフサイクルフック → ローカルデーモン

セッション/タスク

ディスク上のJSONL

AgentDiff (codeprakhar25)

なし

ed25519署名付きクロスエージェント来歴

行

エージェントごとのエディタフック＋gitフック（コミット時に署名）

なし

git参照内の署名付きトレース

Origin

なし — rework は事後的にAIコードを差し戻しフラグ付けるが、根拠はない

プロンプトレシート、ターンごとにライブ捕捉

行

エージェントライフサイクルフック＋git post-commitフック

なし

Git notes＋sessionsブランチ

Git AI

なし

帰属メタデータ

行

エージェント起動のチェックポイント → コミット時にGit notes

なし

Git notes

BlamePrompt

なし

プロンプトレシート — プロンプト、コスト、ツール。根拠の記載なし

行

エージェントライフサイクルフック＋post-commitフック

なし

Git notes

「却下されたパス」が重要な理由 — コピーできない唯一のもの。 高くつく失敗は、カラムがなぜ存在するかを忘れることではない。チームが正当な理由で既に廃止したものを、その理由を知る全員がコンテキストウィンドウから消えた6ヶ月後に、エージェントが自信満々に再実装することだ。上記の行帰属ツールのどれも却下されたパスを一切表面化せず、それはリリースで埋められる機能ギャップでもない — 行指向のストアには、試行 → 差し戻し → 再試行のサイクルを生き延びたエンティティという概念が存在しないからだ。docs/demos/prior-attempts.md を参照。

決定性が重要な理由。 Selvedgeの推論はエージェント自身の意図であり、変更を生んだのと同じコンテキストウィンドウから書かれる。ストレージ経路にも検索経路にもモデルは一切存在しないため、同じクエリは今日も2年後も、モデルバージョンを問わず同じ答えを返す。推論を事後的に推測するツールは、元のプロンプトを見たことのない2つ目のLLMを実行していることになる。それが生むのは言い換えであり、再実行すれば同じ変更に対して異なるカテゴリを生み出しうる。Hacker Newsのコメント者が競合アプローチについて述べたように、「'oauth-library' を却下したからといってgrepはあなたのコミットを見つけられない…決定論的な強制がない限り」（0x457）。

決定性だけではもはや差別化要因にならない — OpenLoreも決定性ネイティブであり、そう明言している。差別化する複合要因は**追加専用の証言（append-only testimony）**だ。エージェント自身が書いた推論が、却下が掃除されるべき非アクティブなステータスではなく第一級のレコードとして保持されるストアに保存されること。

「エンティティレベル」が重要な理由。 ほとんどのツールは行に帰属する。Selvedgeは実際に検索するものに帰属する：users.email、env/STRIPE_SECRET_KEY、api/v1/checkout、deps/stripe。git blame の後に最初に来る質問は通常*「このカラムの履歴は何か」であり、「users.pyの40〜48行の履歴は何か」*ではない。

「ライブで捕捉」が重要な理由。 それ自体は差別化要因ではない — ここにあるすべてのツールが何らかの形でそれを主張している — しかし、推論を信頼できるものにする仕組みなのだ。変更の瞬間に、それを生んだコンテキストから書くことこそが、経路に説明を幻覚させる2つ目のモデルが存在しない理由である。空の reasoning フィールド自体が正直なシグナルだ：エージェントには推論がなかったということ。

比較は2026-08-05時点のもの。OpenLoreはv2.1.8 / 265★、ソースに対して検証済み。訂正はissueとして歓迎します。

「チェンジセット」が重要な理由。 Stripeの請求ロールアウトは、users テーブル、2つの新しい環境変数、3つの新しいAPIルート、1つの依存関係、そしてコードベース全体の4つの関数に触れる。すべてのイベントに changeset:add-stripe-billing というタグを付ければ、後からスコープ全体を引き出せる — 元のPRが1ヶ月かけて8つの小さなPRに分割されたとしても。

Selvedge ↔ Agent Trace。 Agent Trace はCursorが公開したオープンなAIコード帰属ワイヤーフォーマットである（RFC、2026年1月）。その元のGitHubホームは2026年8月に404となり、背後にあったマルチベンダーの勢いは衰えたが、仕様とスキーマは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はスキーマをベンダー提供し、アップストリームプロジェクトへの実行時依存はない。

クイックスタート

Claude Code — プラグインをインストール（推奨）

Claude Code内で2つのコマンド。事前の pip install は不要 — プラグインは uvx（または pipx）経由でサーバー自体をブートストラップする：

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

これでエージェント向けの表面全体が1ステップで揃う：

  • MCPサーバー — 8つのツール（log_change、prior_attempts、blame、diff、history、changeset、search、stale_decisions）；

  • スキル — エージェントにいつ呼び出すべきかを伝える — 追跡対象エンティティを編集する前、実質的な変更の後；

  • PreToolUse強制フック — スキーマ/マイグレーション編集は、このセッションで prior_attempts がチェックされるまでブロックされ、ブロックメッセージに以前の推論が表示される；

  • スラッシュコマンド — /selvedge:status、/selvedge:blame <entity>、/selvedge:history、/selvedge:prior-attempts <entity>。

ストア（.selvedge/selvedge.db）は最初のログ記録変更時に自動作成される。2つのオプション機能はCLI側に留まる：各イベントにコミットハッシュを刻印するpost-commitフック（selvedge install-hook）、そして — 自分のシェルの PATH に selvedge コマンドを置きたい場合 — pip install selvedge。ランチャーは正確にピン留めされたバージョンのために uvx よりこちらを優先する。

Claude Code向けプラグインか selvedge setup か？ どちらか一方を選ぶこと。 両方ともMCPサーバーを配線する。両方実行すると二重登録になる。プラグインの方が軽量で、自己更新もする。プラグインを使っていてpost-commitのコミットハッシュ刻印だけが必要なら、単独で 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のみ — prior_attempts がチェックされるまでスキーマ/マイグレーション編集をブロック。--skip-enforcement-hook でオプトアウト可能）、selvedge init を実行し、post-commitフックをインストールする。変更されたすべてのファイルは、ディスクに到達する前に隣に .bak が書き込まれる。再実行はno-opである。

CIブートストラップや devcontainer.json の postCreateCommand 向け：

selvedge setup --non-interactive --yes

配線を検証する — 同じプロジェクトで2つ目のターミナルを開く：

selvedge watch

AIツールで何か変更を加える — カラムを追加する、関数をリネームする、環境変数を追加する。selvedge watch は、エージェントが log_change を呼び出してから1秒以内に新しいイベントを表示するはずだ。何も届かなければ、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

ウィザードを実行したくない場合、ウィザードが自動化する4つの手動ステップ：

1. プロジェクトで初期化する

cd your-project
selvedge init

2. MCPサーバーを登録する

Selvedgeは標準のstdio MCPサーバーなので、あらゆるMCPクライアントで動作する — Claude Code、Cursor、Windsurf、Codex CLI、Gemini CLIなど。クライアントごとの正確な設定は Works with any MCP client を参照。Claude Codeの場合：

claude mcp add selvedge -- selvedge-server

3. エージェントに使うよう指示する

selvedge prompt --install CLAUDE.md

--install はクライアントが読み取るプロンプトファイルを指定する — ブロック自体はクライアント間で同一である：

クライアント

プロンプトファイル

Claude Code

CLAUDE.md

Codex CLI（およびその他の AGENTS.md 対応ツール）

AGENTS.md

Cursor

.cursor/rules/selvedge.md（または旧形式の .cursorrules）

Gemini CLI

GEMINI.md

これにより、正規のエージェント指示ブロックがセンチネル括弧 （<!-- selvedge:start --> / <!-- selvedge:end -->）で囲まれてインストールされ、 将来の --install 呼び出しはファイル内の他の部分に影響を与えずに括弧で囲まれた領域だけを更新します。 またはパイプで渡すこともできます：

selvedge prompt | tee -a CLAUDE.md

コピー＆ペーストがお好みですか？同じブロックはウェブサイト上でワンクリックで入手できます： selvedge.sh/prompt-block — コピーボタンと、 エージェントがそのブロックをどう使うかについてのメモ付きです。

4. post-commit フックをインストールする

selvedge install-hook

ウィザードが実行するのと同じ4つのステップです。

あらゆる 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 の新しいスキーマでは明示的な "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 エージェントは、 作業中に Selvedge のツールを呼び出し、構造化された変更イベントをローカルの SQLite データベースに記録します。

各イベントには次の情報が記録されます：

  • 何が変わったか（エンティティパス、変更タイプ、差分）

  • いつ（タイムスタンプ）

  • 誰が（エージェント、セッション ID）

  • なぜ（推論 — その瞬間のエージェントのコンテキストから取得）

  • どこで（git コミット、プロジェクト）

差分は git の役割です。なぜは Selvedge の役割です。

Selvedge は自身の履歴を追跡する

このリポジトリは Selvedge をドッグフーディングしています：.selvedge/selvedge.db がコミットされているため、 新しいクローンには Selvedge 自身の「なぜ」の履歴が含まれています。クローンして、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 を構築したエージェントによって記録されました — この 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 は以下を公開します：

ツール

説明

log_change

エンティティ、差分、推論を含む変更イベントを記録します。rename_from + change_type="rename" は二重イベントのリネームパターンを記録します。change_type="supersede" は元に戻された決定を再オープンします（追記のみ）。オプションの constraint / stale_when により、決定の原則とその無効化条件をクエリ可能に保ちます

diff

エンティティまたはエンティティプレフィックスの履歴。各行に superseded_by の注釈が付きます

blame

正確なエンティティの最新の変更とコンテキスト、および導出された決定の status（active / reverted / reopened）

history

全エンティティにわたるフィルタリングされた履歴

changeset

名前付きフィーチャー/タスクスラッグの下にグループ化されたすべてのイベント

search

全イベントにわたる全文検索

prior_attempts

エンティティに対する以前の変更試行と推測された結果（試行 → 元に戻し → 再オープン）— 編集前に呼び出してください。オプションの fuzzy クエリは意味的に類似したレコードを追加します（semantic エクストラが必要。それ以外は部分文字列にフォールバック）

stale_decisions

再検討が必要な決定：revisit_after を過ぎてもまだアクティブに使用されているもの（flag="revisit_due"）、または stale_when 条件が後続の変更と一致したもの（flag="review_suggested"）

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 → 過去1年

解析できない入力（例：--since yesterday）は、黙って空の結果を返すのではなく、 明確なエラーで終了します。ISO 8601 タイムスタンプも受け付けられ、UTC に正規化されます。

設定

方法

形式

例

環境変数

SELVEDGE_DB=/path/to/db

セッションごとのオーバーライド

プロジェクト初期化

selvedge init

CWD に .selvedge/selvedge.db を作成

グローバルフォールバック

~/.selvedge/selvedge.db

プロジェクト DB が見つからない場合に使用

フック監視グロブ

.selvedge/config.toml

[hook]watch_globs = ["**/migrations/**", "db/**/*.sql"] — 強制フックのデフォルトのスキーマ/マイグレーショングロブを置き換えます

プロジェクト設定

.selvedge/config.toml

以下のキー一覧を参照 — 保持期間、サイズ上限、リダクションパターン

グローバル設定

~/.selvedge/config.toml

同じキー。両方で設定されている場合、プロジェクトファイルが優先されます

フックバイパス

SELVEDGE_HOOK_DISABLE=1

シェルの PreToolUse 強制フックを無効化

セマンティックエクストラ

pip install "selvedge[semantic]"

selvedge index + prior-attempts --fuzzy を有効化（ローカル model2vec 埋め込み、約30 MB。コアはこれに依存しません）

.selvedge/config.toml

すべてのキーはオプションです。ファイルがない場合は以下のデフォルトが使用されます。優先順位は CLI フラグ → 環境変数 → プロジェクト .selvedge/config.toml → グローバル ~/.selvedge/config.toml → デフォルトです。SELVEDGE_DB は唯一の例外で、 データベース解決では常に優先されます。設定ファイルはそのパスを解決することによって見つかるためです。 selvedge doctor は、すべての設定について有効な値とそれを生成したステップを出力します。

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

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

すべてのキーには環境変数によるオーバーライドもあります（SELVEDGE_DIFF_BYTES、 SELVEDGE_RETENTION_DAYS_EVENTS、…）。

プルリクエストで取得した意図をレビューする

.selvedge/selvedge.db は SQLite ファイルのため、その中の推論は差分に表示されません。 その隣に Markdown ダイジェストをエクスポートして、両方をコミットします：

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

ダイジェストはエンティティごとにグループ化され、元に戻された決定が最初に表示されます。また決定的です — 新しいイベントなしで再生成するとゼロ行の差分になるため、誰もが読み飛ばすノイズではなく、 レビュー可能な状態が保たれます。見出しアンカーはエンティティパスから導出されるため、 成長してもリンクは機能し続けます。コードと同じコミットで再生成するか、pre-commit フックから再生成します。

カバレッジチェック

エージェントが実際に log_change をどのくらいの頻度で呼び出しているか気になりませんか？確認方法は2つあります：

# 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 複合アクションとして提供されているため、 プッシュのたびにエージェントのカバレッジを追跡でき、低下した場合にビルドを失敗させることもできます：

# .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

ジョブサマリーにカバレッジサマリーを書き込み、coverage-ratio、covered、total を ステップ出力として公開します。このアクションは 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 tools
blameBlame an entityA
Read-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
NameRequiredDescriptionDefault
entity_pathYesExact entity path (no prefix matching). Examples: 'users.email', 'src/auth.py::login', 'env/STRIPE_SECRET_KEY'.

Output Schema

ParametersJSON Schema
NameRequiredDescription
idYes
diffYes
agentYes
errorYes
statusYes
projectYes
metadataYes
reasoningYes
timestampYes
constraintYes
git_commitYes
session_idYes
stale_whenYes
supersedesYes
change_typeYes
entity_pathYes
entity_typeYes
changeset_idYes
expires_whenYes
revisit_afterYes
superseded_byYes

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 changesetA
Read-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
NameRequiredDescriptionDefault
changeset_idYesThe 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
NameRequiredDescription
resultYes

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 historyA
Read-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
NameRequiredDescriptionDefault
limitNoMaximum number of events to return.
entity_pathYesEntity 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
NameRequiredDescription
resultYes

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 historyA
Read-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
NameRequiredDescriptionDefault
limitNoMaximum number of results.
sinceNoTime 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.
projectNoFilter to a specific project/repository.
entity_pathNoFilter to an entity, or a DOTTED prefix of one ('users' also covers 'users.email'). Not a raw string prefix.
changeset_idNoFilter to a specific changeset (feature/task group).

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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
NameRequiredDescriptionDefault
diffNoThe actual change — SQL migration text, code diff, or a human-readable description of what changed. Optional but strongly recommended for non-trivial changes.
agentNoName/ID of the AI agent making the change (e.g. 'claude-code', 'cursor', 'copilot', 'human').
projectNoRepository or project name. Useful when one DB tracks multiple projects.
reasoningNoWhy 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`.
constraintNoOptional: the testable principle behind the decision, kept queryable (e.g. 'card data in our own DB = PCI scope').
git_commitNoThe git commit hash this change will land in. Can be backfilled later via `selvedge backfill-commit` or the post-commit hook.
session_idNoThe agent session or conversation ID, if available.
stale_whenNoOptional: what would invalidate this decision (e.g. 'payment provider changed'). stale_decisions matches it against later events and flags 'review suggested' — surfacing only.
supersedesNoId 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_typeYesWhat 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_pathYesDot/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_typeNoCategory 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_fromNoThe 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_idNoOptional 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_whenNoOptional 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_afterNoOptional 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
NameRequiredDescription
idYes
errorYes
statusYes
warningsYes
timestampYes
supersedesYes

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 entityA
Read-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
NameRequiredDescriptionDefault
fuzzyNoOptional 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.
limitNoMaximum number of results.
descriptionNoFree-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_pathNoThe 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_confidenceNoConfidence 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_minutesNoProximity 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
NameRequiredDescription
resultYes

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.

stale_decisionsStale decisions due for revisitA
Read-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
NameRequiredDescriptionDefault
agentNoOptional filter to the agent that logged the decision.
limitNoMaximum number of results.
projectNoOptional filter to a specific project/repository.
entity_pathNoOptional filter to a single entity or path prefix — 'users' also covers 'users.email'. Empty = every entity.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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. 1 tool updatev0.3.14
    • Changedprior_attempts1 field changed
      • changedInput schema / properties / window_minutes / maximum
        Previous value: -1000New value: +10080
  2. 2 tool updates
    • Changedlog_change3 fields changed
      • changedInput schema / properties / change_type / description
        Previous 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."
      • addedInput schema / properties / expires_when
        Added 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"
+}
      • changedInput schema / properties / supersedes / description
        Previous 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."
    • Changedprior_attempts2 fields changed
      • changedInput schema / properties / min_confidence / description
        Previous 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)."
      • changedInput schema / properties / window_minutes / description
        Previous 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)."
  3. 5 tool updatesv0.3.11
    • Changeddiff2 fields changed
      • changedInput schema / properties / entity_path / description
        Previous 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'."
      • addedInput schema / properties / limit / maximum
        Added value: +1000
    • Changedhistory2 fields changed
      • changedInput schema / properties / entity_path / description
        Previous 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."
      • addedInput schema / properties / limit / maximum
        Added value: +1000
    • Changedprior_attempts2 fields changed
      • addedInput schema / properties / limit / maximum
        Added value: +1000
      • addedInput schema / properties / window_minutes / maximum
        Added value: +1000
    • Changedsearch1 field changed
      • addedInput schema / properties / limit / maximum
        Added value: +1000
    • Changedstale_decisions1 field changed
      • addedInput schema / properties / limit / maximum
        Added value: +1000
  4. 3 tool updatesv0.3.10
    • Changedblame6 fields changed
      • addedOutput schema / properties / constraint
        Added value: +{
+  "title": "Constraint",
+  "type": "string"
+}
      • addedOutput schema / properties / stale_when
        Added value: +{
+  "title": "Stale When",
+  "type": "string"
+}
      • addedOutput schema / properties / status
        Added value: +{
+  "title": "Status",
+  "type": "string"
+}
      • addedOutput schema / properties / superseded_by
        Added value: +{
+  "title": "Superseded By",
+  "type": "string"
+}
      • addedOutput schema / properties / supersedes
        Added value: +{
+  "title": "Supersedes",
+  "type": "string"
+}
      • changedOutput schema / required
        Previous 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"
+]
    • Changedlog_change6 fields changed
      • changedInput schema / properties / change_type / description
        Previous 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."
      • addedInput schema / properties / constraint
        Added 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"
+}
      • addedInput schema / properties / stale_when
        Added 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"
+}
      • addedInput schema / properties / supersedes
        Added 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"
+}
      • addedOutput schema / properties / supersedes
        Added value: +{
+  "title": "Supersedes",
+  "type": "string"
+}
      • changedOutput schema / required
        Previous value: -[
-  "id",
-  "timestamp",
-  "status",
-  "error",
-  "warnings"
-]New value: +[
+  "id",
+  "timestamp",
+  "status",
+  "error",
+  "warnings",
+  "supersedes"
+]
    • Changedprior_attempts1 field changed
      • addedInput schema / properties / fuzzy
        Added 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"
+}
  5. 4 tool updatesv0.3.8
    • Changedblame3 fields changed
      • addedOutput schema / properties / expires_when
        Added value: +{
+  "title": "Expires When",
+  "type": "string"
+}
      • addedOutput schema / properties / revisit_after
        Added value: +{
+  "title": "Revisit After",
+  "type": "string"
+}
      • changedOutput schema / required
        Previous 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"
+]
    • Changedlog_change2 fields changed
      • addedInput schema / properties / rename_from
        Added 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"
+}
      • addedInput schema / properties / revisit_after
        Added 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"
+}
    • Addedprior_attempts
    • Addedstale_decisions
  6. 6 tool updatesv0.3.2
    • Changedblame2 fields changed
      • addedInput schema / properties / entity_path / description
        Added value: +"Exact entity path (no prefix matching). Examples: 'users.email', 'src/auth.py::login', 'env/STRIPE_SECRET_KEY'."
      • changedOutput 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"
+}
    • Changedchangeset1 field changed
      • addedInput schema / properties / changeset_id / description
        Added value: +"The changeset identifier (the same slug or UUID passed to `log_change`'s changeset_id parameter). Examples: 'add-stripe-billing', 'fix-auth-redirect'."
    • Changeddiff3 fields changed
      • addedInput schema / properties / entity_path / description
        Added 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."
      • addedInput schema / properties / limit / description
        Added value: +"Maximum number of events to return."
      • addedInput schema / properties / limit / minimum
        Added value: +1
    • Changedhistory6 fields changed
      • addedInput schema / properties / changeset_id / description
        Added value: +"Filter to a specific changeset (feature/task group)."
      • addedInput schema / properties / entity_path / description
        Added value: +"Filter to a specific entity or path prefix."
      • addedInput schema / properties / limit / description
        Added value: +"Maximum number of results."
      • addedInput schema / properties / limit / minimum
        Added value: +1
      • addedInput schema / properties / project / description
        Added value: +"Filter to a specific project/repository."
      • addedInput schema / properties / since / description
        Added 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."
    • Changedlog_change11 fields changed
      • addedInput schema / properties / agent / description
        Added value: +"Name/ID of the AI agent making the change (e.g. 'claude-code', 'cursor', 'copilot', 'human')."
      • addedInput schema / properties / change_type / description
        Added 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."
      • addedInput schema / properties / changeset_id / description
        Added 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."
      • addedInput schema / properties / diff / description
        Added 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."
      • addedInput schema / properties / entity_path / description
        Added 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)."
      • addedInput schema / properties / entity_type / description
        Added 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'."
      • addedInput schema / properties / git_commit / description
        Added value: +"The git commit hash this change will land in. Can be backfilled later via `selvedge backfill-commit` or the post-commit hook."
      • addedInput schema / properties / project / description
        Added value: +"Repository or project name. Useful when one DB tracks multiple projects."
      • addedInput schema / properties / reasoning / description
        Added 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`."
      • addedInput schema / properties / session_id / description
        Added value: +"The agent session or conversation ID, if available."
      • changedOutput 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"
+}
    • Changedsearch3 fields changed
      • addedInput schema / properties / limit / description
        Added value: +"Maximum number of results."
      • addedInput schema / properties / limit / minimum
        Added value: +1
      • addedInput schema / properties / query / description
        Added 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."
  7. 6 tool updatesv0.3.1
    • First observedblame
    • First observedchangeset
    • First observeddiff
    • First observedhistory
    • First observedlog_change
    • First observedsearch
Deploy Server
Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

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

Resources

Related MCP Connectors

Related MCP Servers

  • Projectmem

    riponcm
    A
    license
    A
    quality
    A
    maintenance
    Local-first memory layer for AI coding agents — captures issues, attempts, fixes, and decisions, and warns at git commit before you repeat a mistake.
    17
    850
    MIT