fish-bridge — Session Knowledge Graph

fish_bridge

面向 AI 聊天上下文压缩的会话级知识图谱引擎。

将原始 AI 聊天记录（40k+ 个 token）转换为精简的类型化知识图谱（约 300–800 个 token），并写入 .github/copilot-instructions.md 或 CLAUDE.md——在所有模式（ask、edit、agent）下自动包含在每轮 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 文档。它用一个工具替代 pip + pipx + pyenv——无需管理虚拟环境。

推荐——uv tool install（会在 PATH 中同时安装 fish-bridge CLI 和 fish-bridge-mcp MCP 服务）：

# 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 中会有两个可用命令：

• fish-bridge——主 CLI（ingest、compile、show、serve 等）
• fish-bridge-mcp——用于 VS Code Agent 模式的 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 个 token），可在之后的每轮对话中替代原始历史记录。

后端

配置方法：

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 服务（可选——仅用于 Agent 模式）

使用 VS Code Agent 模式时，MCP 服务会增加实时 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. 提取 — 大模型提取带类型的节点（问题、决策、错误、任务、技能、文件）和边
3. 去重 — 语义相似度用于合并近似重复项；冲突检测会标记状态反转
4. 编译 — 将图压缩为约 300–800 个 token 的 XML/Markdown 块
5. 写入 — 将块写入 .github/copilot-instructions.md（或 CLAUDE.md）
6. 交付 — AI 工具会在下一轮自动读取该文件——无需注入，也无需 Agent

文档

• 快速入门
• 配置
• 图架构
• 编译模式
• 接入器

许可证

MIT——详见 LICENSE