docdex

Docdex

リポジトリを、人間と AI が信頼できる、高速でプライベートなコンテキストに変えます。

Docdex は、ドキュメントとソースコード向けのローカルファーストなインデクサー兼検索デーモンです。生のファイルと AI アシスタントの間で動作し、コードをクラウドのベクトルストアにアップロードすることなく、決定的な検索、コードインテリジェンス、永続的なメモリを提供します。

⚡ Docdex を選ぶ理由

多くの AI ツールは「grep」（高速ですが単純）や、ホスト型 RAG（低速で、アップロードが必要）に依存しています。Docdex はローカルで動作し、コードの構造を理解して、AI エージェントに永続的なメモリを提供します。

課題	一般的な方法	Docdex の解決策
コンテキストの検索	grep/rg（ノイズが多く、文字どおりの一致）	意図に基づくランキング済みの構造化された結果
コードのプライバシー	ホスト型 RAG（コードのアップロードが必要）	**ローカルのみでインデックスを作成。**コードはお使いのマシンから外に出ません。
分断された検索	IDE 専用の検索バー	CLI、HTTP、MCP クライアントに同時に対応する共有デーモン
コードの認識	文字列の照合	依存関係と定義を理解するためのAST と影響グラフ

---

🚀 機能

• **📚 ドキュメントのインデックス作成：**リポジトリのドキュメントをすばやくランキングし、要約します。
• **🧠 AST と影響グラフ：**関数の意図に基づいて検索し、下流の依存関係を追跡します（Rust、Python、JS/TS、Go、Java、C++ などに対応）。
• **💾 リポジトリメモリ：**プロジェクトの事実、決定事項、メモをローカルに保存します。
• **👤 エージェントメモリ：**異なるリポジトリ間で、ユーザーの好み（例：「簡潔な箇条書きを使う」）を記憶します。
• **🗂️ 会話メモリ：**トランスクリプトをインポートし、起動時のバンドルを簡潔に保ち、リポジトリ単位の要約、日記の記録、作業メモリを生成します。
• **🕸️ 時間的ナレッジグラフ：**アーカイブされた会話からエンティティ、エッジ、エピソード、コード関連のリンクを抽出し、タイムラインや近傍のクエリに対応します。
• **🧭 起動時 + プロジェクトマップのコンテキスト：**簡潔な起動時バンドル、プロファイルの正確な情報、キャッシュされた Project map: コンテキストを OpenAI 互換のチャット補完に挿入します。
• **🔌 MCP ネイティブ：**Claude Desktop、Cursor、Windsurf などのツール向けに自動設定します。
• **🌐 ウェブ情報の拡充：**検出されたローカル LLM サービスを通じて、ローカル LLM でフィルタリングする任意のウェブ検索に対応します。

---

📦 インストールしたらあとはおまかせ

一度インストールして、エージェントから Docdex を指定すれば、バックグラウンドで動作し続けます。

1. npm でインストール（推奨）

Node.js >= 18 が必要です。お使いの OS（macOS、Linux、Windows）に適したバイナリがダウンロードされます。

npm i -g docdex

警告

**Windows の要件：**Docdex は MSVC ランタイムを使用します。docdex/docdexd の実行前に、Microsoft Visual C++ Redistributable 2015-2022 (x64) をインストールしてください。

• Winget：winget install --id Microsoft.VCRedist.2015+.x64
• 手動：Microsoft から vc_redist.x64.exe をダウンロードします：https://aka.ms/vs/17/release/vc_redist.x64.exe
• docdexd が 0xC0000135 で終了する場合、ランタイムが不足しています。

2. 自動設定

次のクライアントがインストールされている場合、Docdex はローカル MCP エンドポイント（デーモン HTTP/SSE）を使用するように自動設定します。

Claude Desktop、Cursor、Windsurf、Cline、Roo Code、Continue、VS Code、PearAI、Void、Zed、Codex。

注：インストール後に AI クライアントを再起動してください。

---

🛠️ 使用ワークフロー

1. リポジトリのインデックスを作成

インデックスとグラフデータを作成するために、一度だけ実行します。

docdexd index --repo /path/to/my-project

2. デーモンを起動

共有サーバーを起動します。HTTP リクエストと MCP 接続を処理します。

docdex start
# or: docdexd daemon --host 127.0.0.1 --port 28491

3. 質問する（CLI）

