Selvedge

selvedge.sh  ·  DevHunt  ·  PyPI  ·  GitHub

AI エージェントのための、永続的な意思決定メモリです。

選んだアプローチ、その案を却下した理由、どのような変化があれば考えを改めるかを保存できます。次のコーディングセッションでは、関数、データベースのカラム、API ルート、依存関係を検索キーとして、そのコンテキストを取得できます。

Selvedge は、互換性のあるエージェントを使うすべての人を対象としています。stdio 経由のローカル MCP で接続するか、シェルにアクセスできるエージェントから CLI を使用できます。ツールを切り替えても、意思決定は .selvedge/ 内の同じ SQLite ストアに保存されます。 ホスト型アカウントは不要です。コアの保存機能と取得機能では LLM 呼び出しを行いません。

使い始める · ドキュメント · エージェントとの互換性

uv tool install --upgrade selvedge
selvedge demo

uv と Python が必要です。 Python 3.11～3.14 を推奨します。Python 3.10 も引き続き互換性がありますが、サポート終了となっています。 デモでは一時的なデータベースを使用します。エージェントを実際のプロジェクトに接続するには、クイックスタートに従ってください。

selvedge demo --mcp を使うと、ローカルの stdio MCP サーバー経由で保存し、サーバーを再起動した後に同じレコードを取得できます。確認済みの ID とバージョンを表示するには --json を追加してください。これは、破棄可能なデータを使って Selvedge を実行する Python のインストールをテストします。エージェントの設定、起動、フックについては、別途確認が必要です。

Selvedge の対象ユーザー

• 個人開発者：元の会話が失われた後に、プロジェクトに戻る方。
• チーム：記録された意思決定を、セッションやコーディングツールの間で引き継ぐ必要がある方。

課題

コードからは、選ばれたアプローチがわかります。しかし、その決定に影響した制約や、却下した代替案までは示されていない場合があります。Selvedge は、こうした説明をプロジェクト内に記録する場所と、次の編集の前にそれを取得するツールを提供します。

明示的に保存された意思決定だけを呼び出せます。保存された説明は、人またはエージェントが提供した記録であり、Selvedge はその真偽を確認せず、エージェントがそれを参照することも保証しません。セットアップをテストするには、2 つのセッションにわたって 1 つの意思決定を確認する方法をご覧ください。

v0.3.17の新機能

レビューの前に、記録された決定を確認できます。 Markdownダイジェストを生成してから、 selvedge export --format markdown -o DECISIONS.md --checkを実行すると、差分を検出できます。 同一のダイジェストの場合は何も出力せずに終了コード0を返します。古い、または存在しないダイジェストの場合は、統合差分と再生成の手順を表示して終了コード1を返します。チェックモードでは、ダイジェストと保存済みレコードは変更されません。 公開する前に、エクスポートされた理由を確認してください。

selvedge demo --mcpは、実際のローカルMCPサーバーを介して合成された却下記録を保存し、サーバーを再起動して同じレコードを取得します。破棄可能な状態を使用します。エージェントの設定やフックの有効化は検証しません。

CLIの出力では、ユーザーデータ内の角括弧がそのまま保持されるようになりました。また、blameとMarkdownエクスポートでは、却下されたアプローチと、試した後に元に戻した変更が区別されます。 このパッチではPython 3.10との互換性を維持していますが、このランタイムは現在 上流でサポートが終了しています。新規インストールには、テスト済みでサポートされているPython 3.11～3.14を使用してください。ランタイム依存関係、マイグレーション、MCPツールの追加はありません。

v0.3.16の新機能

記録された決定をコードレビューに活用できます。 selvedge ledgerでは、 各決定を記録した人と、後続のどのレコードで明示的に改訂されたかが表示されます。オプションの PRレビューActionでは、公開が承認されたベース履歴をもとに、変更対象ファイルの理由と却下された代替案が追加されます。記録者の帰属情報は自己申告です。このActionはオプトイン方式で、PRヘッドのコードを実行することはありません。

