rutter

rutter

AI エージェントのためのパーソナルメモリレイヤーです。メモリはひとつ。エージェントは複数。あなたのものです。

モデルがメモリなのではありません。あなたのノートがメモリです。 rutter は、過去の決定と、AI セッションが参照したノートを呼び出します。記録はモデルやベンダーのアカウント内ではなく、あなた自身のノートフォルダー内にある（ノートと並んだ _librarian/ フォルダー内の）プレーンな Markdown です。

これは、そのフォルダーを対象とする MCP（Model Context Protocol）サーバーです。セッションで何かを決めると、クライアントがその内容を一行残します。フック（各ターンの後にクライアントが実行するスクリプト）が、文体を書き換えることなくその行を保存します。保存先はノートフォルダー内の日付付きファイルで、参照した各ノートのパスとコンテンツハッシュ（ノートの内容を示すフィンガープリント）も記録します。

数週間後、設定済みの同じ AI ツール、または別の AI ツールで結論を尋ねると、日付とノートとともにその一行が返ってきます。編集されずに名前だけ変更されたノートは、ハッシュを使って追跡されます。rutter が場所を特定できない参照は、破棄されず未解決として表示されます。内容が変更されたノートは、まだフラグ付けされません。

Markdown のノートを使っていて、AI クライアントの設定に慣れている人に向いています。docs/getting-started.mdから始めてください。Claude Code のユーザーは、数分でプラグインをインストールできます。それ以外の方は npm からインストールしてください。パッケージ名はrutter-memoryです（rutterという名前は、無関係なライブラリが使用しています）。

内部にモデルはありません。コードとストレージだけなので、推論はクライアント側で行われます。

名前の由来は大航海時代です。rutter とは、地図に対して、実際に航海した航路を記した航海日誌のことでした。地図には、知られていることが記録されます。rutter には、それに対して何をしたかが記録されます。

個人用ツールであり、リファレンス実装として公開されています。サポート対象の製品ではありません。 ひとりのワークフローのために作られ、その仕組みが役立つかもしれないと考えて共有されています。ロードマップの約束も、サポートの義務も、次のコミットで依存している部分が変わらない保証もありません。フォークして、アイデアを活用し、よければ issue を登録してください。ただし、このツールに重要なものを依存させないでください。

AI ツール間で共有する一つのメモリー

rutter は Claude Code、Grok、Codex、Copilot CLI、Antigravity、Muse Code 向けの記録を一元管理します。各クライアントはセッションの要約を同じノートフォルダーに書き込みます。各クライアントは同じ MCP サーバーを通じて、その内容を読み取ります。

火曜日に Codex で決めたことは、Codex がその内容を書き残し、フックが実行されていれば、木曜日に Claude Code で尋ねたときにも確認できます。クライアント間で何かをコピーする必要はありません。メモリーが特定のツールの機能ではなく、自分で所有する Markdown ファイルのフォルダーだからです。

使用するもの	手順	必要なもの
Claude Code	Claude Code の最短手順	数分。クローンは不要
Grok	Grok の手順	npm install を 1 回、フック、grok mcp add を 1 回
Codex	Codex の手順	npm install を 1 回、信頼できるフック
GitHub Copilot CLI	Copilot CLI の手順	npm install を 1 回、フック、指示ファイル
Antigravity CLI (agy)	Antigravity の手順	npm install を 1 回、フック、ルールファイル
Muse Code (muse)	Muse Code の手順	npm install を 1 回、インストーラーの実行を 1 回
その他の MCP（Model Context Protocol）クライアント	npx で読み取りのみ	設定を 1 つ追加。検索と読み取りのみ。フックがないと何も記録されません
クローンからの Claude Code	ソースからの手順	手書きの記録から始める 8 つの手順（M1 から M8）。コントリビューター向け

Grok は Linux でのみ動作確認済みです（既知の問題）。npm のみを使う手順（Codex、Copilot CLI、Antigravity、Muse Code）は、Claude Code もインストールされたマシンでテストされているため、クリーンなマシンでは未検証です。既知の問題をご覧ください。

MCP サーバーを登録すれば、どのクライアントもメモリーを読み取れます。書き込みには各ターンの後に実行されるフックが必要で、この 6 つのクライアントにはそれがあります。その他の MCP クライアントは、サーバーを npx で実行することで読み取りのみ可能です（npx で読み取りのみ）。Antigravity の項目は Antigravity IDE ではなく、agy コマンドラインツールを対象としています。

すべてのクライアントに同じノートフォルダーを指定してください。指定方法はクライアントごとに異なります。Claude Code プラグインはインストール時にフォルダーを尋ねます。Grok、Codex、Copilot CLI は、起動元のシェルから LIBRARIAN_VAULT_PATH を読み取ります。Antigravity と Muse Code のインストーラーには --vault を指定します。フックで判別できる場合は、各記録にどのクライアントが書き込んだかが記録されます（「既知の制限事項」をご覧ください）。

既存のメモリとの違い

お使いのハーネスでも、何らかの形ですでにこれを行っているはずです。Claude Code はセッションの要約を書き、メモリフォルダーに好みを推測して記録し、時間の経過とともに整理します。重複を統合し、古くなったように見えるものを削除します。

整理するのは妥当な既定の動作です。しかし、これはこの仕組みとは正反対です。

ここでは、保存済みの行が書き換えられることはありません。記録は追記のみで、読み込む際にセッションごとにまとめられます。また、行を追加する際に文体を整えるための書き換えは行わず、1行単位の正規化と2,000文字での切り詰めだけが適用されます。

より重要なのは、2つ目の違いです。要約だけでは記録ではなく、主張にすぎません。要約に、そこで参照したメモのバージョン管理された状態を添えることで、比較に使える指紋が得られ、記録となります。

