Context Portal MCP (ConPort)：给 AI 编程工具打造的项目级记忆银行

想象这样一个场景：你正在开发一个大型项目，AI 助手帮助你写代码。聊了 50 轮之后，AI 开始「失忆」——忘了你们早期做出的架构决策，混淆了变量命名，甚至建议你重复写已经实现过的功能。

这不是 AI 的 bug，而是上下文丢失的必然结果。大多数 AI 编程工具（如 Cursor、Windsurf、CLine）只能看到当前对话窗口的内容，没有持久化的项目级记忆。

Context Portal（简称 ConPort） 正是来解决这个问题的：它为每个项目建立一个专属的「记忆库」，让 AI 编程工具能够跨会话、跨工具调用，记住项目的决策、进度、架构和约定。

集成 ConPort 的 CLine IDE ConPort 也支持 Cursor IDE

背景：为什么需要 ConPort？

Scott McLeod（GitHub: @GreatScottyMac）开发了 ConPort，灵感来自他日常使用 AI 编程工具的痛苦经历。随着项目规模增长，AI 的健忘症越来越严重——每次开启新对话，都得从头解释项目背景。

ConPort 基于 Model Context Protocol（MCP） 构建。MCP 是 Anthropic 在 2024 年底开源的一项标准协议，旨在让 AI 模型能够与各种数据源和工具进行标准化交互。ConPort 将 MCP 作为接口层，对下管理项目的结构化数据，对上提供统一的工具调用接口。

这意味着 ConPort 可以无缝插入所有支持 MCP 的 AI 编程工具，包括 CLine、Roo Code（Cline 的进阶版）、Windsurf 和 Cursor 等主流 IDE——你不需要为每个工具单独配置记忆系统，ConPort 就是那个统一的项目记忆后端。

核心原理：知识图谱 + 向量检索双驱动

ConPort 的数据层采用双引擎架构，兼顾结构化查询和语义搜索：

1. SQLite 结构化存储（项目知识图谱）

每个工作区对应一个独立的 SQLite 数据库（.conport/ 目录下），存储四类核心实体：

• Decisions（决策）：记录架构选型、第三方库取舍等重要决定的「为什么」，包含摘要、理由和实现细节。
• Progress（进度）：任务清单，支持父子任务关系，适合 Sprint 规划。
• System Patterns（系统模式）：沉淀项目中反复出现的代码模式、规范和约定。
• Custom Data（自定义数据）：任意 JSON 结构，存储项目特有的信息（如 API 规范、术语表等）。

这四类实体通过 workspace_id 隔离，支持多项目并行管理。

2. ChromaDB 向量检索（语义搜索）

ConPort 不满足于「精确匹配」，还支持语义搜索：当你问「之前的缓存方案是怎么做的」，即使不用精确关键词，系统也能找到相关内容。这背后的技术栈是：

• Embedding 模型：使用 all-MiniLM-L6-v2（轻量级 sentence-transformer 模型），在 CPU 上即可高效运行。
• 向量存储：ChromaDB 作为向量数据库，支持持久化存储和相似度检索。
• RAG 增强：将语义搜索结果注入 LLM 的上下文，实现检索增强生成。

3. MCP Server 架构（FastMCP + FastAPI）

ConPort 的服务端基于 fastmcp 框架构建，这是在标准 MCP SDK 之上的高级封装。FastMCP 让开发者可以用装饰器风格定义工具（@mcp.tool()），而底层由 FastAPI 驱动 HTTP 服务，同时也支持 STDIO 模式——后者是 IDE 集成的推荐方式，因为延迟最低。

主入口在 src/context_portal_mcp/main.py，命令行参数解析后启动两种运行模式：

• --mode stdio：标准 I/O 模式，适合 IDE 集成
• --mode server：HTTP 服务模式，可作为独立进程运行

代码架构：清晰的分层设计

项目采用标准的 src/ 布局，核心模块分为三层：

模块	职责
core/	核心服务：嵌入向量生成（embedding_service.py）、工作区检测（workspace_detector.py）
db/	数据层：SQLite 数据库管理（database.py）、Pydantic 模型（models.py）、ChromaDB 向量服务（vector_store_service.py）
handlers/	MCP 工具处理器（mcp_handlers.py）：实现所有 MCP 工具的核心逻辑

各层职责清晰，handlers 不直接操作数据库，而是通过 db/ 模块提供的接口。core/embedding_service.py 使用**双重检查锁（double-check locking）**模式保证线程安全的模型加载，避免重复初始化开销。

使用方式：15 分钟快速上手

安装（Python >= 3.10）：

pip install context-portal-mcp

IDE 配置（以 CLine 为例）：在 CLine 的 MCP Server 配置中添加：

{
  "mcpServers": {
    "context-portal": {
      "command": "conport-mcp",
      "args": ["--mode", "stdio", "--workspace_id", "${workspaceFolder}"]
    }
  }
}

Docker 部署：提供 Dockerfile，基于 python:3.13-slim-bookworm，以非 root 用户运行，适合集成到 CI/CD 流程中。

局限与注意事项

1. 没有图形界面：ConPort 是纯后端服务，没有 Web UI。配置和交互全部通过 AI 编程工具完成，对习惯 GUI 的用户有一定上手门槛。

2. ChromaDB 内存占用：向量检索依赖 ChromaDB，文档量大时（>10万条）需要关注内存使用。建议定期清理无用上下文条目。

3. 上下文窗口仍然有限：ConPort 是 RAG 后端，但最终送入 LLM 的上下文仍然受限于模型的上下文窗口大小。超长项目仍需考虑选择性检索策略。

4. MCP 生态兼容性：MCP 协议相对年轻，不同 IDE 对 MCP 的支持程度不一。Windsurf 某些版本可能需要额外配置。

行业意义：AI 编程的记忆缺失问题正在被解决

2024 年下半年起，AI 编程工具进入爆发期。Cursor 估值 25 亿美元、Windsurf 获 1.15 亿美元融资、Anthropic 推出 Claude Code……但这些工具都有一个共同的阿喀琉斯之踵：缺乏项目级持久记忆。

ConPort 的出现代表了三条趋势的交汇：

1. MCP 协议标准化：从厂商私有接口走向开放协议，降低了工具间集成成本。
2. 本地知识图谱下沉：将云端 RAG 能力迁移到本地，既保护隐私又降低延迟。
3. AI Agent 的长期记忆需求：随着 AI 能处理更复杂任务，「记忆」成为制约多轮交互质量的瓶颈。

ConPort 目前处于 Beta 阶段（v0.3.13），作者 Scott McLeod 保持高频更新，已有不错的社区关注度（765 stars）。对于经常使用 AI 辅助编程的开发者，这是一款值得关注的效率工具。