selvedge doctor --agent CLIENTは、6種類すべてのセットアップ対象について、プロジェクトのフック設定を具体的な次の手順とともに確認します。設定の確認だけでは、クライアントがフックを有効化したことは証明できません。

一致条件を統制したインジェクションの試験では、合成試行を24回実施しました。有効なままの却下済み選択が、メモリなしでは対象となる実行6回のうち4回で再発し、記録を注入した場合は0回でした。どちらの条件でも、古い記録と無関係な記録に対する対照テストに合格しました。合成タスク2件だけでは、一般的なコーディング性能や、保守されているファイルに対する優位性は立証できません。先に行われた4群間の同率結果も引き続き開示されています。ランタイム依存関係、マイグレーション、MCPツールの追加はありません。

Selvedgeの役割

1. 決定を保存します。 あなたまたはコーディングエージェントが、選択、その理由、 却下したアプローチをMCPまたはCLIを介して記録します。
2. プロジェクトと一緒に保管します。 Selvedgeは、対象となる関数、列、ルートなどのエンティティをキーとして、レコードをローカルのSQLiteに保存します。
3. 次の編集の前に呼び出します。 後続のセッションで同じストアをクエリし、 以前の制約が引き続き適用されるかどうかを確認します。

Gitはコードの履歴を保持し、レビュー用ツールは変更を確認し、オブザーバビリティはランタイムの動作を示します。Selvedgeは、決定の背景にある記録済みの理由を追加します。 仕組み · Agent Traceの相互運用

Selvedge の比較

ワークフローに合った、最もシンプルなメモリの仕組みを選んでください。

これらのアプローチは併用できます。具体的な選択基準と制限については、 ソースへのリンク付き比較 と指示と ADR と決定メモリの比較 をご覧ください。

エンティティの履歴が重要な理由。 users.email、env/STRIPE_SECRET_KEY、 api/v1/checkout、deps/stripe は、コードが移動しても有用な検索対象であり続けます。 明示的な却下記録と置き換え記録があれば、後のセッションで何が試されたのか、 当初の制約が今も適用されるのかを確認できます。

記録するタイミングが重要な理由。 コンテキストが得られるうちに理由を記録すれば、 差分には含まれない情報を保持できる場合があります。ただし、記録した理由が 必ず正しいということではありません。取得されるのは保存済みの記録です。 適用可能性を確認し、変更をテストする責任はコーディングエージェントにあります。

チェンジセットが重要な理由。 add-stripe-billing のような共通のチェンジセットで イベントにタグ付けすると、テーブル、環境変数、ルート、関数をまたいで タスクの決定事項を取得できます。

Agent Trace の相互運用。 selvedge export --format agent-trace と selvedge import --format agent-trace を使って、Agent Trace v0.1.0 の記録を 交換できます。推論とエンティティの履歴は dev.selvedge メタデータに格納されます。 マッピングと制限で形式を説明しています。 Selvedge はスキーマをベンダリングしており、アップストリームプロジェクトへの 実行時依存はありません。

クイックスタート

エージェントを接続する

uv をインストールした状態で：

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

セットアップでは、サポートされているクライアントが検出されます。プリセットを明示的に 選択するには、claude-code、codex、copilot、cursor、gemini、windsurf の いずれかを指定して --agent を使用します。複数のクライアントを指定する場合は、 フラグを繰り返してください。これらのプリセットは利便性のためのものであり、 互換性を制限するものではありません。ローカル stdio MCP に対応する別のエージェントでは、 手動セットアップに従ってください。シェルアクセスがある エージェントでは CLI を使用できます。pip を使う場合は、仮想環境で python -m pip install --upgrade selvedge を実行してください。 selvedge-server 実行ファイルがエディターの PATH 上にある必要があります。 その環境からエディターを起動するか、MCP 設定で実行ファイルの絶対パスを指定してください。

