fish-bridge — Session Knowledge Graph

io.github.MakeaMousePublished by GitHub account MakeaMousev0.1.3Updated Oct 24, 2026

Compresses AI chat sessions into a typed knowledge graph. Local/offline via Ollama.

VerifiedSTDIODesktop onlyKnowledge & MemoryDeveloper ToolsAI & ML

Overview

AI-generated overview

Local MCP server that compresses AI chat sessions into a typed knowledge graph and writes a compact context block into project instruction files.

What you can do
Record chat turns into a session knowledge graph in real time during agent mode, with an optional LLM extraction backend doing the typing and deduplication. Read back the current context, the focused subset, and the list of active or deferred nodes. Add nodes, mark items resolved, and export or import session graphs as files. The companion CLI ingests Copilot transcripts, pasted text, documents, codebases, dependency files, test output, IaC and OpenAPI specs, then compiles the graph into copilot-instructions.md or CLAUDE.md.
When to use it
Useful when long AI chat sessions need to be carried across turns or tools without resending tens of thousands of tokens, and when you want decisions, tasks and errors kept as a structured, editable graph in the project's instruction file. The MCP server itself is optional for the file-based workflow.
Requirements
Runs locally as a Python package (fish-bridge-mcp) via uv, uvx or pip; desktop only. An extraction backend is needed: local Ollama, or a cloud backend configured with ANTHROPIC_API_KEY, GEMINI_API_KEY or OPENAI_API_KEY. Cloud backends incur per-turn costs.
Before you install
Cloud backends send chat content to Anthropic, Google or OpenAI and cost money per turn; the local Ollama backend avoids both. The server writes into project files such as .github/copilot-instructions.md or CLAUDE.md, which are then included in every AI turn, so review what gets written. API keys are read from environment variables.

Installation

In SourceWeft

  1. Open fish-bridge — Session Knowledge Graph in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

bash
# 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-...
# Everythinguv 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:

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

See the MCP server section below for the full config.

Traditional pip install (for embedding fish-bridge as a library in your own Python project)
bash
pip install fish-bridge-mcppip install "fish-bridge-mcp[gemini]"   # with Gemini backendpip install "fish-bridge-mcp[claude]"   # with Claude backendpip install "fish-bridge-mcp[all]"      # everything

2-minute quickstart

bash
# 1. Initialize for your projectfish-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 graphfish-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

BackendInstall extraModelQualityCost/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+cloudbestmixed

Configure with:

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

Full CLI reference

bash
# --- Session init ---fish-bridge init                          # create session for current projectfish-bridge init --tool claude            # → writes to CLAUDE.md instead
# --- Ingest chat turns ---fish-bridge ingest --source copilot       # auto-discover latest VS Code Copilot sessionfish-bridge ingest --source copilot --session <id>  # target specific sessionfish-bridge ingest --source paste         # paste any chat text — opens $EDITOR (universal fallback)fish-bridge ingest --source file --file export.json  # from a saved export filefish-bridge watch --source copilot        # tail JSONL, auto-update on new turns
# --- Merge external knowledge ---fish-bridge merge --source document --file HANDOVER.mdfish-bridge merge --source codebase --path ./            # git log + READMEfish-bridge merge --source obsidian --vault ~/notesfish-bridge merge --source deps --path ./                # package.json / pyproject.toml etc.fish-bridge merge --source testout --file results.json   # jest / pytest / JUnitfish-bridge merge --source iac --path ./                 # Terraform / CDK / CloudFormationfish-bridge merge --source openapi --file openapi.yamlfish-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 markdownfish-bridge compile --mode focus --query "Redis caching"fish-bridge show                          # pretty-print active nodesfish-bridge show --all                    # include resolved/deferred itemsfish-bridge serve                         # open Cytoscape.js graph viewer at localhost:8080fish-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 decisionfish-bridge conflict showfish-bridge conflict resolve <node-id> --keep old
# --- Export / import / diff ---fish-bridge export                        # save .chatgraph.jsonfish-bridge import prior-session.chatgraph.jsonfish-bridge diff session-a.chatgraph.json session-b.chatgraph.json
# --- Config ---fish-bridge config --showfish-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):

json
{  "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:

json
{ "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

SourceCommandWhat it ingests
Copilotingest --source copilotVS Code Copilot JSONL transcript (auto-discovered)
Pasteingest --source pasteAny chat text — universal fallback
Documentmerge --source documentMarkdown, JSON, YAML specs and ADRs
Codebasemerge --source codebaseGit commits + README + HANDOVER
Obsidianmerge --source obsidianVault notes with wikilinks and frontmatter
Sessionmerge --source sessionPrior .chatgraph.json export
Depsmerge --source depspackage.json, pyproject.toml, Cargo.toml, go.mod, Gemfile, pom.xml
Test outputmerge --source testoutJest JSON, pytest JSON, JUnit XML — error nodes per failing test
IaCmerge --source iacTerraform, CDK (synth output), CloudFormation, docker-compose
OpenAPImerge --source openapiOpenAPI 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

Source: README.md at commit e995e56

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.3LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts