nodedex

NodeDex

エージェントのための、プロジェクトの意思決定履歴

エージェントにプロジェクトの意思決定履歴を渡せます。提案する前にすでに却下された内容を確認し、古い決定を引用するのではなく、置き換えのつながりをたどって現在の結論を把握し、セッションを重ねても調査全体を引き継ぎます。エージェント自身の会話からローカルの因果グラフを自動的に構築します。Claude Code、Cursor、Hermes、または独自に作成したエージェントループで動作します。（事実を保存するストアとは役割が異なります。両方を使う。）

クイックスタート · 仕組み · エージェントを接続する · NodeDex を使う理由 · 有効性の根拠 · ドキュメント

_{エージェントが自分の記憶をたどります。行き止まり → 断念した理由 → 因果関係の連鎖。構造そのものが想起を支えます。}

NodeDex がないと、セッション N+1 では、セッション N ですでに決着した内容がひそかに再導出されます。どのアプローチが失敗したか（そしてその理由）、どの決定が置き換えられたか（そして何に置き換わったか）、どの制約が今も有効か、といった内容です。NodeDex はその記録をローカルの SQLite グラフに保持し、エージェントがセッションを重ねながら意図的にたどれるようにします。

ステータス — 開発初期・個人開発。 NodeDex は一人で開発しており、まだ開発初期の段階です。 エンジンはエンドツーエンドでテスト済み（1319 件のテストが成功）ですが、 多数のマシンやエージェントで実地検証されたわけではありません。まだ荒削りな部分があります。問題を見つけたら報告してください。 この段階でのフィードバックは非常に貴重です。

最も新しく、実地検証も最も少ない機能： 3 本のワイヤーによるセットアップ — エージェント自身に NodeDex を導入させ（リフレックス＋キャプチャ＋ゲート）、エージェントの申告を鵜呑みにせず、実際に行われたことをもとに各ワイヤーを検証します。ゲート（編集前のチェック。警告のみ、失敗時も処理を継続）は登場したばかりです。ロードマップにあった「単なる促しではなく、フックで強制されるチェック」を置き換えるものです。長いタスクでエージェントの振る舞いが変わるかどうかは、まさにこれから測定するところです。現時点では、変化があるとは主張していません。

ロードマップ： Claude Code のネイティブメモリとの相互運用 · 「前回のセッション以降の新着情報」を提示する機能 · 対応エージェントホストの拡大。

はじめに

3 つのステップです。最初にサーバーを一度セットアップし、残り 2 つでエージェントを接続します。

# 1. Install + run the setup wizard — asks for a provider key, model, port, and database.
npx nodedex                 # or: npm i -g nodedex && nodedex onboard

# 2. Point your agent at the running server (one line; this is the only host-specific part).
#    Claude Code shown — Cursor, Codex, Copilot, Hermes and custom loops in "Connect your agent".
claude mcp add --transport http nodedex http://127.0.0.1:3001/mcp   # 3001 = the port you chose

3. エージェントに Set up NodeDex と伝えます。 エージェントが自ら導入します。グラフを埋める CAPTURE、確認を忘れないための REFLEX、編集時に確認する GATE を設定し、それぞれについてあなたの許可を求めます。NodeDex は各設定が実際に行われたことを検証するため、何も申告だけで済ませることはありません。

これでセットアップは完了です。詳細はこちら：セットアップ（ウィザード） · エージェントを接続する （すべてのホスト） · 60 秒で試す（デモグラフを使用、キー不要）。 後からツールを切り替えてもデータは移動しません。新しいエージェントを同じサーバーに接続し、再び Set up NodeDex と伝えてください。

NodeDex を選ぶ理由

忘れたことは表面化します。エージェントがまた尋ね、あなたはため息をつき、もう一度説明します。実際に手戻りを招く失敗は、気づかれないまま起こります。エージェントが3セッション前に試して断念した方法をまた提案したり、2週間前に置き換えられた決定に基づいて計画したりします。古い決定は現在の決定とまったく同じように権威があるように見え、却下済みの方法は新鮮な案のように聞こえ、何時間もの作業が二度無駄になります。

NodeDex は、過去について「確信を持って間違える」問題を解決します。 これはナレッジの ステータス の問題です。却下済み、置き換え済み、未解決といったステータスは、記憶ではなく構造です。そこで NodeDex は、プロジェクトの推論の残滓を、エージェントが たどる グラフとして保持します。理由と不採用だった代替案を伴う決定、最初に確認するようエージェントに教える、行き止まりを列挙可能な恒久的な閉鎖リストとして記録したもの（強く促しますが、強制的にブロックはしません）、ひそかに変更されてはならない制約、そしてそれらを結び付ける因果関係です。

プロジェクトを引き継いだ新しいエージェントが受け取るのは、事実を順位付けした山ではありません。調査の過程をたどり、何を 繰り返してはいけないか を学びます。

NodeDex が 不要な 場合

適用範囲を正直にお伝えします。短いセッション、単発のタスク、事実を想起するワークフローでは、ネイティブメモリで十分です。NodeDex は使わなくてかまいません。導入すると過剰です。NodeDex が真価を発揮するのは、失敗の繰り返しが大きなコストになる、長期にわたる、決定事項の多い、複数セッションにまたがる作業です。特に、エージェントが行き止まりを再提案するのを見張る人間がいない自律実行で効果を発揮します。

60 秒で試す — キー不要、セットアップ不要

新しいグラフは空です（実際の作業を重ねることで価値が蓄積されます）。そのため NodeDex には、すぐに確認できるサンプルプロジェクトの履歴が用意されています。

npx nodedex demo

これは小規模な完成済みプロジェクトを提供します。理由と却下された代替案を含む決定、行き止まり、制約、そして 置き換えられた 決定が1つあります。http://127.0.0.1:3009/mcp で利用できます。任意の MCP エージェントを接続して、次のように尋ねてください。

1. 「ratelimiter プロジェクトでは何を試して断念しましたか？ その理由は何ですか？」
2. 「なぜトークンバケットが選ばれたのですか？ ほかにどのような案が検討されましたか？」
3. 「『カウンターを Redis に置く』というのは、今も現行の決定ですか？」 — いいえ。エージェントが古い決定を引用するのではなく、置き換えのエッジをたどって現在の事実にたどり着く様子を確認できます。
4. 「未解決または未検証のことは何ですか？」

15 個のブロックからなるおもちゃのような例から得られる回答が役立つなら、自分の6週間分の作業から得られる回答を想像してみてください。nodedex stop 3009 でデモを終了できます。実際のグラフには一切触れません。

インストール前に証拠を確認しますか？ 動作を示す証拠 — 実際のトランスクリプトからパイプラインが取り込む内容、グラフの健全性、そして限界を正直に示す検索をご覧ください。

その概要

プロジェクトで確立されたこと、つまりすべての決定、行き詰まり、制約と、それらを結ぶ因果関係をローカルのナレッジグラフに記録します。コンテキストウィンドウの外部に保存され、エージェントが MCP 経由で読み取ります。メモを取るためのツールではありません。誰も手作業で整理せず、バックグラウンドのパイプラインが作業内容そのものから構築します。

エージェントはデフォルトではステートレスです。NodeDex は、あらゆるコンテキストのリセット後も残る、プロジェクトの推論を記録した永続的な記録を提供します。LLM はその上で動作する推論エンジンにすぎません。

主な特性：

