Which integrations are available for this server?

Allows ingesting Docker Compose files to incorporate infrastructure context into the knowledge graph. Allows ingesting Jest test output to add error nodes for failing tests and integrate test results into the session graph. Enables merging notes from an Obsidian vault, including wikilinks and frontmatter, into the knowledge graph. Provides a local backend for offline knowledge graph extraction using Ollama models (e.g., qwen2.5:7b). Provides a cost-effective backend for knowledge graph extraction using OpenAI's GPT-4.1-mini model. Allows ingesting pytest test output to add error nodes for failing tests and integrate test results into the session graph. Allows ingesting Swagger 2.0 API specifications as part of the OpenAPI merge source to incorporate API documentation into the graph. Enables ingesting Terraform infrastructure-as-code files to add infrastructure context to the knowledge graph.

fish_bridge

PyPI Python License: MIT

Session-scoped knowledge graph engine for AI chat context compression.

Converts raw AI chat (40k+ tokens) into a compact typed knowledge graph (~300–800 tokens) and writes it to .github/copilot-instructions.md or CLAUDE.md — automatically included in every AI turn across all modes (ask, edit, agent). No MCP server required for the core workflow.

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

Install

Don't have uv? Get it first: curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux) or see uv docs. It replaces pip + pipx + pyenv in one tool — no virtualenv management needed.

Recommended — uv tool install (installs both the fish-bridge CLI and fish-bridge-mcp MCP server on your 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]"

After install, two commands are available on your PATH:

fish-bridge — the main CLI (ingest, compile, show, serve, ...)
fish-bridge-mcp — the MCP server for VS Code agent mode

MCP config only (no permanent install needed): use uvx directly in your .vscode/mcp.json — it downloads and runs the MCP server on demand:

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

See the MCP server section below for the full config.

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-minute quickstart

# 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

That's it. .github/copilot-instructions.md now contains a ~350-token compressed summary of your session, replacing raw history in every future turn.

Backends

Backend	Install extra	Model	Quality	Cost/turn
`local` (Ollama)		qwen2.5:7b	~85%	$0
`gemini`	`[gemini]`	gemini-2.5-flash	~95%	~$0.0002
`openai`	`[openai]`	gpt-4.1-mini	~93%	~$0.0003
`claude`	`[claude]`	claude-opus-4-7	~97%	~$0.002
`hybrid`	`[claude]` or `[openai]`	local+cloud	best	mixed

Configure with:

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

Full CLI reference

# --- 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 server (optional — agent mode only)

The MCP server adds real-time record_turn capture when using VS Code agent mode. It is not required — the file-based workflow above works in all modes without it.

Add to .vscode/mcp.json (uses uvx — no prior install needed):

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

If you used uv tool install fish-bridge-mcp, you can also reference the installed binary directly:

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

See examples/ for Claude Desktop, Cursor, and Windsurf configs.

MCP tools: record_turn, get_context, get_focus, mark_resolved, add_node, export_session, import_session, show_active, list_deferred

Ingest sources

Source	Command	What it ingests
Copilot	`ingest --source copilot`	VS Code Copilot JSONL transcript (auto-discovered)
Paste	`ingest --source paste`	Any chat text — universal fallback
Document	`merge --source document`	Markdown, JSON, YAML specs and ADRs
Codebase	`merge --source codebase`	Git commits + README + HANDOVER
Obsidian	`merge --source obsidian`	Vault notes with wikilinks and frontmatter
Session	`merge --source session`	Prior `.chatgraph.json` export
Deps	`merge --source deps`	package.json, pyproject.toml, Cargo.toml, go.mod, Gemfile, pom.xml
Test output	`merge --source testout`	Jest JSON, pytest JSON, JUnit XML — error nodes per failing test
IaC	`merge --source iac`	Terraform, CDK (synth output), CloudFormation, docker-compose
OpenAPI	`merge --source openapi`	OpenAPI 3.x / Swagger 2.0 / AsyncAPI specs

How it works

Ingest — reads raw chat turns from JSONL (Copilot), paste, or any file format
Extract — LLM extracts typed nodes (questions, decisions, errors, tasks, skills, files) and edges
Dedup — semantic similarity merges near-duplicates; conflict detection flags status reversals
Compile — graph is compressed to ~300–800 token XML/markdown block
Write — block is written to .github/copilot-instructions.md (or CLAUDE.md)
Deliver — AI tool reads the file automatically on the next turn — no injection, no agent required

Documentation

License

MIT — see LICENSE

fish-bridge-mcp