セットアップでは、ファイルを変更する前に確認を求め、既存の内容をバックアップし、 MCP とエージェント指示をインストールしてプロジェクトを初期化し、Git の post-commit フックを追加するかどうかを尋ねます。設定ファイルとライフサイクルフックは クライアントによって異なります。プリセットのパス、有効化要件、制限については、 互換性ガイドをご覧ください。

プロジェクト内でエージェントを再起動し、求められた場合は Selvedge のツールを承認してください。 クライアントのプロジェクト信頼要件にも従ってください。エージェントに次のように依頼します。

Selvedge を使って、このプロジェクトで検討し、却下した実際のアプローチを1つ記録してください。 エンティティ、理由、考えを変える条件を含めてください。決定事項を捏造しないでください。 保存されたエンティティのパスと記録 ID を表示してください。 新しいセッションを開始し、同じエンティティを検索して、決定が引き継がれていることを確認します。確認できる項目については、最初の決定の確認ガイド とエージェント間の引き継ぎガイド に従ってください。MCP アクセスによってすべての決定が自動的に記録されるわけではありません。インストールされた指示によって、エージェントがこれを使用するよう促されます。ネイティブのライフサイクルアダプターは、サポート対象のクライアントイベントに対応します。起動時の配信、編集の監視チェック、圧縮通知はハーネスによって異なります。有効にする前に、 エージェントフックガイドを確認してください。

CI のブートストラップ、または devcontainer.json の postCreateCommand には、次を使用します。

selvedge setup --non-interactive --yes

配線を確認する — 同じプロジェクト内で2つ目のターミナルを開きます。

selvedge watch

AI ツールで何か変更します。列の追加、関数名の変更、環境変数の追加などです。エージェントが log_change を呼び出してから1秒以内に、新しいイベントが selvedge watch に表示されるはずです。何も表示されない場合は、selvedge doctor を実行して、どの手順に問題があるかを知らせる単一コマンドのヘルスチェックを行います。

履歴を検索する：

selvedge status                        # recent activity + missing-commit count
selvedge diff users                    # all changes to the users table
selvedge diff users.email              # changes to a specific column
selvedge blame payments.amount         # what changed last and why
selvedge history --since 30d           # last 30 days of changes
selvedge history --since 15m           # last 15 minutes ('m' = minutes)
selvedge changeset add-stripe-billing  # all events for a feature/task
selvedge search "stripe"               # full-text search
selvedge stats                         # observed tool calls and explanation quality
selvedge import migrations/            # backfill from migration files
selvedge export --format csv           # dump history to CSV

cd your-project
selvedge init

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

selvedge prompt

selvedge install-hook

対応するエージェントで利用できます

Selvedge は特定のエージェントブランドやモデルプロバイダーを必須としません。MCP インターフェースはローカルの stdio を使用します。対応クライアントは selvedge-server を起動し、そのツールを呼び出せる必要があります。リモート HTTP のみをサポートするクライアントには、別途 stdio ブリッジが必要です。Selvedge はホスト型エンドポイントを提供しません。代わりに、シェルアクセス権を持つエージェントは selvedge log と読み取りコマンドを使用できます。

以下の連携例を参考にしてください。使用するクライアントに合ったものを選ぶか、各クライアント独自の設定形式を使って別の stdio MCP クライアントを設定してください。

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

claude mcp add selvedge -- selvedge-server

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

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

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

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

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

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

仕組み

Selvedge はローカル MCP サーバーまたは CLI として動作します。対応するエージェントは作業中にそのツールを呼び出し、構造化された変更イベントをローカルの 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 は次の機能を公開します。

CLI リファレンス

selvedge init [--path PATH]               Initialize in project
selvedge status                           Recent activity summary
selvedge diff ENTITY [--limit N]          Change history for entity
selvedge blame ENTITY                     Most recent change + context
selvedge history [--since SINCE]          Browse all history
              [--entity ENTITY]
              [--project PROJECT]
              [--changeset CS]
              [--summarize]
              [--limit N]
