fish-bridge — Session Knowledge Graph

fish_bridge

AI チャットのコンテキスト圧縮に対応した、セッション単位のナレッジグラフエンジンです。

生の AI チャット（40k 以上のトークン）を、コンパクトで型付きのナレッジグラフ（約 300～800 トークン）に変換し、.github/copilot-instructions.md または CLAUDE.md に書き込みます。これらのファイルは、あらゆるモード（質問、編集、エージェント）でのすべての AI ターンに自動的に含まれます。コアのワークフローに MCP サーバーは必要ありません。

Raw session (40k tokens) → [fish_bridge] → Compressed graph (350 tokens)
                                              written to copilot-instructions.md
                                              picked up by every AI turn automatically

インストール

uv をまだお持ちでない場合は、まずインストールしてください：curl -LsSf https://astral.sh/uv/install.sh | sh（macOS/Linux）、または uv のドキュメントをご覧ください。1 つのツールで pip + pipx + pyenv を置き換えられるため、仮想環境を管理する必要はありません。

推奨 — uv tool install（fish-bridge CLI と fish-bridge-mcp MCP サーバーの両方を PATH にインストールします）：

# Local Ollama backend — free, offline (requires Ollama running)
uv tool install fish-bridge-mcp

# Gemini backend (~$0.0002/turn, ~95% quality — recommended cloud option)
uv tool install "fish-bridge-mcp[gemini]"
export GEMINI_API_KEY=...

# Claude backend (~$0.002/turn, ~97% quality)
uv tool install "fish-bridge-mcp[claude]"
export ANTHROPIC_API_KEY=sk-ant-...

# OpenAI backend (~$0.0003/turn, ~93% quality)
uv tool install "fish-bridge-mcp[openai]"
export OPENAI_API_KEY=sk-...

# Everything
uv tool install "fish-bridge-mcp[all]"

インストール後、PATH から次の 2 つのコマンドを使用できます：

• fish-bridge — メイン CLI（ingest、compile、show、serve、...）
• fish-bridge-mcp — VS Code エージェントモード用の MCP サーバー

MCP 設定のみ（永続的なインストールは不要）： .vscode/mcp.json で uvx を直接使用します。必要に応じて MCP サーバーをダウンロードして実行します：

{ "command": "uvx", "args": ["fish-bridge-mcp"] }

完全な設定については、以下の MCP サーバーのセクションをご覧ください。

pip install fish-bridge-mcp
pip install "fish-bridge-mcp[gemini]"   # with Gemini backend
pip install "fish-bridge-mcp[claude]"   # with Claude backend
pip install "fish-bridge-mcp[all]"      # everything

2 分で始める

# 1. Initialize for your project
fish-bridge init --tool copilot --project ./

# 2. Ingest the latest Copilot session (auto-discovers JSONL on macOS/Linux/Windows)
fish-bridge ingest --source copilot

# 3. View the graph
fish-bridge show

# 4. Compile to your instructions file (done automatically after ingest)
fish-bridge compile

これで完了です。.github/copilot-instructions.md に、約 350 トークンに圧縮されたセッションの要約が含まれるようになり、今後のすべてのターンで生の履歴に置き換わります。

バックエンド

次のように設定します：

fish-bridge config --backend gemini
# or set GEMINI_API_KEY / ANTHROPIC_API_KEY / OPENAI_API_KEY as env vars

CLI リファレンス全文

# --- Session init ---
fish-bridge init                          # create session for current project
fish-bridge init --tool claude            # → writes to CLAUDE.md instead

# --- Ingest chat turns ---
fish-bridge ingest --source copilot       # auto-discover latest VS Code Copilot session
fish-bridge ingest --source copilot --session <id>  # target specific session
fish-bridge ingest --source paste         # paste any chat text — opens $EDITOR (universal fallback)
fish-bridge ingest --source file --file export.json  # from a saved export file
fish-bridge watch --source copilot        # tail JSONL, auto-update on new turns

# --- Merge external knowledge ---
fish-bridge merge --source document --file HANDOVER.md
fish-bridge merge --source codebase --path ./            # git log + README
fish-bridge merge --source obsidian --vault ~/notes
fish-bridge merge --source deps --path ./                # package.json / pyproject.toml etc.
fish-bridge merge --source testout --file results.json   # jest / pytest / JUnit
fish-bridge merge --source iac --path ./                 # Terraform / CDK / CloudFormation
fish-bridge merge --source openapi --file openapi.yaml
fish-bridge merge --source session --file prior.chatgraph.json

# --- Compile & view ---
fish-bridge compile                       # update instruction file (runs after ingest by default)
fish-bridge compile --mode digest         # full handover markdown
fish-bridge compile --mode focus --query "Redis caching"
fish-bridge show                          # pretty-print active nodes
fish-bridge show --all                    # include resolved/deferred items
fish-bridge serve                         # open Cytoscape.js graph viewer at localhost:8080
fish-bridge digest                        # generate handover digest

# --- Node management ---
fish-bridge resolve "DNC caching strategy"
fish-bridge defer "v16 index validation"
fish-bridge add "Use Redis for session cache" --type decision
fish-bridge conflict show
fish-bridge conflict resolve <node-id> --keep old

# --- Export / import / diff ---
fish-bridge export                        # save .chatgraph.json
fish-bridge import prior-session.chatgraph.json
fish-bridge diff session-a.chatgraph.json session-b.chatgraph.json

# --- Config ---
fish-bridge config --show
fish-bridge config --backend gemini

MCP サーバー（任意 — エージェントモードのみ）

MCP サーバーを使用すると、VS Code エージェントモードで record_turn によるリアルタイムの記録が可能になります。必須ではありません — 上記のファイルベースのワークフローは、MCP サーバーなしですべてのモードで動作します。

.vscode/mcp.json に追加します（uvx を使用するため、事前のインストールは不要です）：

{
  "servers": {
    "fish-bridge": {
      "command": "uvx",
      "args": ["fish-bridge-mcp"],
      "env": { "FISH_BRIDGE_BACKEND": "gemini", "GEMINI_API_KEY": "${env:GEMINI_API_KEY}" }
    }
  }
}

uv tool install fish-bridge-mcp を使用した場合は、インストール済みのバイナリを直接指定することもできます：

{ "command": "fish-bridge-mcp" }

Claude Desktop、Cursor、Windsurf の設定例については、examples/ をご覧ください。

MCP ツール：record_turn、get_context、get_focus、mark_resolved、add_node、export_session、import_session、show_active、list_deferred

ソースの取り込み

仕組み

1. 取り込み — JSONL（Copilot）、貼り付け、または任意のファイル形式からチャットの生のターンを読み取ります
2. 抽出 — LLM が型付きノード（質問、決定、エラー、タスク、スキル、ファイル）とエッジを抽出します
3. 重複排除 — 意味的類似性に基づいて重複に近い項目を統合し、競合検出によってステータスの反転を警告します
4. コンパイル — グラフを約 300～800 トークンの XML／Markdown ブロックに圧縮します
5. 書き込み — ブロックを .github/copilot-instructions.md（または CLAUDE.md）に書き込みます
6. 配信 — 次のターンで AI ツールがファイルを自動的に読み取ります — 注入もエージェントも不要です

ドキュメント

• クイックスタート
• 設定
• グラフスキーマ
• コンパイラーモード
• インジェスター

ライセンス

MIT — LICENSE を参照