ContextBridge

ContextBridge

一个零依赖的 Windows MCP 记忆服务，为 AI 编码助手提供共享的持久化记忆层，并支持语义搜索。

什么是 ContextBridge？

Claude Code 等 AI 编码助手是无状态的——每次会话都会重新开始，不会持久记住你之前的上下文、决策或发现。ContextBridge 通过作为后台 Windows 服务运行来解决这一问题，所有 AI 工具都可以连接到该服务。它会持久存储记忆，并支持按含义（而非关键词）搜索，因此上下文能够在不同会话之间以及多个工具之间持续积累。

为什么选择 ContextBridge？

• 零外部依赖 — 无需 Docker、Postgres、Python 或 Ollama。所有功能都在一个 Windows 服务进程中运行。
• 进程内嵌入 — 嵌入模型（all-MiniLM-L6-v2，约 22 MB）通过 ONNX Runtime 运行；无需调用外部 API。
• 单文件存储 — SQLite 数据库位于 %ProgramData%\ContextBridge\memories.db。备份只需复制一个文件。
• 工具间共享 — Claude Code（HTTP）、Claude Desktop（stdio）、Cline、VS Code Chat Agents 都能实时连接到同一个记忆存储。
• 服务重启后记忆仍会保留 — 记忆持久保存在 SQLite 中；嵌入模型在启动时加载一次，随后保持就绪状态。

要求

• Windows 10 / Windows 11（Windows 服务集成所必需）
• 选项 A：.NET 10 SDK（通过 dotnet tool 安装时需要）
• **选项 B：**Windows 10+（下载预编译的 .exe 时无需其他前置条件）
• 管理员 PowerShell（安装/卸载 Windows 服务时需要）

快速开始

选项 A：通过 dotnet 全局工具安装

如果已安装 .NET 10 SDK：

dotnet tool install -g ThunderEagle.ContextBridge

这会在系统 PATH 中放置一个 context-bridge 可执行文件。

选项 B：直接下载

从 GitHub Releases 下载预编译的可执行文件（无需 SDK；首次运行时会出现一次 SmartScreen 警告）。将 .exe 添加到 PATH，或直接调用它。

首次运行设置

在管理员 PowerShell 中运行以下两条命令（右键单击 →“以管理员身份运行”）：

# 1. Download the embedding model, register as Windows Service, start it
context-bridge service install

# 2. Configure your AI tools to connect
context-bridge configure

具体操作：

1. service install 会下载嵌入模型（约 22 MB）、注册 Windows 服务、将其设置为开机自动启动，并立即启动服务。
2. configure 会自动检测已安装的客户端（Claude Code、Claude Desktop、Cline、VS Code Chat），并配置它们连接到该服务。

现在服务已在后台运行。下次重启 AI 工具时，它们就能使用记忆存储。

验证服务是否正在运行：

Get-Service ContextBridge

预期输出：Status = Running

支持的客户端

客户端	传输方式	版本	备注
Claude Code	HTTP	最新版	由 context-bridge configure 自动配置
Claude Desktop	stdio	最新版	通过 claude_desktop_config.json 自动配置
Cline（VS Code）	HTTP	最新版	由 context-bridge configure 自动配置
VS Code Chat Agents	HTTP	1.99+	由 context-bridge configure 自动配置

所有客户端通过并发连接共享同一个 SQLite 数据库；一个工具写入的记忆会立即对其他工具可见。

MCP 工具

ContextBridge 提供七个 MCP 工具，供 AI 助手使用：

工具	用途
memory_write	存储单条记忆，并自动进行语义嵌入，可选添加标签
memory_batch_write	原子性地存储多条相关记忆（高效提取会话结束时的信息）
memory_search	语义搜索——使用自然语言查询，返回最近邻结果
memory_list	分页列出所有记忆，可选按标签筛选
memory_update	更新记忆内容（自动重新嵌入）
memory_delete	按 ID 删除记忆
memory_status	服务健康状况检查、记录数量和模型信息

标签约定（可选；由 AI 工具分配）：

• project:<repo-name> — 将记忆限定到某个项目
• type:decision — 架构或技术选择
• type:preference — 编码风格、工具和工作流偏好
• type:pattern — 重复出现的模式或约定
• type:reference — 指向外部资源或文档的链接

交接——恢复会话

记忆是永久事实。交接则有所不同：它是临时的会话状态，让你在未来的会话中从上次中断处继续，而无需重新加载对话历史。

工作原理

在会话结束时，请 AI 助手保存当前状态：

“为项目 context-bridge 保存一份交接，记录我们正在处理的内容。”

模型会调用 handoff_write，保存当前工作的摘要——包括已做出的决定、后续步骤和待解决的问题，并限定到该项目。

在下一次会话开始时，模型会（通过服务说明）自动调用 handoff_list，并将此前的交接纳入开场上下文。处理完成后，它会调用 handoff_acknowledge 移除交接。

交接工具

工具	用途
handoff_write	记录会话状态——正在处理的内容、已做出的决定和后续步骤
handoff_list	获取有效交接，可选按项目筛选
handoff_acknowledge	处理完交接后将其移除（永久删除）

handoff_write 的关键参数：

• content — 会话摘要（自由格式文本）
• project — 项目标识符，例如 context-bridge（可选，但建议填写）
• ttl_days — 交接保留的天数，之后自动过期（默认值：7）

交接与记忆的区别

	记忆	交接
用途	长期有效的事实、决定和偏好	临时的“我上次处理到哪里”快照
有效期	永久（除非明确删除）	受 TTL 限制（默认 7 天）
搜索	通过 memory_search 进行语义搜索	通过 handoff_list 进行精确查找
清理	memory_delete	handoff_acknowledge（或 TTL 到期）

不要自动将交接内容转换为记忆。记忆用于记录会无限期保持有效的事实。如果恢复会话时发现某些内容达到这一标准，请另行通过 memory_write 写入。

显式恢复会话

如果你的 MCP 客户端支持提示词功能（例如 Claude Code），可以显式触发会话恢复：

/mcp__context-bridge__resume-session context-bridge

这会调用名为 resume-session 的提示词，指示模型查找指定项目的交接信息并将其纳入上下文。

过期与可靠性

交接会在 ttl_days 指定的时间后过期，并在服务启动时清除。如果会话在调用 handoff_acknowledge 前崩溃，交接会保留至 TTL 到期——它将在下一次会话调用 handoff_list 时再次出现。

导入现有上下文

如果你一直在使用 Claude Code 内置的基于文件的记忆（~/.claude/projects/<name>/memory/），可以将这些上下文迁移到 ContextBridge，无需任何特殊工具。只需询问：

“检查你的记忆文件，并使用 memory_batch_write 将相关条目添加到 context-bridge。”

Claude Code 会读取自己的记忆索引，遍历其中的条目，并调用 memory_batch_write 将它们存储到 ContextBridge 中，这样它们就会立即变得可语义搜索，并对所有已连接的客户端可见。

你可以限定请求范围：“仅导入标记为 project:my-repo 的条目”，或 “添加记忆文件中的所有内容。”

导入完成后，你可以删除原有的基于文件的条目，避免维护两套存储。ContextBridge 将成为唯一可信来源，并在 Claude Code、Claude Desktop 及其他所有已连接的客户端之间共享。

CLI 参考

所有功能都通过 context-bridge 命令控制。可从任意命令行运行（安装/卸载服务和设置配置需要管理员 PowerShell）。

服务管理

context-bridge service install      # Download model, register service, start it
context-bridge service start        # Start the service (no-op if already running)
context-bridge service stop         # Stop the service gracefully
context-bridge service status       # Show current status
context-bridge service uninstall    # Stop and unregister (preserves memories.db)

模型管理

context-bridge model download       # Download embedding model (~22 MB) from Hugging Face
context-bridge model download --yes # Skip confirmation, force re-download

配置

context-bridge config get port      # Show current HTTP port (default: 5290)
context-bridge config set port 8000 # Change HTTP port (requires service restart)

配置存储在 %ProgramData%\ContextBridge\appsettings.json 中。更改将在下次启动服务时生效。

客户端配置

context-bridge configure            # Auto-configure all installed clients

此命令会：

• 检测已安装的 AI 客户端（Claude Code、Claude Desktop、Cline、VS Code）
• 为每个客户端写入 MCP 服务配置
• 对于 Claude Code：将使用指南注入 ~/.claude/CLAUDE.md
• 显示已配置的客户端

输出示例：

Claude Code configured (HTTP transport)
Claude Desktop configured (stdio transport)
Cline configured (HTTP transport)
VS Code Chat Agents configured (HTTP transport)

Configured 4 client(s). Restart them to pick up changes.

在以下情况后请重新运行此命令：

• 安装新的 AI 客户端
• 更改服务端口（config set port）
• 更新 ContextBridge 本身

安全

安全模型： Kestrel 仅绑定到 127.0.0.1（仅限本地主机）。无需身份验证，也不使用 TLS。

设计理由： 本地主机绑定就是安全边界。无论是否增加身份验证，有足够权限拦截 127.0.0.1 上流量的进程，本来就已拥有对计算机的广泛访问权限。

敏感数据： 请将 %ProgramData%\ContextBridge\memories.db 视为敏感数据，其中包含明文记忆内容。存储在记忆中的任何凭据或 API 密钥，都应视为本地进程可读取。请妥善保护备份。

从源代码构建

适用于希望修改、测试或在本地运行 ContextBridge 的开发者。

先决条件

• .NET 10 SDK — 提供 dotnet CLI 和运行时
• Windows 10 / Windows 11
• 管理员 PowerShell — 作为 Windows 服务安装时需要
• Git

克隆并构建

git clone https://github.com/ThunderEagle/context-bridge.git
cd context-bridge
dotnet build

首次构建耗时：30–60 秒；后续构建更快。根据项目策略，警告会被视为错误。

运行测试

dotnet test

此命令会运行所有 xUnit 集成测试（约 2–5 分钟）：

• 向量搜索准确性验证
• 重启后记忆持久性
• 所有 MCP 工具实现
• 架构迁移
• SQLite + sqlite-vec 集成

测试使用真实的临时文件 SQLite 数据库（而非内存数据库），因为 sqlite-vec 需要基于文件的连接。

本地运行（控制台模式）

如需在不安装为 Windows 服务的情况下测试该服务：

dotnet run --project src/ContextBridge.Service

此命令会在前台启动 HTTP MCP 服务：

• 绑定： http://127.0.0.1:5290（仅限本地主机）
• 存储： %LOCALAPPDATA%\ContextBridge\memories.db（用户临时目录）
• 日志记录： 控制台输出显示启动信息、请求跟踪信息和错误

按下 Ctrl+C 前，服务会持续运行。预计启动时间：5–10 秒（首次运行时会加载 ONNX 模型并进行 JIT 编译；后续启动会更快）。

安装为 Windows 服务（从源代码）

发布项目，然后从已发布的二进制文件安装：

dotnet publish -c Release -o ./publish
./publish/ContextBridge.Service.exe service install

重要： 请在管理员 PowerShell 中运行。这会将 ContextBridge 注册为 Windows 服务，并启用自动启动，与已发布的可执行文件完全相同。

发布到单独的目录可避免在服务运行时重建项目导致的文件锁定问题。

卸载：

./publish/ContextBridge.Service.exe service uninstall

路线图

v1（当前）— Windows 服务、进程内嵌入（all-MiniLM-L6-v2）、SQLite 向量存储、支持 Claude Code + Claude Desktop。

v2 — 支持第三方编辑器（Cursor、Windsurf）、Web 仪表板、可配置的嵌入提供商。

v3 — 跨平台支持（macOS、Linux）、扩展客户端生态系统。

技术栈

面向贡献者以及对架构细节感兴趣的读者。

关注点	技术	原因
运行时	.NET 10 Worker Service（Microsoft.NET.Sdk.Web）	Windows 服务集成、简洁的分发方式、无需外部运行时
嵌入	ONNX Runtime + all-MiniLM-L6-v2 INT8	快速、内置、384 维向量、模型约 22 MB、进程内运行
向量搜索	sqlite-vec 扩展	在 SQLite 中执行原生向量操作、单文件存储、无需外部数据库
数据访问	Dapper + 原始 SQL	Sqlite-vec 需要原始 SQL；Dapper 负责对象映射
AI 抽象	Microsoft.Extensions.AI	.NET 的标准 AI 库
CLI	System.CommandLine	内置 CLI 解析、依赖项精简
MCP 传输	Streamable HTTP（ModelContextProtocol SDK）	共享服务、支持并发客户端、简洁的 async/await 模型

无外部依赖： 核心领域逻辑仅依赖 C# 标准库。基础设施和 CLI 使用 Microsoft 软件包及 MCP SDK。

完整的设计原理：参阅 docs/DESIGN.md 和 docs/adr/（架构决策记录）。