ターミナルから直接チャットできます。

docdexd chat --repo /path/to/my-project --query "how does auth work?"

---

🔌 Model Context Protocol (MCP)

Docdex は、AI エージェントの「頭脳」となるように設計されています。エージェントが接続する MCP エンドポイントを公開します。

アーキテクチャ

flowchart LR
  Repo[Repo on disk] --> Indexer[Docdex Indexer]
  Indexer --> Daemon[Docdex Daemon]
  Daemon -->|HTTP + SSE| MCPClient[MCP Client]
  MCPClient --> Host[AI Agent / Editor]

デーモンの HTTP/SSE エンドポイントを使用してください。サンドボックス化されたクライアント向けに、Docdex はローカル IPC（Unix ソケットまたは Windows 名前付きパイプ）経由で MCP を提供することもできますが、ほとんどの MCP クライアントでは HTTP/SSE がデフォルトです。

手動設定

クライアントを手動で設定する必要がある場合：

JSON（Claude/Cursor/Continue）：

{
  "mcpServers": {
    "docdex": {
      "url": "http://127.0.0.1:28491/v1/mcp/sse"
    }
  }
}

Claude Code（CLI）JSON（~/.claude.json またはプロジェクトの .mcp.json）：

{
  "mcpServers": {
    "docdex": {
      "type": "http",
      "url": "http://127.0.0.1:28491/v1/mcp"
    }
  }
}

TOML（Codex）：

[mcp_servers.docdex]
url = "http://127.0.0.1:28491/v1/mcp"
tool_timeout_sec = 300
startup_timeout_sec = 300

---

🤖 機能と使用例

1. AST と影響分析

「addressGenerator」という文字列を見つけるだけではありません。定義と、それが与える影響も見つけます。

# Find definition
curl "http://127.0.0.1:28491/v1/ast?name=addressGenerator&pathPrefix=src"

# Track downstream impact (what breaks if I change this?)
curl "http://127.0.0.1:28491/v1/graph/impact?file=src/app.ts&maxDepth=3"

2. メモリーシステム

Docdex では「事実」を保存でき、検索によって後から呼び出せます。

リポジトリのメモリー（プロジェクト固有）：

# Teach the repo a fact
docdexd memory-store --repo . --text "Payments retry up to 3 times with backoff."

# Recall it later
docdexd memory-recall --repo . --query "payments retry policy"

エージェントのメモリー（ユーザー設定）：

# Set a style preference
docdexd profile add --agent-id "default" --category style --content "Use concise bullet points."

3. 会話メモリー

会話メモリーはデフォルトでリポジトリ単位で管理され、任意で有効にできます。リポジトリに属さないセッションでは、リポジトリアーカイブが暗黙的に再利用されないよう、明示的な会話名前空間を使用する必要があります。このサブシステムはトランスクリプトをインポートし、エピソード要約と作業メモリーを保存し、日記エントリーと時間情報を含む KG ファクトを knowledge.db に生成します。また、厳格な起動時予算の範囲内で想起を行います。

CLI のアーカイブ、日記、フックの各コマンドは HTTP を利用するラッパーです。そのため、先に docdex start または docdexd daemon を起動してください。

# Archive and inspect transcripts
docdexd conversations import --repo . ./session.txt --format plain_text --agent-id codex
docdexd conversations list --repo . --agent-id codex
docdexd conversations search --repo . "timeline_index"
docdexd conversations read --repo . <session_id>

# Import into an explicit global conversation namespace instead of a repo archive
docdexd conversations import --conversation-namespace shared-team ./session.txt --format plain_text --agent-id codex
docdexd conversations search --conversation-namespace shared-team "timeline_index"

# Keep agent diary notes alongside imported sessions
docdexd diary write --repo . --agent-id codex "Wake-up rollout validated against knowledge.db timeline output."
docdexd diary read --repo . --agent-id codex

# Trigger durable summarization from an external transcript
docdexd hook conversation --repo . \
  --action session_close_summarization \
  --source codex \
  --agent-id codex \
  --transcript ./session.txt \
  --format plain_text \
  --wait-for-processing

# Build a compact wake-up bundle over recent context
curl -X POST http://127.0.0.1:28491/v1/wakeup \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"codex","query":"timeline_index","max_tokens":96}'