• ストレージはローカルです（~/.nodedex/*.db）。抽出は、選択したモデルに応じてローカルまたはクラウドで行われます。クラウドプロバイダー（例：OpenRouter）は抽出のために会話内容を受け取り、ローカルモデルではすべてのデータがマシン上に保持されます。NODEDEX_DB_ENCRYPTION_KEY を設定しない限り、データベースは平文です。
• エージェントは意図的にグラフをたどります。まずツリービューを使い、次に検索します。
• 因果関係の連鎖を第一級の要素として扱います。ブロックには、そこに至った関係が記録されます（単独の記録も可能です）。
• 行き詰まりは設計上保持されます。ただし、抽出で見落としたり、誤分類されたりすることはあります。確認できるよう、すべてのブロックには元の文章がそのまま含まれています。
• 非同期の AI パイプラインが、エージェントに負荷をかけることなく、生のやり取りを構造化された知識に変換します。

仕組み — 3つの役割

  Autonomous agent (e.g. Hermes)
        │   reads ▲                         │ each finished turn (a COPY)
        │  (MCP)  │                         ▼
        │   ┌─────┴──────────────┐   ┌──────────────┐
        └──▶│  NodeDex server    │◀──│ capture tee  │  (out-of-path, fire-and-forget)
            │  • MCP read tools  │   └──────────────┘
            │  • REST API        │
            │  • AI pipeline ────┼──▶ writes blocks / chains / links (async)
            │  • self-maintenance│   (dedup · provenance · heal)
            └─────────┬──────────┘
                      ▼
              ~/.nodedex/<your>.db   (SQLite WAL — local, bitemporal)

• エージェントは、読み取り専用の MCP ツール（workspace_get、workspace_search、workspace_filter、workspace_tree、workspace_stats、…）を使ってグラフをたどります。知識を書き込むツールはデフォルトで非表示です。読み取りを行うと、開いたブロックに使用状況のメタデータ（アクセス回数）が記録されます。内容、リンク、ステータスが変更されることはありません。デフォルトで使える唯一の意図的な書き込み機能は workspace_task_update です。エージェントは自身のタスクステータスを管理します（作業が実際に完了したことを把握しているのはエージェントだけです。それ以外はすべてパイプラインの役割です）。
• パイプライン（サーバーサイド AI）は、各ターンの記録から、事実、決定、行き詰まり、洞察、制約、推論の連鎖など、すべてを非同期でまとめます。エージェントが作業を中断して保存する必要はありません。
• キャプチャは、完了した各ターンをサーバーに送ります。方法はホストによって異なります。Hermes は自身の state.db を読み取ってキャプチャされます（モデルプロキシを無視します）。カスタムベース URL に対応している OpenAI 互換ホストは、NodeDex のプロキシ経由でモデルに接続できます。ループを制御できるエージェントでは、経路外の小さなティー（workspace_install_capture）を使います。NodeDex は受動的な MCP サーバーであり、エージェントの返信を自力で確認することはできません。そのため、キャプチャなしではグラフは空のままです（エージェントを接続するを参照）。

SQLite WAL — 単一のローカルファイルに、二時点リレーションを保存します（履歴は保持され、削除されません）。

セットアップ

コマンドを1つ実行するだけです（Node ≥ 18）：

npx nodedex

初回実行時にセットアップウィザードが起動し、設定後は同じコマンドでサーバーが起動します。通常どおりインストールしたい場合は、npm i -g nodedex を実行すると、nodedex を PATH から利用できるようになります。設定、キー、データベース、ログなど、すべてが ~/.nodedex/ に保存され、npx nodedex uninstall を実行するとすべて削除されます。

エージェントにインストールを任せることもできます。 シェルにアクセスできるエージェント（Claude Code、OpenClaw、Hermes など）をすでに使っている場合は、AGENT-INSTALL.md を貼り付けてください。エージェントが3つの同意確認を行い、ヘッドレスセットアップコマンドを1つ実行してサーバーを起動し、自身を接続します。

ネイティブドライバーに関する注意： SQLite ドライバーは、一般的なプラットフォーム向けにビルド済みのものが同梱されています。ソースからのコンパイルが npm に必要な場合に限り、C/C++ ツールチェーンが必要です（macOS： xcode-select --install · Debian：build-essential python3 · Windows： VS Build Tools → C++）。

git clone https://github.com/NodeDex/NodeDex-v0.1.git
cd NodeDex-v0.1/server && npm install          # compiles/fetches the SQLite driver
cd ../tui && npm install
npm run dev                                    # first run launches the setup wizard

ウィザードに沿って設定できます。モデルを選択します。OpenRouter（クラウド。キーを用意してください。該当する場合は、無料プランではプロンプトが学習に使用されるという警告が表示されます）または Local / self-hosted（Ollama／LM Studio／vLLM。オフラインで利用でき、キー不要、無料。ウィザードがローカルモデルをスキャンして一覧表示するので、モデルを選ぶだけです）を選びます。続いて、空いているポートを選び、データベースを作成または命名します。サーバーは localhost で起動し、最後の画面にサーバー URL（ネットワーク／Docker バインドを選択した場合は認証トークンも）が表示されます。次の手順でエージェントに渡すのはこの情報なので、保存してください。 初回実行時には、セマンティック検索をオフラインでキー不要で使えるよう、同梱のローカル 埋め込み モデルもダウンロードされます（1回のみ）。

抽出モデルには、高い性能と大きなコンテキストウィンドウの両方が必要です。 パイプラインは会話全体の流れを理解し、厳密で完全な構造化出力を生成するようモデルに求めます。これは通常のチャットより難しい処理です。実際のテストでは、12B のローカルモデルは十分に理解できるものの、厳密な構造化処理では安定して失敗します（必須項目を落とす、出力が止まらなくなるなど）。パイプラインは不完全な結果の保存を拒否するため、安全性は確保されますが、メモリーは残りません。実用上の最低ラインは、低価格のクラウドモデル（推奨の gemini-2.5-flash-lite。抽出1回あたり約½¢、コンテキストは1M）か、約27～30B以上のローカルモデルを実際のコンテキストウィンドウが≥16kの状態で提供することです（Ollama のデフォルトの num_ctx に注意してください。モデルがサポートするサイズに関係なく、インポート時には8kで実行されることがよくあります）。ローカルで実行する場合は、NODEDEX_THINKING_BUDGET=off と、使用するモデルの NODEDEX_MODEL_CAPS エントリーも設定してください。

ウィザードでは同じマシン上でサーバーをセットアップします（localhost）。これがデフォルトです。エージェントを Docker 内または別のマシンで実行する設定は、後から行う高度なセットアップです（0.0.0.0 にバインドし、トークンを設定します）。docs/how-to/connect-mcp-over-http.md を参照してください。

埋め込みには、デフォルトで同梱のローカルモデルを使用します（オフライン、無料、キー不要）。代わりにホスト型の埋め込みモデルを使用する場合は、~/.nodedex/.env に EMBEDDING_PROVIDER=gemini（または openai）を設定してください。これはシェルコマンドではなく設定値なので、すべての OS で同じです。設定はすべて ~/.nodedex/ に保存され、プロバイダーのキーがリポジトリに入ることはありません。(Windows では、~/.nodedex は C:\Users\<you>\.nodedex を意味します。)

次の手順： 実行中のサーバーにエージェントを接続します。

エージェントを接続する

NodeDex は、長期間にわたる複数セッションの作業を行うエージェント型エージェント向けに構築されています。ファイルの読み書きとツールの実行ができれば、どのエージェントでも使えます。Claude Code、Cursor、Codex、Copilot、Hermes のような自律型ホスト、あるいは自分で作成したループでも同じです。以下のセットアップは、あなたではなくエージェントが行うため、すべてに共通です。

手順は2つだけです。

ステップ 1 — エージェントをサーバーに接続します（ホストごとに異なるのはここだけです）

ウィザードはすでにサーバーを起動し、URL（http://127.0.0.1:<port>/mcp）を表示しています。 ホストに MCP（Streamable-HTTP）経由で登録します。一度だけ、1 行で済みます。

localhost ではなく 127.0.0.1 を使ってください — サーバーは IPv4 にバインドされており、Windows では localhost が先に IPv6 の ::1 に解決されるため、接続に失敗しても何も表示されません。URL をなくした場合は、nodedex connect を実行してください。 ~/.nodedex/connect-snippets.md にすぐ貼り付けられる設定も保存されており、起動のたびに再生成されます。

ステップ 2 — エージェントに自分で設定するよう伝えます

一度だけ、次のように伝えます。

Set up NodeDex

指示はこれだけです。エージェントが自分自身に NodeDex をインストールします — エージェントは自分のホストについて私たちよりも詳しいので、自分のファイルと設定箇所を見つけます。何かに手を加える前に許可を求めます。また、完了するまでツールの結果が返るたびに催促されるため、設定を飛ばしにくくなります。

3 つのワイヤーがあり、それぞれ有効期間が異なります — そこが要点です。

ゲートは警告するだけで、処理をブロックすることはありません。また、フェイルオープンするため、NodeDex が動作していなくても何もしません。エディターの利用を妨げることは決してありません。

どの設定も、自己申告だけでは済みません。 NodeDex は実際に起きたことに基づいて各ワイヤーを検証します — ファイルを読み返してマーカーを探し、実際のターンがグラフに記録されるのを待ち、実際のチェックがエンドポイントに届くのを待ちます。設定したと言うだけで実際には設定していないエージェントには、引き続き催促が届きます。

その場合、何もインストールできないため、手動で接続します。任意の言語で 3 回 HTTP を呼び出します。

# 1. REFLEX — paste this into that agent's system prompt (it must be present on EVERY turn)
curl http://127.0.0.1:3001/api/agent-reflex?format=text

# 2. CAPTURE — POST each finished turn, fire-and-forget, out of your model's path
#    POST /api/reflect/trigger  { user_message, agent_response, reasoning }

# 3. GATE — call before a file edit; feed anything it returns back into context
curl http://127.0.0.1:3001/api/gate/check

Node では、workspace_install_capture がすぐに使えるアダプター（呼び出しをそのまま転送するティー。モデル呼び出しには一切触れず、遅延も発生させません）をエージェントに渡し、workspace_install_gate がゲートスクリプトを渡します。

ホストによっては独自のトランスクリプトを保持し、ターン後の接続ポイントを公開していません（Claude Code、Hermes など）。そのような場合は、NodeDex が代わりに ウォッチャー を提供します。これは読み取り専用で一方向に動作し、TUI から有効にできるため、接続設定なしでキャプチャできます。ウィザードがこれらを検出して確認します。

詳細／その他のホスト。 動作の仕組みは 2 つの要素から成り、それぞれ独立しています。

1. エージェントにツールを提供する（読み取り側）。 実行中のサーバーを MCP 経由でエージェントホストに登録します（/mcp で Streamable-HTTP を使用）。方法は エージェントの実行場所 によって異なります。

同じマシン（デフォルト）

エージェントはこのコンピューター上で実行されるため、ループバック経由でサーバーに接続できます。ウィザードはすでにサーバーをそこで起動しています。ホストの接続先に /mcp URL を指定します（ほとんどの MCP ホストでは小さな JSON 設定を使用します）。

{
  "mcpServers": {
    "nodedex": { "url": "http://127.0.0.1:3001/mcp" }
  }
}

localhost ではなく 127.0.0.1 を使用してください — サーバーは IPv4 にバインドされます。また、Windows では localhost が最初に IPv6 の ::1 に解決されるため、localhost では接続に失敗しますが、127.0.0.1 なら接続できます。

または、ホストに stdio 経由で起動させる こともできます（まず npm i -g nodedex を実行して、コマンドを PATH 上で使えるようにします。クローンから実行する場合は、代わりに node /path/to/server/scripts/nodedex-entry.mjs を使います）。

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

CLI スタイルのホスト（例：Hermes）の場合：hermes mcp add nodedex --url http://127.0.0.1:3001/mcp を実行してから、MCP 接続を再読み込みし、新しいセッションを開始します。

Claude Code、Cursor、VS Code — 設定ファイルを選ぶのはエディターではなく エージェント です。 Claude Code 拡張機能は Cursor や VS Code 内で実行される場合でも .mcp.json を使用します。Cursor と VS Code の 独自の エージェントは、それぞれ独自のファイルを使用します。/mcp URL は同じですが、エージェントごとに場所とキーが異なります。

ホストを切り替えても（例：Hermes → Claude Code）、データは移動しません。 グラフはホストに依存しません。すべてのエージェントが 同じ グラフを読み取り、データを追加します。ホストを追加または切り替えるには、新しいホストを接続するだけです（上記の MCP 接続と、以下のキャプチャ方法）。以前のホストが残したデータはすぐに確認できます。必要であれば、複数のホストを同時に実行できます。

Docker 内または別のマシン上のエージェント（上級者向け — 初回設定向けではありません）

コンテナー化されたエージェントやリモートエージェントはホストのループバックに接続できないため、サーバーを 0.0.0.0 にバインドし、トークンを使用する必要があります。また、エージェントはホストアドレス（例：host.docker.internal）経由で接続します。これは意図的に後から行う設定です。手順（ホストのバインド、トークン、Docker のネットワーク設定）については、 docs/how-to/connect-mcp-over-http.md を参照してください。

これでエージェントに 読み取りツール が表示され、グラフをたどれるようになります。（サーバーは MCP の instructions フィールドを通じて独自の使用プロトコルを提供するため、プロンプトを変更する必要はありません。）

2. キャプチャを有効にする（書き込み側）— 必須です。有効にしないとグラフは空のままです。 NodeDex は パッシブ な MCP サーバーです。ツール呼び出しは確認できますが、エージェントの返信は確認できません。完了した各ターンをサーバーに送信する仕組みが必要です。エージェントに合った方法を選んでください。

(a) ウォッチャー — 自分のターンを保存するホスト向けのセットアップ不要なキャプチャ

最も手軽な方法です。NodeDex はホスト独自の会話ログを読み取ります（読み取り専用、ご利用のマシン上で、以降の分のみ — 過去の履歴は読み取りません）。ホスト側での設定は不要です。オンボーディングウィザードがインストール済みのホストを検出し、キャプチャするホストを尋ねます。切り替えはTUI の設定ビューで行えます。

• Claude Code — セッションのトランスクリプト（~/.claude/projects/…jsonl）を追跡します。グラフでは各セッションが個別のアークになります。projects の行でキャプチャするプロジェクトを指定します（* = すべて）。
• Hermes — Hermes の state.db を読み取ります（Hermes はカスタムモデルのベース URL を無視し、シェルフックも呼び出さないため、この方法だけが有効です）。sources の行はプライバシーフィルターです（デフォルトは tui）。詳しい手順は次のとおりです。 docs/how-to/connect-hermes.md。

(b) カスタムベース URL を使用できる OpenAI 互換ホスト — モデルを NodeDex 経由でルーティング

モデルのエンドポイントをリダイレクトできるホスト向けの、デプロイ不要な方法です（Hermes はできないため、(a) を使用してください）。エージェントのモデルベース URLを NodeDex のプロキシに指定します。プロキシは各呼び出しを変更せずに実際のプロバイダーへ中継し（遅延は追加されず、ストリーミングも機能します）、その間にターンをキャプチャします。エージェントのモデル／プロバイダー設定で、次のように設定します。

• ベース URL： http://127.0.0.1:3001/api (Windows では localhost ではなく 127.0.0.1 を使用してください。0.0.0.0 にバインドされたサーバーは IPv4 のみで、localhost は最初に IPv6 の ::1 に解決されます。リモート／Docker のエージェントでは、代わりにホストアドレスを使用してください)
• API キー： 通常使用しているプロバイダーキー（例：OpenRouter の sk-or-…）— そのまま転送され、保存されることはありません
• モデル： 変更なし

デプロイするファイルはなく、この方法ではNodeDex トークンも不要です（プロキシは認証対象外で、独自のプロバイダーキーを使用します）。

(c) コード／ループを制御できるエージェント（Agent SDK、LangChain、独自のループ）— ティー

エージェントに workspace_install_capture を一度呼び出させます。ターン後の接続ポイントに挿入できる、小さなアウトオブパスのティーが返されます（サーバーに {user, response, reasoning} を POST します）。トークンで保護されたサーバーでは、ティーを実行する場所に NODEDEX_TOKEN を設定し、POST を認証してください。

これらのいずれも使用しない場合、エージェントはメモリを読み取ることはできますが、グラフは増えません。

エージェントに渡す情報は、選択した方法によって異なります。 読み取りには常に MCP の …/mcp URL を使用します（Docker／ネットワークサーバーの場合のみ、トークンも必要です）。キャプチャ方法はホストによって異なります。

Hermes を使用していますか？ エンドツーエンドの詳しい手順（MCP による読み取り、state.db ウォッチャー、注意点すべて）はこちらです：docs/how-to/connect-hermes.md。

ホストごとの詳しい情報（HTTP トランスポート、Docker／host.docker.internal、キャプチャアダプター、環境変数の切り替え）は、docs/how-to/connect-mcp-over-http.md および docs/how-to/deploying-nodedex.md を参照してください。

再設定／アンインストール

# change your key / model / provider (merges into ~/.nodedex/config.json)
npx nodedex setup --provider openrouter --key sk-or-...   # validated before saving
npx nodedex onboard                                       # or re-run the full wizard

# remove all local data + config (~/.nodedex: config, API key, databases, logs)
npx nodedex uninstall      # asks for confirmation — this is destructive

TUI 内で操作することもできます。settings view → provider row でクラウド／ローカルを切り替え、モデルを選択します（ローカルモデルは自動的にスキャンされます）。同じプロバイダー内でモデルを変更するとすぐに反映されます。プロバイダー／エンドポイントの切り替えは、サーバーの再起動時に反映されます（db を切り替えるか、TUI を再起動してください）。

複数のキー＋自動フェイルオーバー。 実際の環境では、複数のキーを使うことがよくあります。アカウントを使い分けたり、1 つを予備にしたりできます。nodedex config を実行すると、専用のキーリングページが開きます。複数の API キーを保存し、1 つをアクティブ、もう 1 つをフォールバックに指定して、フォールバックモデルを設定できます。また、アクティブキーの請求上限に達したときの動作（フェイルオーバーして続行するか、支出の一時停止を維持するか）を選択できます。実行中のサーバーは、アクティブキーが拒否された場合（キーが無効）やクレジットがなくなった場合に、自動的にフォールバックキーへフェイルオーバーします。同じモデルが使われ、再起動は不要です。アクティブキーを設定すると、実行中のサーバーがその場で切り替わります。nodedex tui にすべて反映されます（どちらも同じ ~/.nodedex/config.json を読み取ります）。TUI 設定の keyring row からもキーリングにアクセスできます。

現時点では、キーは ~/.nodedex/config.json に平文で保存されます（シングルユーザー、ローカル優先の設計です）。 このファイルは機密情報として扱ってください。より広範なリリースの前に、保存データの暗号化を予定しています。

アンインストールしても、パッケージは削除されません（削除するには npm rm -g nodedex を実行してください）。また、エージェントホストの MCP 設定にある NodeDex の項目も削除されません（ホスト側で削除してください）。キー／モデル／プロバイダーを変更するには、TUI（nodedex tui → 3 health → provider で Enter）を使うか、nodedex onboard を再実行してください。またはヘッドレスで、nodedex setup --provider openrouter --key … --model … を実行します。

コマンド

サーバー（cd server）：

nodedex コマンド（npx nodedex / npm i -g nodedex から実行。クローンから実行する場合は、 cd server && npm link で同じコマンドを使えるようになります）：

TUI には3 つのビューがあります。1 memory（ルートの閲覧、ストーリーのたどり、/ による検索）、2 feed（メモリのリアルタイム生成と、エージェントが読み取った内容）、3 health（サーバー／db の切り替え、プロバイダーとモデルの選択、パイプライン設定、キャプチャの切り替え、レビューキュー）です。すべての操作は行単位です。↑↓ で移動し、enter で実行します。

サーバーの通常の起動方法は TUI です（キー／モデルを設定し、ポートとデータベースを選び、db の切り替え時にはサーバーを再起動します）。上記の server/ スクリプトは、手動操作または上級者向けの方法です。

ブロックの種類

パイプラインは、あなたとのやり取りからこれらを分類して書き込み、エージェントはそれらを読み取ります。

エージェントによる読み取り方法

まずナビゲートし、次に検索します。ツリーですべてを確認できます。

workspace_tree                     # root view — projects + counts
workspace_filter(concepts)         # cold start: concepts → relevant roots
workspace_get(label, "relations")  # a block + its causal chain(s)
workspace_search(query)            # fallback: semantic + keyword + concept, ranked by match
workspace_stats(agent_id)          # graph landscape + extraction freshness + pending flags

単独のブロックは見出しにすぎません。物語を伝えるのはそのチェーンです。workspace_get は、そのブロックが属する名前付きの因果チェーンを返すため、1回の読み取りで流れ全体を把握できます。

検索結果は限界を正直に示します。各ヒットにはどのルートの配下にあるかと一致を示すシグナルが表示され、置き換えられたブロックには何に置き換えられたかが示されます。また、本当に一致するものがない場合は、答えを装うのではなく、その旨（弱い一致のみ）を伝えます。

効果を示す根拠

NodeDex は、実際の使われ方に即してテストしています。パイプラインを通じて推論を抽出 → グラフの健全性を確認 → エージェントが必要な情報にたどり着けるかを確認します。スコアから推測するのではなく、稼働中のグラフから読み取ります。

研究論文の導出をパイプラインに通した結果、論文ごとにブロックの種類別でどのような推論の痕跡を捉えたかを示します（グラフから直接読み取り）：

捕捉された構成は、情報源の推論スタイルを反映しています。上限導出の論文では 試す → 棄却する → 選ぶ → 制約する という流れになり（行き詰まり／制約が多い構成：53ブロック。うち dead-end が2件、decision が10件、constraint が5件、chain が8件）、簡潔な定理証明では 確立する → 結論を導く という流れになります（fact / chain が多い構成）。代表的な論文ではグラフは健全で、55ブロックのうちレビュー対象のフラグが付いたものは1件のみ、decision は根拠となる fact に接続され、孤立したルートはゼロでした。また、グラフをたどる（ツリー → ルート → decision → chain）ことで、文脈から切り離された断片ではなく、対象を絞った結果をその導出過程とともに取得できました。

RAG の合格率ではありません。 1回限りのベンチマークスコアは意図的に報告していません。受動的な「取得して注入する」呼び出しでは情報のたどり方を検証できないため、その数値はメモリではなく、エージェントのタスク遂行能力を測るものだからです。詳しい説明はこちら： docs/NODEDEX-MEMORY-MODEL.md。

エンジンの健全性：サーバーのテストは1319件中1319件すべて合格し、抽出 → グラフ → 検索をエンドツーエンドで検証しています。検証には、捕捉漏れ（確認応答に安全なウォッチャーのカーソル）、MCP の読み取りサーフェス自体（エージェントが受け取る内容。出典情報を含む）、セットアップの配線（実際には書き込まれていないのに書き込み済みとされた reflex を見逃さず、真実として扱わないこと）が含まれます。テストで証明されるのは仕組みが機能することです。このメモリによってあなたのエージェントの能力が測定可能なほど向上するかどうかは、引き続きユーザーと検証中の主張です。

NodeDex 自身にも適用しました。NodeDex を構築した Claude Code セッションの直近約50ターンをウォッチャーで捕捉し、223ブロックのグラフに抽出しました。忠実度は9/10と監査され、グラフには自身のバグ修正の経緯（decision、その置き換え対象となった dead-end、各種 constraint がすべて接続された状態）が正しく記録されていました。そのグラフを検索すると、関連するクエリでは15件中15件が有用なヒットを返し、関連しないクエリでは答えを装うのではなく、弱い一致 — グラフに該当する情報がない可能性がありますと明示されます。

自己メンテナンス

グラフはサーバー側で自動的にクリーンな状態に保たれます（エージェントによる作業は不要です）。

• 検出（$0）： 重複したブロック、捏造されたソースの引用、スキーマの不整合。
• 解決： サーバー側のレビュアーが明確なケースを自動的に統合します。判断できない本当に曖昧なケースは、エージェントに提示されます（workspace_stats で取得し、平易な言葉で確認します）。

インフラストラクチャ

バックアップ： 自動（reflect サイクル後に実行され、最近のスナップショットを ~/.nodedex/data/backups/ に保持します）。手動の場合は POST /api/admin/backup、エクスポートの場合は GET /api/export を使用します。

ドキュメント

全体のインデックスについては、docs/README.md を参照してください。

ライセンス

NodeDex は GNU AGPL-3.0 のもとでライセンスされています（LICENSE を参照）。自由に使用、変更、セルフホストできます。NodeDex を変更し、ネットワーク経由で他者に提供する場合、AGPL により、変更したソースを同じライセンスのもとで公開する必要があります。

商用ライセンス： AGPL のコピーレフト義務なしで NodeDex を使用する必要がある場合（たとえば、クローズドソース製品への組み込みや、変更内容を公開せずにホスト型サービスとして提供する場合）は、商用ライセンスを利用できます。[email protected] までお問い合わせください。

貢献は、簡易な CLA のもとで歓迎します。CONTRIBUTING.md を参照してください。