{
  "markdown": "# fish_bridge\n\n<!-- mcp-name: io.github.MakeaMouse/fish-bridge-mcp -->\n\n[![CI](https://github.com/MakeaMouse/fish-bridge-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/MakeaMouse/fish-bridge-mcp/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/fish-bridge-mcp)](https://pypi.org/project/fish-bridge-mcp/)\n[![Python](https://img.shields.io/pypi/pyversions/fish-bridge-mcp)](https://pypi.org/project/fish-bridge-mcp/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n**Session-scoped knowledge graph engine for AI chat context compression.**\n\nConverts 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.\n\n```\nRaw session (40k tokens) → [fish_bridge] → Compressed graph (350 tokens)\n                                              written to copilot-instructions.md\n                                              picked up by every AI turn automatically\n```\n\n## Install\n\n> Don't have `uv`? Get it first: `curl -LsSf https://astral.sh/uv/install.sh | sh` (macOS/Linux) or see [uv docs](https://docs.astral.sh/uv/getting-started/installation/). It replaces pip + pipx + pyenv in one tool — no virtualenv management needed.\n\n**Recommended — `uv tool install`** (installs both the `fish-bridge` CLI and `fish-bridge-mcp` MCP server on your PATH):\n\n```bash\n# Local Ollama backend — free, offline (requires Ollama running)\nuv tool install fish-bridge-mcp\n\n# Gemini backend (~$0.0002/turn, ~95% quality — recommended cloud option)\nuv tool install \"fish-bridge-mcp[gemini]\"\nexport GEMINI_API_KEY=...\n\n# Claude backend (~$0.002/turn, ~97% quality)\nuv tool install \"fish-bridge-mcp[claude]\"\nexport ANTHROPIC_API_KEY=sk-ant-...\n\n# OpenAI backend (~$0.0003/turn, ~93% quality)\nuv tool install \"fish-bridge-mcp[openai]\"\nexport OPENAI_API_KEY=sk-...\n\n# Everything\nuv tool install \"fish-bridge-mcp[all]\"\n```\n\nAfter install, two commands are available on your PATH:\n- **`fish-bridge`** — the main CLI (`ingest`, `compile`, `show`, `serve`, ...)\n- **`fish-bridge-mcp`** — the MCP server for VS Code agent mode\n\n**MCP config only (no permanent install needed):** use `uvx` directly in your `.vscode/mcp.json` — it downloads and runs the MCP server on demand:\n\n```json\n{ \"command\": \"uvx\", \"args\": [\"fish-bridge-mcp\"] }\n```\n\nSee the [MCP server section](#mcp-server-optional--agent-mode-only) below for the full config.\n\n<details>\n<summary>Traditional pip install (for embedding fish-bridge as a library in your own Python project)</summary>\n\n```bash\npip install fish-bridge-mcp\npip install \"fish-bridge-mcp[gemini]\"   # with Gemini backend\npip install \"fish-bridge-mcp[claude]\"   # with Claude backend\npip install \"fish-bridge-mcp[all]\"      # everything\n```\n</details>\n\n## 2-minute quickstart\n\n```bash\n# 1. Initialize for your project\nfish-bridge init --tool copilot --project ./\n\n# 2. Ingest the latest Copilot session (auto-discovers JSONL on macOS/Linux/Windows)\nfish-bridge ingest --source copilot\n\n# 3. View the graph\nfish-bridge show\n\n# 4. Compile to your instructions file (done automatically after ingest)\nfish-bridge compile\n```\n\nThat's it. `.github/copilot-instructions.md` now contains a ~350-token compressed summary of your session, replacing raw history in every future turn.\n\n## Backends\n\n| Backend | Install extra | Model | Quality | Cost/turn |\n|---|---|---|---|---|\n| `local` (Ollama) | *(none — requires [Ollama](https://ollama.com))* | qwen2.5:7b | ~85% | $0 |\n| `gemini` | `[gemini]` | gemini-2.5-flash | ~95% | ~$0.0002 |\n| `openai` | `[openai]` | gpt-4.1-mini | ~93% | ~$0.0003 |\n| `claude` | `[claude]` | claude-opus-4-7 | ~97% | ~$0.002 |\n| `hybrid` | `[claude]` or `[openai]` | local+cloud | best | mixed |\n\nConfigure with:\n```bash\nfish-bridge config --backend gemini\n# or set GEMINI_API_KEY / ANTHROPIC_API_KEY / OPENAI_API_KEY as env vars\n```\n\n## Full CLI reference\n\n```bash\n# --- Session init ---\nfish-bridge init                          # create session for current project\nfish-bridge init --tool claude            # → writes to CLAUDE.md instead\n\n# --- Ingest chat turns ---\nfish-bridge ingest --source copilot       # auto-discover latest VS Code Copilot session\nfish-bridge ingest --source copilot --session <id>  # target specific session\nfish-bridge ingest --source paste         # paste any chat text — opens $EDITOR (universal fallback)\nfish-bridge ingest --source file --file export.json  # from a saved export file\nfish-bridge watch --source copilot        # tail JSONL, auto-update on new turns\n\n# --- Merge external knowledge ---\nfish-bridge merge --source document --file HANDOVER.md\nfish-bridge merge --source codebase --path ./            # git log + README\nfish-bridge merge --source obsidian --vault ~/notes\nfish-bridge merge --source deps --path ./                # package.json / pyproject.toml etc.\nfish-bridge merge --source testout --file results.json   # jest / pytest / JUnit\nfish-bridge merge --source iac --path ./                 # Terraform / CDK / CloudFormation\nfish-bridge merge --source openapi --file openapi.yaml\nfish-bridge merge --source session --file prior.chatgraph.json\n\n# --- Compile & view ---\nfish-bridge compile                       # update instruction file (runs after ingest by default)\nfish-bridge compile --mode digest         # full handover markdown\nfish-bridge compile --mode focus --query \"Redis caching\"\nfish-bridge show                          # pretty-print active nodes\nfish-bridge show --all                    # include resolved/deferred items\nfish-bridge serve                         # open Cytoscape.js graph viewer at localhost:8080\nfish-bridge digest                        # generate handover digest\n\n# --- Node management ---\nfish-bridge resolve \"DNC caching strategy\"\nfish-bridge defer \"v16 index validation\"\nfish-bridge add \"Use Redis for session cache\" --type decision\nfish-bridge conflict show\nfish-bridge conflict resolve <node-id> --keep old\n\n# --- Export / import / diff ---\nfish-bridge export                        # save .chatgraph.json\nfish-bridge import prior-session.chatgraph.json\nfish-bridge diff session-a.chatgraph.json session-b.chatgraph.json\n\n# --- Config ---\nfish-bridge config --show\nfish-bridge config --backend gemini\n```\n\n## MCP server (optional — agent mode only)\n\nThe 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.\n\nAdd to `.vscode/mcp.json` (uses `uvx` — no prior install needed):\n```json\n{\n  \"servers\": {\n    \"fish-bridge\": {\n      \"command\": \"uvx\",\n      \"args\": [\"fish-bridge-mcp\"],\n      \"env\": { \"FISH_BRIDGE_BACKEND\": \"gemini\", \"GEMINI_API_KEY\": \"${env:GEMINI_API_KEY}\" }\n    }\n  }\n}\n```\n\nIf you used `uv tool install fish-bridge-mcp`, you can also reference the installed binary directly:\n```json\n{ \"command\": \"fish-bridge-mcp\" }\n```\n\nSee `examples/` for Claude Desktop, Cursor, and Windsurf configs.\n\n**MCP tools**: `record_turn`, `get_context`, `get_focus`, `mark_resolved`, `add_node`, `export_session`, `import_session`, `show_active`, `list_deferred`\n\n## Ingest sources\n\n| Source | Command | What it ingests |\n|---|---|---|\n| Copilot | `ingest --source copilot` | VS Code Copilot JSONL transcript (auto-discovered) |\n| Paste | `ingest --source paste` | Any chat text — universal fallback |\n| Document | `merge --source document` | Markdown, JSON, YAML specs and ADRs |\n| Codebase | `merge --source codebase` | Git commits + README + HANDOVER |\n| Obsidian | `merge --source obsidian` | Vault notes with wikilinks and frontmatter |\n| Session | `merge --source session` | Prior `.chatgraph.json` export |\n| Deps | `merge --source deps` | package.json, pyproject.toml, Cargo.toml, go.mod, Gemfile, pom.xml |\n| Test output | `merge --source testout` | Jest JSON, pytest JSON, JUnit XML — error nodes per failing test |\n| IaC | `merge --source iac` | Terraform, CDK (synth output), CloudFormation, docker-compose |\n| OpenAPI | `merge --source openapi` | OpenAPI 3.x / Swagger 2.0 / AsyncAPI specs |\n\n## How it works\n\n1. **Ingest** — reads raw chat turns from JSONL (Copilot), paste, or any file format\n2. **Extract** — LLM extracts typed nodes (questions, decisions, errors, tasks, skills, files) and edges\n3. **Dedup** — semantic similarity merges near-duplicates; conflict detection flags status reversals\n4. **Compile** — graph is compressed to ~300–800 token XML/markdown block\n5. **Write** — block is written to `.github/copilot-instructions.md` (or `CLAUDE.md`)\n6. **Deliver** — AI tool reads the file automatically on the next turn — no injection, no agent required\n\n## Documentation\n\n- [Quickstart](docs/quickstart.md)\n- [Configuration](docs/configuration.md)\n- [Graph schema](docs/graph-schema.md)\n- [Compiler modes](docs/compiler-modes.md)\n- [Ingestors](docs/ingestors.md)\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n",
  "bytes": 9032,
  "sha": "4701926e139dce83002a9de1a989ca0fdb84b196e569fd893587da0335b132b2",
  "repo_slug": "makeamouse/fish-bridge-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_makeamouse_fish_bridge_mcp_9187b00c/readme"
}