selvedge changeset [CHANGESET_ID]         Show events in a changeset
                  [--list]                or list all changesets
                  [--project NAME]
                  [--since SINCE]
selvedge search QUERY [--limit N]         Full-text search
selvedge prior-attempts ENTITY            Prior attempts + inferred outcome,
                       [--description T]   with the tried → reverted →
                       [--all]             re-opened trail + status line
                       [--window 7d]       (--all widens recall)
                       [--fuzzy TEXT]      add semantic matches (needs the
                                           semantic extra; substring fallback)
selvedge supersede ENTITY                 Re-open a reverted decision —
                  --reasoning TEXT         append-only, links the prior
                  [--constraint TEXT]      reverted event (or --supersedes ID)
                  [--stale-when TEXT]
                  [--supersedes ID]
selvedge index [--model NAME]             Build/update the optional semantic
              [--json]                     embeddings index (selvedge[semantic])
selvedge stale [--entity ENTITY]          Decisions due for a revisit: past
              [--project NAME]            revisit_after + still in use, or
              [--agent NAME]              stale_when matched by a later change
              [--json]                    ("review suggested")
selvedge stats [--since SINCE]            Tool call coverage report (per-tool, per-agent)
selvedge doctor [--agent CLIENT] [--json] Health check; optional project agent-hook diagnostics
selvedge install-hook [--path PATH]       Install git post-commit hook
                     [--window MIN]       (default 60 minutes)
selvedge backfill-commit --hash HASH      Backfill git_commit on recent events
                        [--window MIN]    (default 60 minutes)
selvedge import PATH                      Import migrations (SQL / Alembic) or
              [--format auto|sql|         an Agent Trace file (agent-trace)
                 alembic|agent-trace]
              [--from-git]                or walk git history for reverts:
              [--since REF|DATE]          revert-message commits + deletions
              [--project NAME]            become change_type="revert" events
              [--dry-run]                 (idempotent on commit + entity)
selvedge export [--format json|csv|       Export history (agent-trace =
                 markdown|agent-trace]      Agent Trace v0.1.0 records;
                                            markdown = reviewable digest)
              [--since SINCE]
              [--entity ENTITY]
              [--ndjson]                  agent-trace: one record per line
              [--collapse-by-session]     agent-trace: merge a session into one
              [--output FILE]
selvedge log ENTITY CHANGE_TYPE           Manually log a change
             [--diff TEXT]                CHANGE_TYPE: add, remove, modify,
             [--reasoning TEXT]           rename, retype, create, delete,
             [--agent NAME]               index_add, index_remove, migrate,
             [--commit HASH]              revert, supersede
             [--project NAME]
             [--changeset CS]
             [--revisit-after WHEN]       ISO date or offset (e.g. 90d)
             [--rename-from OLD]          OLD path when CHANGE_TYPE is 'rename'
             [--constraint TEXT]          the principle behind the decision
             [--stale-when TEXT]          what would invalidate it
             [--supersedes ID]            with CHANGE_TYPE 'supersede'
selvedge migrate-paths                    Re-canonicalize stored entity paths
                      [--apply]           (dry-run by default; --apply writes)
                      [--json]

すべての読み取りコマンドは、機械可読な出力にするための --json をサポートしています。

--since で指定する相対時間：

• 15m → 直近 15 分（m = 分）
• 24h → 直近 24 時間
• 7d → 直近 7 日間
• 5mo → 直近 5 か月（mo または mon = 月）
• 1y → 直近 1 年

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

設定

.selvedge/config.toml

すべてのキーは任意です。ファイルが存在しない場合は、以下のデフォルト値が使われます。優先順位は CLI フラグ → 環境変数 → プロジェクトの .selvedge/config.toml → グローバルの ~/.selvedge/config.toml → デフォルト値です。例外は SELVEDGE_DB で、 データベースの解決時にそのパスを使って設定ファイルを検索するため、 常に最優先されます。selvedge doctor は、各設定の有効値とその値が決まった段階を 表示します。

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

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

