Skip to main content
Glama

fish_bridge

CI 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

Related 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 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)

(none — requires 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

  1. Ingest — reads raw chat turns from JSONL (Copilot), paste, or any file format

  2. Extract — LLM extracts typed nodes (questions, decisions, errors, tasks, skills, files) and edges

  3. Dedup — semantic similarity merges near-duplicates; conflict detection flags status reversals

  4. Compile — graph is compressed to ~300–800 token XML/markdown block

  5. Write — block is written to .github/copilot-instructions.md (or CLAUDE.md)

  6. Deliver — AI tool reads the file automatically on the next turn — no injection, no agent required

Documentation

License

MIT — see LICENSE

Available Tools

9 tools
add_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

    A4/5.0

    Scored across 9 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      Knowledge 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.
      6
      76
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Local-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.
      15
      44 npm
      9
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Obsidian-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.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      1
      MIT