The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the ContextBridge listing page.
A zero-dependency MCP memory server for Windows that gives AI coding assistants a shared, persistent memory layer with semantic search.
AI 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.
%ProgramData%\ContextBridge\memories.db. Backup is one file copy.dotnet tool)If you have the .NET 10 SDK installed:
This places a context-bridge executable on your system PATH.
Download a pre-built executable from GitHub Releases (no SDK required; one-time SmartScreen warning). Add the .exe to your PATH or invoke it directly.
Run these two commands in admin PowerShell (right-click → "Run as Administrator"):
What happens:
service install downloads the embedding model (~22 MB), registers the Windows Service, sets it to auto-start on boot, and starts it immediately.configure auto-detects installed clients (Claude Code, Claude Desktop, Cline, VS Code Chat) and wires them up to connect to the service.The service now runs in the background. Your AI tools will see the memory store the next time you restart them.
Verify the service is running:
Expected output: Status = Running
| Client | Transport | Version | Notes |
|---|---|---|---|
| Claude Code | HTTP | Latest | Auto-configured by context-bridge configure |
| Claude Desktop | stdio | Latest | Auto-configured via claude_desktop_config.json |
| Cline (VS Code) | HTTP | Latest | Auto-configured by context-bridge configure |
| VS Code Chat Agents | HTTP | 1.99+ | Auto-configured by context-bridge configure |
All clients share the same SQLite database via concurrent connections; memories written by one tool are immediately visible to others.
ContextBridge exposes seven MCP tools for your AI assistants to use:
| Tool | Purpose |
|---|---|
memory_write | Store a single memory with automatic semantic embedding and optional tags |
memory_batch_write | Store multiple related memories atomically (efficient end-of-session extraction) |
memory_search | Semantic search — natural language query, returns nearest-neighbor results |
memory_list | Paginated list of all memories with optional tag filters |
memory_update | Update a memory's content (re-embedded automatically) |
memory_delete | Delete a memory by ID |
memory_status | Service health check, record count, model info |
Tag conventions (optional; assigned by the AI tool):
project:<repo-name> — scope memories to a projecttype:decision — architectural or technology choicestype:preference — coding style, tooling, workflow preferencestype:pattern — recurring patterns or conventionstype:reference — pointers to external resources or documentationMemories 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.
At the end of a session, ask your AI assistant to save its state:
"Save a handoff for project context-bridge with what we were working on."
The model calls handoff_write with a summary of current work — decisions made, next steps, open questions — scoped to the project.
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.
| Tool | Purpose |
|---|---|
handoff_write | Capture session state — what you're working on, decisions made, next steps |
handoff_list | Retrieve active handoffs, optionally filtered by project |
handoff_acknowledge | Remove a handoff after processing it (permanent deletion) |
Key parameters for handoff_write:
content — the session summary (free-form text)project — project identifier, e.g. context-bridge (optional but recommended)ttl_days — how many days to keep the handoff before auto-expiry (default: 7)| Memories | Handoffs | |
|---|---|---|
| Purpose | Durable facts, decisions, preferences | Ephemeral "where I was" snapshots |
| Lifespan | Permanent (until explicitly deleted) | TTL-bounded (default 7 days) |
| Search | Semantic search via memory_search | Exact lookup via handoff_list |
| Cleanup | memory_delete | handoff_acknowledge (or TTL expiry) |
Do 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.
If your MCP client supports the prompts capability (e.g. Claude Code), you can trigger a session resumption explicitly:
This invokes the resume-session named prompt, which tells the model to look up any handoff for the specified project and incorporate it.
Handoffs 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.
If 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:
"Check your memory files and add any relevant entries to context-bridge using
memory_batch_write."
Claude 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.
You can scope the request: "import only entries tagged project:my-repo" or "add everything in your memory files."
Once 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.
All functionality is controlled via the context-bridge command. Run from any command-line (admin PowerShell required for service install/uninstall/config set).
Configuration is stored in %ProgramData%\ContextBridge\appsettings.json. Changes take effect on next service start.
This command:
~/.claude/CLAUDE.mdExample output:
Run this again after:
config set port)Security model: Kestrel binds exclusively to 127.0.0.1 (localhost only). No authentication, no TLS.
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.
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.
For developers who want to modify, test, or run ContextBridge locally.
dotnet CLI and runtimeBuild time: 30–60 seconds on first run; subsequent builds are faster. Warnings are treated as errors per project policy.
This executes all xUnit integration tests (~2–5 minutes):
Tests use real temp-file SQLite databases (not in-memory) because sqlite-vec requires file-backed connections.
To test the service without installing as a Windows Service:
This starts the HTTP MCP server in the foreground:
http://127.0.0.1:5290 (localhost only)%LOCALAPPDATA%\ContextBridge\memories.db (user temp directory)The 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).
Publish the project, then install from the published binary:
Important: Run in admin PowerShell. This registers ContextBridge as a Windows Service with auto-start enabled, identical to the released executable.
Publishing to a separate directory avoids file-locking issues if you rebuild the project while the service is running.
Uninstall:
v1 (current) — Windows Service, in-process embeddings (all-MiniLM-L6-v2), SQLite vector storage, Claude Code + Claude Desktop support.
v2 — Third-party editor support (Cursor, Windsurf), web dashboard, configurable embedding providers.
v3 — Cross-platform support (macOS, Linux), expanded client ecosystem.
For contributors and those interested in architectural details.
| Concern | Technology | Why |
|---|---|---|
| Runtime | .NET 10 Worker Service (Microsoft.NET.Sdk.Web) | Windows Service integration, clean distribution, no external runtime |
| Embeddings | ONNX Runtime + all-MiniLM-L6-v2 INT8 | Fast, bundled, 384-dim vectors, ~22 MB model, in-process |
| Vector Search | sqlite-vec extension | Native vector operations in SQLite, single-file storage, no external DB |
| Data Access | Dapper + raw SQL | Sqlite-vec requires raw SQL; Dapper handles object mapping |
| AI Abstraction | Microsoft.Extensions.AI | Standard AI library for .NET |
| CLI | System.CommandLine | Built-in CLI parsing, minimal dependencies |
| MCP Transport | Streamable HTTP (ModelContextProtocol SDK) | Shared service, concurrent clients, clean async/await model |
No external dependencies: Core domain logic depends only on C# standard library. Infrastructure and CLI add Microsoft packages and MCP SDK.
Full design rationale: see docs/DESIGN.md and docs/adr/ (Architectural Decision Records).