# Address the same archive over HTTP without repo_id
curl -X POST http://127.0.0.1:28491/v1/wakeup \
  -H "Content-Type: application/json" \
  -H "x-docdex-conversation-namespace: shared-team" \
  -d '{"agent_id":"codex","query":"timeline_index","max_tokens":96}'

# Explore derived repo-scoped knowledge facts and provenance
curl "http://127.0.0.1:28491/v1/kg/query?q=knowledge.db&limit=10"
curl "http://127.0.0.1:28491/v1/kg/search/nodes?q=knowledge&limit=10"
curl "http://127.0.0.1:28491/v1/kg/neighborhood?entity=knowledge.db&limit=10"
curl "http://127.0.0.1:28491/v1/kg/timeline?entity=knowledge.db&limit=10"

# Chat with wake-up + project-map context and inspect reasoning trace metadata
curl -X POST http://127.0.0.1:28491/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fake-model",
    "messages": [{"role": "user", "content": "What changed around knowledge.db?"}],
    "docdex": {
      "agent_id": "codex",
      "limit": 6,
      "include_libs": true,
      "dag_session_id": "session-123"
    }
  }'

4. ローカル LLM サービス

Docdex は、インストールを提案する前に、サポート対象のローカル LLM サービスを検出します。すでに利用できる場合は、Ollama、vLLM、llama.cpp と互換性のある OpenAI エンドポイント、LM Studio、LocalAI、SGLang、TGI 互換のデプロイメント、および正常なローカル mcoda エージェントを再利用できます。Ollama は、ガイド付きセットアップが最も簡単なため、引き続き推奨されるフォールバックです。

• セットアップ： docdex setup を実行すると、検出されたサービス、モデル、埋め込み候補、ローカル委任エージェントを一覧表示する対話型ウィザードが起動します。
• 確認： docdexd llm detect --json または docdexd llm diagnostics --json を実行すると、サービス／モデルが選択、スキップ、または異常と判定された理由を確認できます。
• Ollama の手動フォールバック： 利用可能なサービスがインストールされていない場合は、ollama pull nomic-embed-text を実行してフォールバック用の埋め込みモデルを取得します。
• カスタム Ollama URL：

DOCDEX_OLLAMA_BASE_URL=http://127.0.0.1:11434 docdex start --host 127.0.0.1 --port 28491

---

⚙️ 設定と HTTP API

Docdex は、以下を提供するローカルデーモンとして動作します。

• CLI コマンド： docdexd chat
• HTTP API： /search、/v1/capabilities、/v1/search/rerank、/v1/search/batch、/v1/chat/completions、/v1/ast、/v1/graph/impact、/v1/conversations/*、/v1/diary/*、/v1/hooks/conversation、/v1/wakeup、/v1/kg/*
• MCP エンドポイント： /v1/mcp および /v1/mcp/sse
• 機能ネゴシエーションツール： docdex_capabilities、docdex_rerank、docdex_batch_search、docdex_conversation_*、docdex_diary_*、docdex_conversation_hook、docdex_wakeup、docdex_kg_*

複数リポジトリのセットアップ

単一のデーモンを実行し、必要に応じて追加のリポジトリをマウントします。

docdex start --port 28491

# Mount repos and capture repo_id values
curl -X POST "http://127.0.0.1:28491/v1/initialize" \
  -H "Content-Type: application/json" \
  -d '{"rootUri":"file:///path/to/repo-a"}'

curl -X POST "http://127.0.0.1:28491/v1/initialize" \
  -H "Content-Type: application/json" \
  -d '{"rootUri":"file:///path/to/repo-b"}'

注意：

• 複数のリポジトリがマウントされている場合（またはデフォルトのリポジトリを指定せずにデーモンを起動した場合）、HTTP リクエストに x-docdex-repo-id: <sha256> を含めてください。
• MCP セッションは initialize.rootUri で指定されたリポジトリにバインドされ、そのリポジトリを自動的に再利用します。

セキュリティ

• セキュアモード： デフォルトでは、Docdex はループバック以外のバインドで TLS を強制します。
• ループバック： 127.0.0.1 は、ローカルエージェントであれば TLS なしでアクセスできます。
• ネットワークに公開する場合（注意して使用してください）は、--expose と --auth-token を使用します。

---

📚 詳細情報

• 詳細な使用方法： docs/usage.md
• API リファレンス： docs/http_api.md
• MCP 仕様： docs/mcp/errors.md