fish-bridge-mcp
The fish-bridge-mcp server lets AI agents manage conversational context by building and querying a session-scoped knowledge graph. Here's what you can do:
Record conversation turns: Ingest user/assistant messages to incrementally update the session knowledge graph.
Retrieve full session context (
get_context): Return the compressed session graph as XML for AI recall.Get focused context (
get_focus): Query the graph with a natural language question to retrieve only the most relevant nodes and their neighborhood.Mark items resolved (
mark_resolved): Mark questions, tasks, or errors as resolved, with optional resolution notes.Add nodes manually (
add_node): Insert typed nodes (question, decision, concept, skill, file, error, or task) with a label, summary, and status.Export the session graph (
export_session): Serialize the full graph to a portable JSON string for backup or transfer.Import a prior session (
import_session): Merge a previously exported session graph into the current one, carrying forward decisions and reactivating deferred nodes.List deferred items (
list_deferred): Show all parked questions, tasks, decisions, and errors.Show active session thread (
show_active): Display open questions, pending tasks, active errors, and key decisions in plain text.
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
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 automaticallyInstall
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]" # everythingRelated MCP server: sessionmem
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 compileThat'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 |
| (none — requires Ollama) | qwen2.5:7b | ~85% | $0 |
|
| gemini-2.5-flash | ~95% | ~$0.0002 |
|
| gpt-4.1-mini | ~93% | ~$0.0003 |
|
| claude-opus-4-7 | ~97% | ~$0.002 |
|
| local+cloud | best | mixed |
Configure with:
fish-bridge config --backend gemini
# or set GEMINI_API_KEY / ANTHROPIC_API_KEY / OPENAI_API_KEY as env varsFull 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 geminiMCP 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 |
| VS Code Copilot JSONL transcript (auto-discovered) |
Paste |
| Any chat text — universal fallback |
Document |
| Markdown, JSON, YAML specs and ADRs |
Codebase |
| Git commits + README + HANDOVER |
Obsidian |
| Vault notes with wikilinks and frontmatter |
Session |
| Prior |
Deps |
| package.json, pyproject.toml, Cargo.toml, go.mod, Gemfile, pom.xml |
Test output |
| Jest JSON, pytest JSON, JUnit XML — error nodes per failing test |
IaC |
| Terraform, CDK (synth output), CloudFormation, docker-compose |
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(orCLAUDE.md)Deliver — AI tool reads the file automatically on the next turn — no injection, no agent required
Documentation
License
MIT — see LICENSE
Available Tools
9 toolsadd_nodeB
Manually add a node to the session graph.
Args: label: Short descriptive label (≤8 words). node_type: One of: question | decision | concept | skill | file | error | task summary: Optional 1-2 sentence description. status: Optional status (default depends on type).
Inputs: label (required), node_type, summary, status. Returns: result
export_sessionA
Return the full session graph as a JSON string.
Useful for saving a portable snapshot or importing into another session.
The JSON can be saved as a .chatgraph.json file and imported with
fish-bridge import <file>.
Inputs: no named parameters. Returns: result
get_contextA
Return the current compressed session context as XML.
This is the same content written to .github/copilot-instructions.md. Use this when you need to recall the session state mid-conversation.
Inputs: no named parameters. Returns: result
get_focusA
Return a query-scoped subgraph context XML.
Finds the nodes most relevant to query and their graph neighborhood. Use this for targeted technical questions where full session context is too broad.
Args: query: Natural language question or topic (e.g. "CORS headers configuration")
Inputs: query (required). Returns: result
import_sessionA
Load a prior session graph and merge it into the current session.
Pass the JSON content of a .chatgraph.json file (from export_session or
fish-bridge export). Deferred nodes from the prior session become active;
resolved and adopted decisions carry forward.
Returns a summary of how many nodes and edges were merged.
Inputs: json_str (required). Returns: result
list_deferredA
Return all deferred items in the current session as plain text.
Shows questions, tasks, decisions, and errors that have been parked.
Use mark_resolved or fish-bridge resolve to act on them.
Inputs: no named parameters. Returns: result
mark_resolvedB
Mark a question, task, or error as resolved.
Args: label: The label of the node to resolve (partial match, case-insensitive). note: Optional note explaining how it was resolved.
Inputs: label (required), note. Returns: result
record_turnA
Ingest one user/assistant exchange into the session graph.
Call this after each response in agent mode. The graph is updated incrementally — no full re-extraction required.
Returns a brief acknowledgement with node/edge counts.
Inputs: user_message (required), assistant_message (required). Returns: result
show_activeA
Return the active session thread as plain text (not XML).
Lists open questions, pending tasks, active errors, and key decisions.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool serves a distinct purpose within session graph management: adding nodes, exporting/importing, retrieving context, focusing on subgraphs, listing deferred items, marking resolved, recording turns, and showing active thread. No two tools overlap in function.
All 9 tools follow a consistent verb_noun pattern (e.g., add_node, export_session, get_context, list_deferred), using lowercase with underscores. No deviations or mixed conventions.
With 9 tools, the server is well-scoped for session graph management. Each tool addresses a core operation (add, retrieve, list, resolve, import/export, record), without unnecessary bloat or deficiency.
The tool set covers the main lifecycle: adding nodes, resolving them, recording turns, listing deferred items, and exporting/importing sessions. Minor gaps exist (e.g., no explicit update or delete node tool), but the core workflows are covered.
Related MCP Connectors
Compress coding-agent context ~64%. Hosted Neural Keep MCP for Cursor/Claude/Codex.
MCP-native notes and memory for ChatGPT, Claude, and other AI tools.
Shared AI memory. ChatGPT, Claude, Cursor and any MCP app read and write the same memory.
Private persistent memory for Claude, ChatGPT & Gemini via MCP - semantic search, zero-code setup.
Related MCP Servers
- AlicenseAqualityAmaintenanceKnowledge graph for token-efficient code reviews. Builds a structural map of your codebase with Tree-sitter, tracks changes incrementally, and gives AI agents precise context via MCP tools. Features fixed multi-word search, qualified call resolution, dual-mode embedding (ONNX local + LiteLLM cloud), and output pagination.676Apache 2.0
- AlicenseAqualityBmaintenanceLocal-first MCP server that watches your coding sessions and injects a compact summary at the start of each new session. 85.6% token reduction, SQLite storage, no cloud. Works with Claude Code, Cursor, Cline, and Windsurf.1544 npm9MIT
- AlicenseNot gradedqualityDmaintenanceObsidian-backed knowledge graph with semantic search, entity extraction, and cross-session memory. 11 MCP tools. Works with Claude Code, Cursor, Windsurf, and any MCP-compatible editor.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to retrieve hyper-targeted, token-efficient context from a codebase by querying a locally built AST knowledge graph, and to persist cross-session agent memory through 17 MCP tools. All indexing and retrieval run entirely offline, so proprietary code never leaves the machine.1MIT