各キーには環境変数による上書き設定もあります（SELVEDGE_DIFF_BYTES、 SELVEDGE_RETENTION_DAYS_EVENTS、…）。

プルリクエストで記録された意図をレビューする

.selvedge/selvedge.db は SQLite ファイルなので、内部の推論は差分に表示されません。レビュー可能なコピーが必要な場合は、Markdown ダイジェストをエクスポートしてください。

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

ダイジェストはエンティティごとにまとめられ、取り消し済みおよび却下済みの決定が最初に表示されます。明示的な reject イベントは、試行後に取り消された決定とは別に、検討のうえ却下された決定の下に表示されます。最新のイベントによってセクションが決まります。後続の supersede により、どちらの種類も履歴全体を保持したまま再開に移動します。人が読める形式の blame でも、明示的な却下は「却下」として表示されます。API との互換性のため、JSON の status と履歴の phase では、否定的な判定のカテゴリとして既存の reverted が維持されます。change_type: "reject" によって却下が識別されます。

ダイジェストは決定的です。新しいイベントがなければ再生成しても差分は 0 行なので、誰もが読み飛ばすようなノイズにならず、レビュー可能な状態を保てます。見出しのアンカーはエンティティのパスから生成されるため、内容が増えてもリンクは機能し続けます。コードと同じコミットで再生成するか、pre-commit フックから再生成してください。

フックや CI で古いダイジェストや欠落したダイジェストを検出するには、同じフィルターと出力先を指定して --check を使用します。

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

UTF-8 で LF 終端のバイト列が一致する場合、チェックは何も出力せず 0 で終了します。古い、または存在しない場合は、統合差分を出力して 1 で終了します（読み取り不能の場合はエラーになります）。引数が無効な場合は 2 で終了します。Markdown と明示的なファイルの指定が必要です。標準出力やその他の形式は受け付けません。ダイジェストの書き換え、データベースの作成や移行、保存されたレコードの変更、バックグラウンドでの更新確認やテレメトリ確認の開始は行いません。CI では、通常のデータベース解決方法または SELVEDGE_DB で選択した、初期化済みの既存ストアを使用してください。読み取り中、SQLite は通常の WAL ロックファイルを維持する場合があります。ダイジェストを更新するには、--check を指定せずに再生成してください。

ダイジェストやデータベースの公開は任意です。コミットまたは共有する前に、記録された推論やメタデータに秘密情報や個人情報が含まれていないか確認してください。生成された差分から、それらの情報が CI ログに漏れることもあります。

カバレッジの確認

エージェントが実際にどのくらいの頻度で 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複合 Action としても提供されるため、プッシュのたびにエージェントのカバレッジを追跡でき、必要に応じてカバレッジが低下したときにビルドを失敗させることもできます。

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

ジョブのサマリーにカバレッジの概要を書き込み、coverage-ratio、covered、total をステップ出力として公開します。この Action は Git の履歴と Selvedge のイベントログを相互参照するため、ランナーにはプロジェクトの .selvedge/selvedge.db（コミットするか、このステップの前に復元してください）と Git の全履歴（fetch-depth: 0）が必要です。入力：since、window、limit、fail-under、selvedge-version、python-version、working-directory、db-path。

コントリビューション

問題の報告、機能リクエストの評価、議論のフォローアップについては、フィードバックとレビューのプロセスをお読みください。

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

アーキテクチャの詳細とフェーズのロードマップについては、CLAUDE.md を参照してください。

ライセンス

MIT — LICENSE を参照してください。

レビュアー向けの決定コンテキスト

共有台帳と PR レビュー Action では、記録された理由、却下された方針、変更対象エンティティに関する実行者／セッションの帰属情報と整合性を確認できます。対応付けを行ったインジェクションのパイロットでは、すべての試行を報告し、その結論をテスト済みの合成タスクに限定しています。