{
  "markdown": "<!-- mcp-name: io.github.ThunderEagle/context-bridge -->\n# ContextBridge\n\nA zero-dependency MCP memory server for Windows that gives AI coding assistants a shared, persistent memory layer with semantic search.\n\n## What is ContextBridge?\n\nAI coding assistants like Claude Code are stateless—each session starts fresh, with no persistent memory of your prior context, decisions, or discoveries. ContextBridge solves this by running as a background Windows Service that all your AI tools connect to. It stores memories persistently, searchable by meaning (not keywords), so context accumulates across sessions and across different tools simultaneously.\n\n## Why ContextBridge?\n\n- **Zero external dependencies** — No Docker, Postgres, Python, or Ollama. Everything runs in one Windows Service process.\n- **In-process embeddings** — Embedding model (all-MiniLM-L6-v2, ~22 MB) runs via ONNX Runtime; no external API calls.\n- **Single-file storage** — SQLite database at `%ProgramData%\\ContextBridge\\memories.db`. Backup is one file copy.\n- **Shared across tools** — Claude Code (HTTP), Claude Desktop (stdio), Cline, VS Code Chat Agents all connect to the same memory store in real-time.\n- **Memory survives service restarts** — Memories persist in SQLite; the embedding model loads once on startup and stays warm.\n\n## Requirements\n\n- **Windows 10 / Windows 11** (required for Windows Service integration)\n- **Option A:** .NET 10 SDK (if installing via `dotnet tool`)\n- **Option B:** Windows 10+ (no additional prerequisites if downloading a pre-built .exe)\n- **Admin PowerShell** (required to install/uninstall the Windows Service)\n\n## Quick Start\n\n### Option A: Install via dotnet global tool\n\nIf you have the .NET 10 SDK installed:\n\n```powershell\ndotnet tool install -g ThunderEagle.ContextBridge\n```\n\nThis places a `context-bridge` executable on your system PATH.\n\n### Option B: Direct download\n\nDownload a pre-built executable from [GitHub Releases](https://github.com/ThunderEagle/context-bridge/releases) (no SDK required; one-time SmartScreen warning). Add the `.exe` to your PATH or invoke it directly.\n\n### First-run setup\n\nRun these two commands in **admin PowerShell** (right-click → \"Run as Administrator\"):\n\n```powershell\n# 1. Download the embedding model, register as Windows Service, start it\ncontext-bridge service install\n\n# 2. Configure your AI tools to connect\ncontext-bridge configure\n```\n\n**What happens:**\n1. `service install` downloads the embedding model (~22 MB), registers the Windows Service, sets it to auto-start on boot, and starts it immediately.\n2. `configure` auto-detects installed clients (Claude Code, Claude Desktop, Cline, VS Code Chat) and wires them up to connect to the service.\n\nThe service now runs in the background. Your AI tools will see the memory store the next time you restart them.\n\n**Verify the service is running:**\n\n```powershell\nGet-Service ContextBridge\n```\n\nExpected output: `Status = Running`\n\n## Supported Clients\n\n| Client | Transport | Version | Notes |\n|---|---|---|---|\n| **Claude Code** | HTTP | Latest | Auto-configured by `context-bridge configure` |\n| **Claude Desktop** | stdio | Latest | Auto-configured via `claude_desktop_config.json` |\n| **Cline** (VS Code) | HTTP | Latest | Auto-configured by `context-bridge configure` |\n| **VS Code Chat Agents** | HTTP | 1.99+ | Auto-configured by `context-bridge configure` |\n\nAll clients share the same SQLite database via concurrent connections; memories written by one tool are immediately visible to others.\n\n## MCP Tools\n\nContextBridge exposes seven MCP tools for your AI assistants to use:\n\n| Tool | Purpose |\n|---|---|\n| `memory_write` | Store a single memory with automatic semantic embedding and optional tags |\n| `memory_batch_write` | Store multiple related memories atomically (efficient end-of-session extraction) |\n| `memory_search` | Semantic search — natural language query, returns nearest-neighbor results |\n| `memory_list` | Paginated list of all memories with optional tag filters |\n| `memory_update` | Update a memory's content (re-embedded automatically) |\n| `memory_delete` | Delete a memory by ID |\n| `memory_status` | Service health check, record count, model info |\n\n**Tag conventions** (optional; assigned by the AI tool):\n- `project:<repo-name>` — scope memories to a project\n- `type:decision` — architectural or technology choices\n- `type:preference` — coding style, tooling, workflow preferences\n- `type:pattern` — recurring patterns or conventions\n- `type:reference` — pointers to external resources or documentation\n\n## Handoff — Resuming Sessions\n\nMemories are permanent facts. A **handoff** is something different: ephemeral session state that lets you resume where you left off in a future session, without reloading conversation history.\n\n### How it works\n\n**At the end of a session**, ask your AI assistant to save its state:\n\n> \"Save a handoff for project context-bridge with what we were working on.\"\n\nThe model calls `handoff_write` with a summary of current work — decisions made, next steps, open questions — scoped to the project.\n\n**At the start of the next session**, the model calls `handoff_list` automatically (via server instructions) and incorporates any prior handoff as its opening context. It then calls `handoff_acknowledge` to remove the handoff once processed.\n\n### Handoff tools\n\n| Tool | Purpose |\n|---|---|\n| `handoff_write` | Capture session state — what you're working on, decisions made, next steps |\n| `handoff_list` | Retrieve active handoffs, optionally filtered by project |\n| `handoff_acknowledge` | Remove a handoff after processing it (permanent deletion) |\n\n**Key parameters for `handoff_write`:**\n- `content` — the session summary (free-form text)\n- `project` — project identifier, e.g. `context-bridge` (optional but recommended)\n- `ttl_days` — how many days to keep the handoff before auto-expiry (default: 7)\n\n### Handoffs vs. memories\n\n| | Memories | Handoffs |\n|---|---|---|\n| **Purpose** | Durable facts, decisions, preferences | Ephemeral \"where I was\" snapshots |\n| **Lifespan** | Permanent (until explicitly deleted) | TTL-bounded (default 7 days) |\n| **Search** | Semantic search via `memory_search` | Exact lookup via `handoff_list` |\n| **Cleanup** | `memory_delete` | `handoff_acknowledge` (or TTL expiry) |\n\nDo not convert handoff content to memories automatically. Memories are for facts that will remain true indefinitely. If something from a resumed session rises to that level, write it via `memory_write` separately.\n\n### Explicit resumption\n\nIf your MCP client supports the prompts capability (e.g. Claude Code), you can trigger a session resumption explicitly:\n\n```\n/mcp__context-bridge__resume-session context-bridge\n```\n\nThis invokes the `resume-session` named prompt, which tells the model to look up any handoff for the specified project and incorporate it.\n\n### Expiry and reliability\n\nHandoffs expire after `ttl_days` and are purged on service startup. If a session crashes before `handoff_acknowledge` is called, the handoff survives until its TTL — it will surface again in the next session's `handoff_list` call.\n\n## Importing Existing Context\n\nIf you've been using Claude Code's built-in file-based memory (`~/.claude/projects/<name>/memory/`), you can migrate that context into ContextBridge without any special tooling. Just ask:\n\n> \"Check your memory files and add any relevant entries to context-bridge using `memory_batch_write`.\"\n\nClaude Code reads its own memory index, iterates the entries, and calls `memory_batch_write` to store them in ContextBridge — where they become semantically searchable and visible to all connected clients immediately.\n\nYou can scope the request: *\"import only entries tagged `project:my-repo`\"* or *\"add everything in your memory files.\"*\n\nOnce imported, you can remove the original file-based entries to avoid maintaining two stores. ContextBridge becomes the single source of truth, shared across Claude Code, Claude Desktop, and any other connected client.\n\n## CLI Reference\n\nAll functionality is controlled via the `context-bridge` command. Run from any command-line (admin PowerShell required for service install/uninstall/config set).\n\n### Service Management\n\n```powershell\ncontext-bridge service install      # Download model, register service, start it\ncontext-bridge service start        # Start the service (no-op if already running)\ncontext-bridge service stop         # Stop the service gracefully\ncontext-bridge service status       # Show current status\ncontext-bridge service uninstall    # Stop and unregister (preserves memories.db)\n```\n\n### Model Management\n\n```powershell\ncontext-bridge model download       # Download embedding model (~22 MB) from Hugging Face\ncontext-bridge model download --yes # Skip confirmation, force re-download\n```\n\n### Configuration\n\n```powershell\ncontext-bridge config get port      # Show current HTTP port (default: 5290)\ncontext-bridge config set port 8000 # Change HTTP port (requires service restart)\n```\n\nConfiguration is stored in `%ProgramData%\\ContextBridge\\appsettings.json`. Changes take effect on next service start.\n\n### Client Configuration\n\n```powershell\ncontext-bridge configure            # Auto-configure all installed clients\n```\n\nThis command:\n- Detects installed AI clients (Claude Code, Claude Desktop, Cline, VS Code)\n- Writes MCP server configuration for each client\n- For Claude Code: injects usage guidelines into `~/.claude/CLAUDE.md`\n- Prints which clients were configured\n\n**Example output:**\n```\nClaude Code configured (HTTP transport)\nClaude Desktop configured (stdio transport)\nCline configured (HTTP transport)\nVS Code Chat Agents configured (HTTP transport)\n\nConfigured 4 client(s). Restart them to pick up changes.\n```\n\nRun this again after:\n- Installing a new AI client\n- Changing the service port (`config set port`)\n- Updating ContextBridge itself\n\n## Security\n\n**Security model:** Kestrel binds exclusively to `127.0.0.1` (localhost only). No authentication, no TLS.\n\n**Design rationale:** The localhost bind is the security perimeter. A process with enough privilege to intercept traffic on `127.0.0.1` already has broad machine access regardless of additional authentication.\n\n**Sensitive data:** Treat `%ProgramData%\\ContextBridge\\memories.db` as sensitive — it contains plaintext memory content. Any credentials or API keys stored in memories should be considered readable by local processes. Keep backups secure accordingly.\n\n## Build from Source\n\nFor developers who want to modify, test, or run ContextBridge locally.\n\n### Prerequisites\n\n- **[.NET 10 SDK](https://dotnet.microsoft.com/download)** — provides `dotnet` CLI and runtime\n- **Windows 10 / Windows 11**\n- **Admin PowerShell** — required to install as a Windows Service\n- **Git**\n\n### Clone and Build\n\n```powershell\ngit clone https://github.com/ThunderEagle/context-bridge.git\ncd context-bridge\ndotnet build\n```\n\nBuild time: 30–60 seconds on first run; subsequent builds are faster. Warnings are treated as errors per project policy.\n\n### Run Tests\n\n```powershell\ndotnet test\n```\n\nThis executes all xUnit integration tests (~2–5 minutes):\n- Vector search accuracy validation\n- Memory persistence across restarts\n- All MCP tool implementations\n- Schema migrations\n- SQLite + sqlite-vec integration\n\nTests use real temp-file SQLite databases (not in-memory) because sqlite-vec requires file-backed connections.\n\n### Run Locally (Console Mode)\n\nTo test the service without installing as a Windows Service:\n\n```powershell\ndotnet run --project src/ContextBridge.Service\n```\n\nThis starts the HTTP MCP server in the foreground:\n- **Binding:** `http://127.0.0.1:5290` (localhost only)\n- **Storage:** `%LOCALAPPDATA%\\ContextBridge\\memories.db` (user temp directory)\n- **Logging:** Console output shows startup, request traces, and errors\n\nThe service runs until you press `Ctrl+C`. Expected startup time: 5–10 seconds (ONNX model loads and JIT-compiles on first run; subsequent starts are faster).\n\n### Install as a Windows Service (from source)\n\nPublish the project, then install from the published binary:\n\n```powershell\ndotnet publish -c Release -o ./publish\n./publish/ContextBridge.Service.exe service install\n```\n\n**Important:** Run in admin PowerShell. This registers ContextBridge as a Windows Service with auto-start enabled, identical to the released executable.\n\nPublishing to a separate directory avoids file-locking issues if you rebuild the project while the service is running.\n\nUninstall:\n```powershell\n./publish/ContextBridge.Service.exe service uninstall\n```\n\n## Roadmap\n\n**v1** (current) — Windows Service, in-process embeddings (all-MiniLM-L6-v2), SQLite vector storage, Claude Code + Claude Desktop support.\n\n**v2** — Third-party editor support (Cursor, Windsurf), web dashboard, configurable embedding providers.\n\n**v3** — Cross-platform support (macOS, Linux), expanded client ecosystem.\n\n## Technology Stack\n\nFor contributors and those interested in architectural details.\n\n| Concern | Technology | Why |\n|---|---|---|\n| **Runtime** | .NET 10 Worker Service (`Microsoft.NET.Sdk.Web`) | Windows Service integration, clean distribution, no external runtime |\n| **Embeddings** | ONNX Runtime + all-MiniLM-L6-v2 INT8 | Fast, bundled, 384-dim vectors, ~22 MB model, in-process |\n| **Vector Search** | sqlite-vec extension | Native vector operations in SQLite, single-file storage, no external DB |\n| **Data Access** | Dapper + raw SQL | Sqlite-vec requires raw SQL; Dapper handles object mapping |\n| **AI Abstraction** | `Microsoft.Extensions.AI` | Standard AI library for .NET |\n| **CLI** | System.CommandLine | Built-in CLI parsing, minimal dependencies |\n| **MCP Transport** | Streamable HTTP (ModelContextProtocol SDK) | Shared service, concurrent clients, clean async/await model |\n\n**No external dependencies:** Core domain logic depends only on C# standard library. Infrastructure and CLI add Microsoft packages and MCP SDK.\n\nFull design rationale: see [`docs/DESIGN.md`](docs/DESIGN.md) and [`docs/adr/`](docs/adr/) (Architectural Decision Records).\n",
  "bytes": 14061,
  "sha": "fe498bc4ddd48dc68a5b51ebc5f5f688e551ed47fa49fd53cc57d0d94c63cb71",
  "repo_slug": "thundereagle/context-bridge",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_thundereagle_context_bridge_71e5d5c2/readme"
}