近接する手法も、それぞれこの2つ目の要素の一部を実現しています。アーキテクチャ決定記録は「何を」と「なぜ」を記録しますが、適用対象となったバージョンまでは固定しません。イベントソーシング形式のログはイベントにタイムスタンプを付けますが、ファイル単位の来歴を含むことはほとんどありません。サプライチェーンの来歴情報形式はコンテンツを適切にハッシュ化しますが、次の作業セッションではなく監査人向けに作られています。そのため、決定はそれを生み出したコードからひそかにずれていき、それを知らせるものもありません。

ここでは、各参照に、その行を記録した時点でのメモのコンテンツハッシュが含まれます。名前が変更されたメモもハッシュの完全一致によって追跡され、場所を特定できないメモは黙って削除されるのではなく、未解決として表示されます。保存されたハッシュを使えば、ファイルと当時の状態を比較することもできます。変更されたメモを報告する機能は、まだ実装されていません。

設計上、さらに2つの小さな利点があります。ストアはあなたのものです。ベンダーのアカウントやツール専用のプライベートフォルダーではなく、自分のノートディレクトリにあるMarkdownなので、移植でき、grepで検索でき、Gitにコミットでき、このプロジェクトがなくなっても読み取れます。また、そのおかげで、使用するどのクライアントからも同じ記録を読み書きできます。さらに、コンテキストがまだ読み込まれている間にクライアントが要約を書き込むため、記録に2回目のモデル呼び出しもネットワーク呼び出しも必要ありません。その 代わり、品質は「サーバーがクライアントに伝えること」で説明されているスタイル規約を、クライアントが遵守するかどうかに左右されます。

この仕組みは、情報検索で競うものではありません。適切に整理されたノートディレクトリを読める優秀なエージェントなら、すでに十分な検索ができます。これは、一時的なセッションにはできないこと、つまり時間をまたいだ記憶のために存在します。

現在できること

• ノートディレクトリをローカルの SQLite FTS5 全文インデックスに登録します。これは破棄して再生成できるキャッシュです。ファイルが信頼できる情報源であることに変わりはありません。
• アンビエントキャプチャ。 セッションで何かが決定されたり、作成されたりすると、クライアントがその内容を1行に記録します。Claude Code、Grok、Codex、Copilot CLI、Antigravity、Muse Code の Stop フックがその行を <notes>/_librarian/sessions/<date>.md に追記し、変更したノートをコンテンツハッシュで参照します。クライアントには、セッションごとに1行ではなく、個別に分けられる成果ごとに1行記録するよう求めます。通常の作業セッションでは3～4行になり、それを読むときには、そのセッションについての1つの記録としてまとめられます。同じセッションで記録済みの行はスキップされます（厳密なルールはdocs/memory-of-use.mdに記載されています）。永続的で、Git にコミットでき、クライアントによって書き込まれます。
• その行のスタイル規約。 セッションに参加していなかった、忙しい賢明な読者に向けて書いてください。まず成果を述べ、セッション内だけで通じる略記より一般的な言葉を使い、架空のコードネームやバージョンタグは使わず、約40語にまとめます。この規約はサーバーの MCP 指示に含まれています。サーバーはスタイルを整えるために要約を書き換えません。文字数の上限を超えた要約はキャプチャ時に報告され、そのまま編集せずに保存されます。ただし、各行を1行に正規化（制御文字を削除し、空白をまとめる）し、2,000文字を超える部分は切り詰めます。スタイル規約を参照してください。
• ワークスペースの由来情報。 各エントリには、セッションの作業ディレクトリ、そこから導出されたプロジェクト名、Git リモート URL がある場合はその URL が記録されるため、1日に3つの作業をしても内容をすっきり把握できます。設定は不要です。解決処理はローカルファイルの読み取りだけで行われ、git を実行したり、リモートに接続したりすることはありません。
• 読み取り専用の MCP ツールが4つあります。
  • librarian-search — ランク付けされた全文検索です。各結果には、パス、type／status／created の由来情報、一致箇所のスニペットが含まれます。複数語のクエリは AND 検索されるため、「blue man group」では、いずれかの語を含むノートではなく、3語すべてを含むノートが見つかります。以前に確認したことのある結果には、控えめな過去の確認に関する注記も追加されます。これは順位付けには影響しません。
  • librarian-get-note — パスを指定して、1つのノートの全文を取得します。
  • librarian-recent — 「最近、何に取り組んでいましたか？」 セッションを新しい順に、日付、プロジェクト、由来情報とともに表示します。任意で project による絞り込み、日数単位の window、または count を指定できます。
  • librarian-positions — 「Xについてどう考えていて、考えは変わりましたか？」 次の3通りでクエリできます。topic はトピックキーを完全一致で指定し、回答を1つ返すか、見つからなかったことを明示します。query は記録済みの立場を自由テキストで検索します。note はパスで指定したノートを参照する立場を検索します。各回答には、トピックの現在の立場と、それが形成された日付、最後に改訂された日付が含まれます。変更の履歴全体を取得するには chain: true を追加します。
• サーバーとともに提供される指示。 接続されたクライアントには、最近の出来事に関する質問では librarian-recent を、「これを見たことがあるか」という質問では librarian-search を使ってから直接ファイルを読むよう指示されます。また、記憶した要約は平易な言葉で報告するよう指示されます。これには、規約の導入前に書かれたエントリも含まれます。内容が密集した古い記録を明快に読めるようにする唯一の方法だからです。プロジェクトごとのクライアント設定は不要です。
• 自身の利用状況を記録します。 ステートフルな動作がどのくらい利用されたかを、ISO 週ごとにローカルで集計します。
• 立場のキャプチャ (意思決定グラフ Phase A)。クライアントがあるトピックについて立場を形成、変更、再確認、または撤回すると、より頻度の低い別種の行である立場ディレクティブを <notes>/_librarian/positions/<YYYY-MM>.md に追記します。これはセッション記録とは完全に別の追記専用ストリームです。ディレクティブの種別（assert、revise、reaffirm、retire）によってイベントの動作が決まります。立場の文章は分類されず、読み取られるのはその中の2つの文字列だけです。[[wikilink]] はバージョン管理された参照になり、revises: <event-id> は置き換えるイベントを記録します。どちらも保存テキストから削除されません。スタイル調整のために書き換えられることはなく、異なるディレクティブごとに冪等です。
• 立場の想起 (意思決定グラフ Phase B)。librarian-positions は、これらのストリームから「Xについてどう考えていて、どう変わりましたか？」に回答します。トピックの現行の立場は、直近のイベントで示された立場です。そのイベントが retire の場合は、撤回時に記録された文章を含む撤回済みのスタブが返されます。撤回した立場が返されることはなく、スタブを作成するために履歴から何かが削除されることもありません。すべての回答には由来情報が記載されます。立場が形成された日付（最初の assert）と、該当する場合は最後に改訂された日付です。再確認は立場を再支持しますが、その日付は更新しません。長期間変更されていない立場には休眠中のマークが付きます。これはイベント自体のタイムスタンプから読み取りのたびに計算され、保存されることはありません。撤回済みの立場に休眠中のマークが付くことはありません。すべてがプロジェクションです。3つの SQLite テーブルは、npm run reindex のたびに <notes>/_librarian/positions/*.md から全体を再構築し、それ以外から再構築されることはありません。再インデックスだけがトリガーです。最後の再インデックス以降にキャプチャされた立場は、次回実行まで想起されません。これは隠れた欠落ではなく、明示された遅延であり、想起がキャプチャに一切干渉しないようにするための仕組みです。
• ノート名を変更してもノートの識別情報は保持されます。 参照には、ノートのパスとキャプチャ時のコンテンツハッシュの両方が記録されます。「デッド」とは、ファイルの種類にかかわらず、ディスク上にパスが存在しない状態を指します。隔離された Vault 内のあらゆるファイル（.gitignore、エクスポートされた.html、_librarian/ 内のファイルなど）への参照は、そのファイルが存在する限り有効です。インデックス対象の Markdown ノートかどうかは関係ありません。参照されているノートの内容を変更せずに名前を変更すると、次の npm run reindex で、古い参照は自動的に新しいパスに結び付けられます。ヒューリスティックも類似度スコアリングもなく、コンテンツハッシュの完全一致だけで判定します。librarian-recent と検索結果への補足情報では、参照先がひそかに解決されます。再インデックスで判定できない場合（ノートも編集されていて現在のノートとハッシュが一致しない、または同じハッシュのノートが複数ある場合）、librarian-recent には候補とともに未解決状態が明示されます。また、検索結果に候補ノートが含まれる場合、検索結果への補足情報にも表示され、npm run identity-confirm で確認されるまでその状態が続きます。候補がまったくない参照（名前が変更され、さらに編集されている場合）が表示されるのは librarian-recent だけです。この一覧が未解決の参照を確認するための完全な手段です。補足情報は候補を起点とするため、候補のない参照には言及できません。検索結果では、単なる候補に対して、あたかも確認済みであるかのような注釈が付くことはありません。未解決状態とその候補は、別個の明示的な注記として表示されます。確認済みの紐付けは固定されます。その後 Vault が変更され、自動のハッシュ完全一致では別の場所が示されるようになっても、確認済みの紐付けが優先され、意見の相違（「Xで確認済みですが、現在ハッシュはYに一致します」）が表示されます。これが上書きされるのは、npm run identity-confirm を再実行したときだけです。どちらの場合も、保存済みのセッション記録が書き換えられることはありません。

既知の制限事項

後から判明することのないよう、ここに記載します。

• 古い記録は情報量が多くなっています。 スタイルの規約と単語数の上限が、最初の2週間の記録後に導入されたため、既存の記録は遡って修正されません。初期のエントリーはビルドログのように読めます。読み取り時のガイダンスだけが、これらの記録にも適用されるレイヤーです。
• 品質はクライアントに左右されます。 サーバーにはモデルが含まれていないため、スタイルの規約を無視するクライアントが生成した要約も、サーバーはそのまま保存します。
• 共有されるのはツール間であり、人々の間ではありません。 1人のツールは1つのメモリを共有します。ここでは、人々の間で共有される記録、承認プロセス、どのバージョンの決定を採用するかといった問題には対応していません。これらはチーム規模での難題ですが、いずれもここでは解決されていません。
• 記録に記載されるのはモデルではなくクライアントです。 セッションエントリーまたはポジションイベントには、フックが特定できる場合、client ラベル（claude、grok、codex、agy、copilot、muse）が含まれるため、どのクライアントが要約の書き込みを停止したかを確認できます。これはホストを示すもので、モデルではありません。agy は Gemini と Claude のモデルを実行しますが、どちらのモデルかを示すフックのペイロードはありません。推測するよりラベルを省略するため、ラベルが導入される前の記録、手動で登録したフック、判断が曖昧なターンにはラベルが表示されません。現時点ではクライアントで絞り込んだり検索したりできません。
• キャプチャは、各ツールのモデルが指示に従うかどうかに左右されます。 フックが取得するのはモデルが書いた行だけです。Claude Code、Grok、Codex、Copilot CLI、Antigravity、Muse Code は、それぞれ実際のセッションで確認済みです。行を書かないモデルからは何もキャプチャされません。
• 再構築中に別のセッションと一時的に重なることがあります。 サーバーは起動時に変更を検出するとインデックスを再構築します。その際、数千件のノートごとに約1秒間、テーブルを削除して再作成します。その瞬間に別の開いたセッションから検索すると、結果が空になることがあります。変更のないインデックスは再構築されないため、これはまれであり、次の呼び出しで解消されます。
• 参照が示すのはキャプチャされた内容であり、読み取られた内容ではありません。 どのパスを一覧表示するかはクライアントが選択し、ハッシュはターン終了後、キャプチャの実行時に取得されます。rutter では、モデルがファイルを読んだこと、ファイルが結論につながったこと、キャプチャが完全であること、またはパスが変わっていないノートの内容がその後も変わっていないこと（このレポートはまだ作成されていません）を確認できません。追記のみというルールはサーバーが守るものであり、改ざん防止監査を保証するものではありません。rutter で確認できること、できないことを参照してください。
• セマンティック検索はスタブです。 embeddings.ts は実装を含まないポートであり、検索は全文検索のみです。
• 現在、積極的に評価中です。 状態を保持する動作は使用ゲートの背後にあり、プロジェクトでは実際に利用されるかを測定しており、利用されないという結論に至る可能性も想定しています。

要件

• Node ≥ 22（組み込みの node:sqlite を使用します。ネイティブのビルド手順は不要で、FTS5 も含まれています）。Node 26 で検証済みです。
• Markdown ノートのディレクトリ。Obsidian を前提に構築されており、ウィキリンクとフロントマターを認識しますが、Obsidian 自体は必須ではありません。
• アンビエントキャプチャには Claude Code、Grok、Codex、Copilot CLI、Antigravity、または Muse Code が必要です。MCP ツールはあらゆる MCP クライアントで動作します。 One memory across your AI tools の表に、6つのツールそれぞれのキャプチャ方法と、セットアップへのリンクが記載されています。Claude Code はトランスクリプトから指示を取得します。Copilot CLI と Antigravity も同様に、現在のターンから取得します。Grok、Codex、Muse Code は Stop イベントの最後のアシスタントメッセージを使用するため、Codex と Muse Code では指示を最終返信に含める必要があります。

セットアップ

まずノートの保存先を指定してください。 デフォルトは作者自身のパスです。読み取りできないディレクトリもエラーにはなりません。ノートが0件だったと報告する再インデックスが成功し、検索して何も見つからないと気づくまで、インストールが正常に動作しているように見えます。

npm からインストールする場合：

export LIBRARIAN_VAULT_PATH=/path/to/your/notes   # do this before reindexing
npm install -g rutter-memory
rutter-memory reindex  # expect a non-zero note count; zero means the path is wrong

引数なしで rutter-memory コマンドを実行すると MCP サーバーが起動します。クライアントはこの方法でサーバーを起動します。また、reindex [--force]、recent、install-hook も実行できます。rutter-memory help を実行すると、各コマンドが一覧表示されます。rutter-memory をインストールすると、同じプログラムを短い名前で呼び出す rutter コマンドも使えるようになります。これは npm の rutter パッケージとは無関係です。

クローンからコードを操作する場合：

export LIBRARIAN_VAULT_PATH=/path/to/your/notes   # do this before reindexing
npm install
npm run build          # compile to dist/ (optional; tsx runs the TS directly)
npm run reindex        # expect a non-zero note count; zero means the path is wrong

環境変数による設定：

変数	デフォルト	意味
LIBRARIAN_VAULT_PATH	~/Documents/knowledge-vault	インデックスを作成するノートのディレクトリ（読み取り専用）です。設定してください。
LIBRARIAN_DB_PATH	npm インストールの場合：~/.local/share/rutter/<id>/librarian.db（ノートフォルダーごとに1つ）。クローンの場合：<repo>/data/librarian.db	生成されたインデックスの保存先です。npm インストールでは、~/.local/share の代わりに $XDG_DATA_HOME が使用されます。1つのインデックスが扱えるのは、それを作成したノートフォルダーだけです。同じファイルを指定した2つ目のフォルダーは拒否され、reindex --force を実行すると、そのファイルの所有先が切り替わります。
LIBRARIAN_USER_LABEL	the user	クライアントが受け取る指示やツールの説明文で、サーバーが誰の作業について説明するかを指定します。自分の名前を設定すると、クライアントには「ユーザーの」作業より自然な表現で、「あなたの」作業を見ていると伝えられます。

使用メモ（セッション記録、使用ログ）は、ノートのディレクトリ内にある <notes>/_librarian/ に保存されます。コードリポジトリ内に保存されることはありません。詳しくは docs/memory-of-use.md を参照してください。

初めて使う方へ。 まず docs/overview.md でライブラリアンの概要と仕組みを確認し、続いて docs/memory-of-use.md で記録／想起／充実化／ゲートの動作を詳しく確認してください。同じドキュメントは shinytoyrobots.github.io/rutter でも読みやすい形式で公開されています。npm run site-drift を実行すると、公開サイトとこれらのファイルに差異が生じた場合に報告されます。現在の作業順序については docs/roadmap.md を参照してください。 docs/decision-graph.md では、位置が追記専用のイベントログに対する射影であり、別途管理するものではない理由など、位置の設計について説明しています。また、docs/decision-graph-plan.md では、これをフェーズに分割した構築計画を説明しています。

CLI から試す

npm からインストールした場合、rutter-memory recent には、以下の npm run recent と同じ引数を指定できます。 検索、使用ゲート、identity-confirm はクローンからのみ実行できます。

npm run search -- bitemporal forgetting memory   # full-text search
npm run recent                                   # recent session summaries
npm run recent -- --days 7                        # just the last week
npm run recent -- --project rutter           # just one project (case-insensitive)
npm run gate                                       # per-ISO-week use count

ワークスペースの出所情報が存在するようになる前に記録されたエントリには、プロジェクトが表示されません。プレースホルダーはなく、--project フィルターを使うと、推測することなくそのエントリが除外されます。

ノートの内容も変更されたリネーム（または重複する内容への変更）の後に、npm run recent が参照を [UNRESOLVED -- candidates: ...] と表示する場合は、適切な対象を手動で確認してください。これはローカル専用のコマンドであり、MCP ツールではありません。そのため、エージェントが切れた参照の意味を独自に書き換えることはできません。

npm run identity-confirm -- Notes/old-name.md Notes/new-name.md

アンビエントキャプチャを有効にする（一度だけの2ステップ）

CLAUDE.md に追加するものは何もありません。要約を残すこと、その正確な構文、書き方というキャプチャの契約全体は、サーバー内の MCP 指示として提供され、接続時にサーバーからすべてのクライアントへ送信されます。フックを登録して再起動すれば完了です。 例外は Antigravity と Copilot CLI です。Antigravity は指示をプロンプトに含める代わりにファイルとして保存し、Copilot はルーターのツールが呼び出されるまで指示を読み込まないため、どちらのインストーラーも指示ファイルを書き込みます。（詳細は docs/memory-of-use.md を参照してください。）

1. Stop フックを登録します。 npm でインストールした場合は、次を実行します。

rutter-memory install-hook                       # adds the hook to ~/.claude/settings.json
rutter-memory install-hook --client codex        # Codex: ~/.codex/hooks.json (then trust it via /hooks)
rutter-memory install-hook --client antigravity  # Antigravity: ~/.gemini/config/hooks.json
rutter-memory install-hook --client copilot      # Copilot CLI: ~/.copilot/hooks/rutter.json

npx ではなく、グローバルにインストールしてください（npm install -g）。フックは絶対パスで登録され、npx のキャッシュはいつでも削除される可能性があるためです。Node のバージョンを切り替えた後は、再インストールして同じ行を再実行してください。既存のフックが新しいパスに移動され、2つ目のフックが追加されることはありません。

クローンからの場合は、次のいずれかを実行します。

npm run build && npm run install-hook          # adds the hook to ~/.claude/settings.json
npm run build && npm run install-hook -- --client codex   # Codex: ~/.codex/hooks.json (then trust it via /hooks)
npm run build && npm run install-hook -- --client antigravity   # Antigravity: ~/.gemini/config/hooks.json
npm run build && npm run install-hook -- --client copilot       # Copilot CLI: ~/.copilot/hooks/rutter.json

…または、手動で ~/.claude/settings.json に追加します（フックは dist/capture-cli.js を実行するため、先にビルドしてください）。

{
  "hooks": {
    "Stop": [ { "hooks": [ { "type": "command", "command": "/ABSOLUTE/PATH/hooks/librarian-stop.sh" } ] } ]
  }
}

2. Claude Code を再起動します。 フックはセッション開始時に読み込まれます。新しいセッションでは、新たにビルドされたサーバーも読み込まれます。/mcp（ツール4つ）で確認し、次の実際のセッションの後に <notes>/_librarian/sessions/ にキャプチャが保存されていることを確認してください。

サーバーがクライアントに伝える内容

クライアントが要約を残さなければ、フックは何もキャプチャしません。また、サーバーには要約を書く AI が含まれていないため、サーバーは要約を残すように求めます。ここにある契約ブロックは、src/server.ts の SERVER_INSTRUCTIONS から逐語的に引用されています。これが契約の唯一の情報源です。このコピーがずれていないかをテスト（COR-R-030）で確認し、ずれていれば失敗します。

セッション中に後で思い出す価値のあることを決定したり、作り出したりした場合は、セッション要約を残します。次の形式で、指示行を1行出力します。

区別できる内容ごとに、完了した時点で1行を出力してください。最後にすべてを1行にまとめて保存するのではなく、些細な作業は一切記録しないでください。キャプチャフックは各ターンの後、直近の該当行を取得します。ツール呼び出しでは記録されません。後続の行には、前の行以降に新たに加わった内容だけを記述してください。

それぞれの行は、このセッションに参加していなかったものの、急いでいる賢い読者に向けて書いてください。決定したこと、または作り出したことから書き始め、セッション内の略語より一般的な言葉を優先し、このセッションで作られたコードネーム、バージョンタグ、略語は展開するか避けてください（ボールトで使われている用語は問題ありません）。ユーザーが決定、選択、判断、修正した場合は、その功績をユーザーに帰属させます。質問しただけの場合は帰属させません。示された理由は残してください。40語程度を目安にし、60語以内で終えてください。ビルドログではなく1行にします。保存時には一字一句そのまま残ります。

トピックに関する立場を形成、変更、再確認、または撤回した場合は、立場の行も残してください。`` -- 別に保存され、バイト単位でそのまま保持されます。これはまれです。

「Write each line」で始まる段落は、スタイル契約です（スタイル契約 を参照）。これは、半年後に読めない要約でディレクトリが埋め尽くされるのを防ぐ、唯一のものです。サーバーはここでは助けになりません。与えられた内容は、どのような文体であっても書き換えません。例外は、未入力のテンプレートです。<angle brackets> に囲まれたままの要約は保存されず、「指示なし」として扱われます。そのため、指示行をコピーして未入力のままにしても、何もキャプチャされません。

Stop イベントとともに作業ディレクトリが渡されるため、各エントリのプロジェクトについても設定は不要です。

キャプチャが保存されなくなった場合は、代替策として契約ブロックをグローバルな ~/.claude/CLAUDE.md に常設ルールとして貼り付けてください。これは念のための対策であり、必須の手順ではありません。必要になった場合は報告に値するバグです。サーバーだけでこの処理を担うことを想定しているためです。

Claude プラグインとしてインストールする

このプラグインにはサーバーとキャプチャフックが含まれているため、ビルドや登録、手動での編集は不要です。プラグインとしてインストールすると、Claude Code が求めるのは検索対象のノートフォルダーだけで、サーバーと Stop フックは自動で起動します。

rutter は、Claude Code と Cowork 向けに Anthropic Directory に掲載されています。Claude Code にはディレクトリが組み込まれています。/plugin → Discover で rutter を探すか、次を実行してください。

/plugin install rutter@anthropic-plugin-directory

ディレクトリから提供されるのは Anthropic が最後にレビューしたバージョンで、このリポジトリの最新状態より遅れている場合があります。リポジトリを直接追跡するには、代わりに専用のマーケットプレイスからインストールしてください。

/plugin marketplace add shinytoyrobots/rutter
/plugin install rutter@rutter

どちらか一方を選び、両方は選ばないでください。インストールが二重になると、サーバーとキャプチャフックがそれぞれ二つ登録されます。

ノートフォルダーを尋ねられたら選択し、その後 /reload-plugins を実行してください。代わりにシェルからインストールする場合（claude plugin install rutter@anthropic-plugin-directory、またはマーケットプレイスを追加した後に rutter@rutter）、--config vault_path=/path/to/notes を渡すか、後から同じプラグイン名で /plugin configure を実行してください。ノートフォルダーを指定しないと、サーバーは読み取るものがありません。

アンビエントキャプチャは、Claude Code、Codex、Antigravity、インストーラー経由の Grok 1.0.62 と Muse Code 1.4.10（Claude Code を一度も使用したことのないマシン上の Grok）、およびある Copilot CLI セッションで動作を確認済みです。その Copilot CLI セッションはキャプチャされ、後から Claude Code で呼び出されました。ディレクトリには Cowork 向けの rutter も掲載されていますが、Cowork でのキャプチャは未確認です。

• 実行されるもの。 ローカル MCP サーバー（node dist/stdio.js）と Stop フック（hooks/librarian-stop.sh）です。どちらも、このリポジトリで読める通常の Node とシェルコードです。dist/ はコミット済みの TypeScript ビルドなので、実行されるコードは GitHub 上のコードと同じです。
• データの保存場所。 検索インデックスはプラグイン専用のデータフォルダー（~/.claude/plugins/data/…）に保存され、アップデート後も保持されます。セッション記録はノートフォルダー内の _librarian/ に保存されます。
• インデックスは自動で管理されます。 サーバーは初回起動時にインデックスを作成し、ノート、セッション記録、または位置情報ストリームに変更があった場合は、次回起動時に再構築します。セッション中に加えた変更を反映するには、新しいセッションを開始してください。
• フックをすでに手動で登録している場合（rutter-memory install-hook または npm run install-hook）、プラグインを追加するときに ~/.claude/settings.json からその登録を削除してください。削除しないと、キャプチャが二度試みられます。重複は検出され、二重に保存されませんが、処理が無駄になります。
• メンテナー向け： プラグインがクローン直後から動作するよう、dist/ はコミットされています。src/ を変更したら、npm run build を実行して、結果をコミットしてください。

Grok、Codex、Copilot CLI、Antigravity、Muse Code のセットアップ

Claude Code にはワンコマンドのプラグインがあります。それ以外の四つは、もう少し手順が必要です。どれを使う場合も、ほかのクライアントと同じノートフォルダーを指定してください。そうしないと、それぞれが独自のメモリを保持します。

Grok

Grok に Claude Code は不要です。npm から rutter をインストールし、インストーラーを実行してください。

npm install -g rutter-memory
rutter-memory install-hook --client grok

インストーラーは ~/.grok/hooks/rutter.json（または $GROK_HOME/hooks/rutter.json）を書き込み、ノートフォルダーを含む grok mcp add の行を表示します。この行は自分で実行してください。インストーラーが実行することはありません。Grok は起動元のシェルから LIBRARIAN_VAULT_PATH を読み取るため、ノートが ~/Documents/knowledge-vault にない場合は、そのシェルで設定してください。Claude Code プラグインのフックを使って rutter がすでに動作している場合、インストーラーはそれを知らせ、二つ目の登録を追加しません。

フックが読み取るのは Grok の最終アシスタントメッセージだけなので、要約行は最終返信の末尾に置いてください。Grok はそのメッセージを 32,768 文字で切り詰めるため、非常に長いやり取りでは末尾の行が失われることがあります。最終メッセージに二つの行がある場合、保持されるのは最後の行だけです。詳しい手順については、Grok の手順を参照してください。

Codex

Codex はプラグインを使用できません。プラグインの変数を一切設定せず、フックもインストールしません。 Codex 0.163.0 で確認済みです。npm install -g rutter-memory で rutter をインストールしてから、次の手順を実行します。

1. Codex を起動するシェルで LIBRARIAN_VAULT_PATH をエクスポートします。フックから参照できるのはその環境のみで、~/.claude/settings.json は参照できません。手順 3 のインストーラーは、フックにフォルダーのパスも埋め込みます（--vault、この変数、またはサーバーの config.toml エントリーから取得します）。いずれも指定されていない場合、キャプチャはデフォルトのフォルダーに保存されます。
2. codex mcp add rutter … -- rutter-memory を実行してサーバーを登録し、--env LIBRARIAN_VAULT_PATH=… でノートのパスを渡します。docs/getting-started.md のCodex の手順を参照してください。
3. rutter-memory install-hook --client codex でフックをインストールします。また、Codex は指示をモデルに表示しないため、rutter の指示をマーク付きブロックとして ~/.codex/AGENTS.md に追加します。その後、/hooks を使って Codex でフックを信頼してください。インストールしても信頼が付与されるわけではなく、信頼されていないフックは実行されません。
4. Codex の最終返信にサマリー行が表示されることを想定してください。フックはその場所を調べます。最終返信に 2 行ある場合、最後の行だけが保持されます。

GitHub Copilot CLI

Copilot CLI 1.0.98 で確認済みです。npm install -g rutter-memory で rutter をインストールしてから、次の手順を実行します。

1. Copilot を起動するシェルで LIBRARIAN_VAULT_PATH をエクスポートします。フックはその環境を引き継ぎます。指定されていない場合、キャプチャはデフォルトのフォルダーに保存されます。
2. rutter-memory install-hook --client copilot を実行します。~/.copilot（または $COPILOT_HOME）の下に hooks/rutter.json と instructions/rutter.instructions.md を書き込みます。インストーラーが書き込んだファイルでない場合、上書きは行いません。ほかのフックファイルや、独自の copilot-instructions.md に変更が加えられることはありません。
3. インストーラーが表示する copilot mcp add の行を実行します。Copilot は MCP サーバーに PATH しか渡さないため、このコマンドには LIBRARIAN_VAULT_PATH が明示的に含まれています。
4. 指示ファイルは残しておいてください。Copilot はサーバーのツールが呼び出された場合にのみサーバーの指示を読み込むため、ほとんどのセッションでキャプチャの仕様が参照されなくなります。テストでは、サーバーの仕様だけでは不十分でした。インストーラーが書き込む、どのような場合にこの行が適用されるかを示す Copilot 固有の行をファイルの先頭に置いて初めて、モデルはその行を出力しました。

Copilot の画面では、サマリー行は HTML コメントであるため表示されません。フックは ~/.copilot/session-state/<session>/events.jsonl から現在のターンのアシスタントメッセージを読み取ります。Copilot はフックの開始から少し遅れてこのファイルを書き込むため、フックはターンが記録されるまで最大 3 秒待機します。ターンに 2 行ある場合、最後の行だけが保持されます。

Antigravity CLI

ここでは agy コマンドラインツールを扱います。検証には agy 1.3.2 を使用しています。Antigravity IDE は対象外です。npm install -g rutter-memory で rutter をインストールし、次の手順で手動設定してください。

1. rutter-memory install-hook --client antigravity --vault <your notes folder> を実行します。 Stop フックを ~/.gemini/config/hooks.json に登録し、キャプチャルールを ~/.gemini/config/rules/rutter-capture.md に書き込みます。--vault を指定しない場合は、既存の rutter フックが使用しているフォルダーを引き継ぎ、次にシェルの LIBRARIAN_VAULT_PATH を確認し、その後デフォルトフォルダーを使用して、どのフォルダーを選んだかを表示します。
2. インストーラーが表示する agy mcp add の行を実行します。フックと同じノートフォルダーが指定されるため、書き込みと読み込みに同じフォルダーが使われます。両者がフォルダーを異なる方法で認識するため、インストーラーは一度だけフォルダーを決定します。MCP サーバーのフォルダーは保存済みの設定です。フックには独自の設定がなく、agy を起動したシェルを引き継ぎます。環境に任せた結果、実際の保管庫が選ばれた一方で、agy が読み取れるのはテスト用の保管庫だけだったことがあります。エクスポート済みの LIBRARIAN_VAULT_PATH は、引き続きフックのデフォルト設定より優先されます。
3. ルールファイルはそのまま残してください。agy は MCP サーバーの指示をプロンプトに含めず、ファイルとして保存します。テストでは、モデルはその指示からも、同じ内容を記載した AGENTS.md からも、要約行を書きませんでした。グローバルな trigger: always_on ルールは毎ターン挿入されます。このルールを使うと、Gemini Flash、Gemini Pro、Claude Sonnet はそれぞれ、判断を下した後にはその行を書き、簡単な質問の後には書きませんでした。ルールを更新するには、インストーラーを再実行してください。
4. その行はターン内のどこにでも現れる可能性があります。Stop イベントには返信テキストが含まれないため、フックは agy のトランスクリプトから現在のターンのアシスタントメッセージを読み取ります。ターンに行が2つある場合は、最後の行だけが保持されます。前のターンの指示が再び読み取られることはありません。

別のノートフォルダーに切り替えるには、新しい --vault を指定してインストーラーを再実行し、その後 agy mcp add を再実行してください。各キャプチャは標準エラーに in vault <path> と出力され、~/.gemini/antigravity-cli/log/ にある agy のログで確認できます。デフォルトフォルダーが使用された場合も、その旨が表示されます。

Muse Code

Muse Code 1.4.10（Meta のターミナルエージェント）で検証済みです。npm install -g rutter-memory で rutter をインストールし、rutter-memory install-hook --client muse --vault <your notes folder> を実行します。 Stop フックと、任意の rutter サーバーエントリーを ~/.config/muse/settings.json に追加し、印付きのブロックを ~/.config/muse/AGENTS.md に追加します。Muse のモデルはサーバーの指示だけでは要約行を書かなかったためです。Muse は環境変数をクリアしてフックを実行するため、ノートフォルダーはフックに直接埋め込まれます。インストーラーはシンボリックリンクされたファイルや解析できないファイルを拒否し、自身のブロック外のテキストは変更しません。その後、新しい Muse セッションを開始してください。詳細と、検証した内容および検証していない内容については、Muse Code のパスを参照してください。

Claude Code に組み込む

このプロジェクトを初めて使う場合は、docs/getting-started.md に、各クライアントについてインストールから初回の想起までの設定手順があります。

npm run build の後、リポジトリのルートから次を実行します。

claude mcp add rutter --scope user -- node "$PWD/dist/stdio.js"

--scope user を指定すると、どのディレクトリからでも、すべての Claude Code セッションでサーバーが登録されます。 指定しない場合、サーバーはこのリポジトリ内のプロジェクト専用となり、実際に作業するディレクトリからは見えません。

サーバーは起動時にインデックスを更新するため、新しいセッションでは変更が自動的に反映されます。再起動せずに更新するには npm run reindex を実行してください。 "X について自分が行ったことをノートから検索して" のように尋ねると、クライアントは librarian-search を呼び出します。

プロジェクトの構成

src/
  config.ts          notes + db + _librarian paths, ignore list
  vault.ts           markdown walk + frontmatter parse
  db.ts              node:sqlite open + FTS5 schema
  indexer.ts         full reindex (notes -> cache)
  startup-index.ts   build the index at start if missing, rebuild only if notes or records changed
  search.ts          FTS5 query + get-note
  embeddings.ts      stubbed port (not implemented)
  server.ts          MCP tool registration (search, get-note, recent, positions) + server instructions
  stdio.ts           stdio entry point (local Claude Code)
  # memory-of-use:
  fs-safe.ts         write choke point: path confinement + atomic, append-only writes
  sanitize.ts        untrusted summary -> one inert line
  refs.ts            versioned identity (path + content-hash)
  workspace.ts       workspace provenance (cwd -> project + git remote, local reads only)
  session-record.ts  typed record format + append-preserving persistence
  capture.ts         ambient capture orchestration
  directive.ts       parse the client's session-summary directive (no inference)
  positions.ts       position-event stream format + append-preserving persistence (decision-graph Phase A)
  position.ts        position capture orchestration
  position-directive.ts  parse the client's position directive (no inference)
  position-fold.ts   fold the position streams into the rebuildable projection (reindex only, Phase B)
  position-recall.ts librarian-positions' three query modes + what is computed rather than stored
  position-render.ts how a recalled position is worded (attribution, retired stub, inert rendering)
  recent.ts          librarian-recent (grouping / project / window / count / empty-state)
  enrichment.ts      additive prior-engagement annotation on search results
  instrumentation.ts append-only use log + per-ISO-week counts
  identity.ts        note identity: exact-hash rename binding + the rebuildable projection
  app.ts             application seam (domain + instrumentation), used by server + tests
  reindex.ts / search-cli.ts / recent-cli.ts / gate-cli.ts / capture-cli.ts / identity-confirm-cli.ts   CLIs
hooks/
  librarian-stop.sh  Claude Code / Grok / Codex / Copilot CLI / Antigravity / Muse Code Stop hook -> capture-cli
  hooks.json         registers that hook when installed as a Claude plugin
.claude-plugin/      plugin manifest (name, version, how it starts the server, notes-folder option, listing links) and marketplace
dist/                committed build, so the plugin runs straight from a clone
spec/                the executable spec — scenarios, requirements, conformance mapping
test/                node:test suite (temp fixture directories; never touches your real notes)

これをどのように構築しているか

動作は、実装に先立って仕様として定義します。spec/spec.md には、Given-When-Then シナリオと、そこから導かれた要件が記載されています。それぞれの要件は評価に使うテストに対応付けられており、すべての修正には、却下した内容とその理由が記録されています。

ここでの判断を理解したい場合は、このファイルがその経緯を率直に記した記録です。この README は概要で、仕様書には詳細が記載されています。

プライバシーポリシー

rutter はすべてお使いのマシン上で動作します。このセクションがポリシーのすべてです。

収集する情報。 作者も第三者も、何も収集しません。サーバーは指定されたノートフォルダーを読み取りますが、ノートを変更することはありません。ローカルファイルを5種類書き込みますが、どれも開いて内容を確認できます。そのうち4種類はノートフォルダー内の _librarian/ フォルダーに、5種類目はプラグインと同じ場所に保存されます。

• セッション記録（_librarian/sessions/）：AI クライアントが、セッション中に何かを決定または生成するたびに書き込む1行の要約を、書き換えずに（1行に正規化して）保存します。引用されたノートのパスと内容のハッシュ、作業ディレクトリ、それをもとに割り出したプロジェクト名、セッション ID、書き込んだクライアント（固定の4つの名前のうち1つで、モデル名は含みません）、およびそのディレクトリに Git リモート URL がある場合はその URL（.git/config から読み取ります。接続はせず、URL に含まれるトークン、パスワード、クエリ文字列は保存前に削除します）も併せて保存します。
• 立場の記録（_librarian/positions/）：トピックについての立場を形成、変更、または撤回したときにクライアントが記録する内容を、日付とともに同じ方法で保存します。
• ノート識別台帳（_librarian/note-identity.md）：参照したノートの名前が変更された場合、参照先となる新しいパスを、古いパスと新しいパス、および内容のハッシュとともに記録します。インデックスの再構築時、または一致を確認したときに書き込まれます。
• 使用ログ（_librarian/stateful-use.jsonl）：各リコールツールを使うたびに、タイムスタンプとツール名を記録し、ツールを使い続ける価値があるか確認できるようにします。
• 検索インデックス（プラグイン独自のデータフォルダーにある SQLite ファイル。npm でインストールした場合は ~/.local/share/rutter/、クローン内では data/、または LIBRARIAN_DB_PATH で指定した場所に作成されます）：ノートと上記の記録をもとに構築され、検索を高速化します。これはキャッシュであり、いつでも削除して再構築できます。

使用方法と保存先。 すべて、お使いのコンピューター上でご自身の検索やリコールに回答するためだけに使用されます。どこにも送信されません。コードはネットワークリクエストを行わず、分析機能やテレメトリーもありません。rutter 独自の処理は2つあります。ほかのプログラムを起動しないローカルサーバーと、各ターンの後にローカルの dist/capture-cli.js を実行して上記の記録を書き込むキャプチャーフック hooks/librarian-stop.sh です。どちらも認証情報や API キーを読み取りません。お使いの AI クライアント（たとえば Claude）は、ツールが返す内容を、そのクライアント独自のプライバシー条件に従って確認します。rutter はその条件を管理しません。

第三者との共有。 ありません。

保存期間。 ファイルを保持している限りです。セッション記録、立場の記録、識別台帳、使用ログは、設計上、追記のみです。これらを削除するには、ノートフォルダー内の _librarian/ フォルダーを削除してください。インデックスを削除するには、プラグインのデータフォルダー（プラグインをアンインストールすると削除されます）、クローンの data/ フォルダー、または npm でインストールした場合は ~/.local/share/rutter/ を削除してください（パッケージをアンインストールしても削除されません）。XDG_DATA_HOME を設定した場合、そのインストールのインデックスは代わりに $XDG_DATA_HOME/rutter/ にあります。また、LIBRARIAN_DB_PATH を設定した場合は、指定したファイルとその -wal および -shm ファイルが対象です。先に、それを使用しているクライアントを終了してください。ほかの場所には何も保持されません。

お問い合わせ。 ご質問や懸念がある場合は、issue を作成するか、[email protected] にメールでお問い合わせください。

ライセンス

MIT。詳細は LICENSE をご覧ください。

---

インデックスはキャッシュです。ノートはあなたのものです。記録こそが目的です。