ContextKeep V2.1 Atlas：为 AI Agent 打造永久记忆系统

图1：ContextKeep 项目 Banner

一、痛点故事：为什么 AI Agent 需要"记忆"？

你一定有过这样的经历：让一个 AI 助手帮你写代码，它确实写出来了；但第二天你再问它同一个项目的问题，它就像失忆了一样——不记得你们讨论过的架构约定、不记得你偏好用的命名风格、不记得上次踩过的坑。这就是当前 AI Agent 最大的痛点——缺乏持久记忆。

ContextKeep 正是为解决这一问题而生的开源项目。它为所有兼容 MCP（Model Context Protocol）的 AI Agent 提供了一个本地持久化、可全文检索的记忆存储系统。开发者在终端里问 AI 一个问题，AI 会自动从 ContextKeep 中检索相关上下文；AI 处理完任务后，可以选择把重要信息写回 ContextKeep。整个过程对用户透明，但 AI 的"脑容量"从单次会话扩展到了无限。

目前主流的 Agent 框架（如 LangChain、CrewAI、AutoGen 等）大多依赖对话历史来维护上下文，一旦对话轮次增加，token 消耗急剧上升，而且长上下文窗口的召回质量也在下降。ContextKeep 通过把"记忆"外部化，让 AI 在需要时主动查询，不再被对话历史绑架。V2.1 版本还从早期版本的"固定标签"升级为"用户可编辑分类"体系，让记忆组织更加灵活。

图2：ContextKeep WebUI 功能展示界面

二、项目概述：技术规格一览

ContextKeep 是一个用 Python 3.10+ 构建的 MCP Server，核心依赖极其精简：

• Flask >= 3.0：提供 HTTP MCP 端点和 WebUI 服务
• FastMCP >= 2.12：实现 MCP 协议服务端，定义标准化的 Agent 工具集
• SQLite + FTS5：利用 SQLite 的 FTS5 全文搜索引擎实现毫秒级记忆检索

项目采用 MIT 许可证，截至分析时已获得 154 颗 GitHub Stars，标签涵盖 、、、、、，定位明确。

三、核心功能：从"记不住"到"忘不了"

3.1 MCP 工具集：Agent 的记忆 API

ContextKeep 提供了一套完整的 MCP 工具，Agent 可以调用它们来管理记忆：

• ****：存储或更新一条记忆，支持指定 key、内容、标题和分类
• ****：通过精确 key 检索记忆，并返回最近 5 条编辑历史
• ****：按分类列出记忆，支持关键词搜索（基于 FTS5 全文索引）
• ****：列出所有分类及其记忆数量
• **** / **** / ****：完整的分类 CRUD 操作
• ****：查询服务器信息，包括版本、数据库路径、工具列表和迁移状态
• **** / ****：记忆的 JSON 导入导出

值得注意的是 V2.1 的一个重要设计变化：** 工具被移除了**。Agent 现在必须先查询分类，再在对应分类下查找记忆。这种"先分类再检索"的模式强制 AI 在存储记忆时就想好分类，减少了记忆的碎片化。

3.2 分类体系：9 大 starter 分类

V2.1 预置了 9 个 starter 分类，覆盖了 Agent 常见的使用场景：

分类	适用场景
Projects	项目仓库、里程碑、特定项目的上下文
Hardware & Infrastructure	设备参数、NAS 服务器、家庭实验室
Credentials & Access	API Key、SSH 密钥、登录凭证
People & Contacts	联系人、团队成员、协作者
Workflows & Automation	流程、脚本、Agent 指令、自动化任务
Content & Media	YouTube 视频、博客文章、社交媒体内容
Configuration & Settings	工具配置、环境变量偏好、系统设置
Knowledge & Research	笔记、文章、参考资料、学习资源
Personal	目标、个人偏好、提醒、生活笔记

分类还支持通过关键词自动推断：当 Agent 存储记忆时，系统会根据记忆内容中的关键词自动建议合适的分类。

3.3 数据库架构：FTS5 全文索引

ContextKeep 的数据库设计值得细看。 表使用 UUID 作为唯一 key，存储标题和正文内容； 是多对多关联表，一条记忆可以同时属于多个分类，这是 V2.1 的核心改进之一。 表记录每条记忆的所有操作历史（INSERT/UPDATE/DELETE），来源可以是 MCP 或 WebUI，为记忆的可追溯性提供保障。

FTS5 虚拟表通过三个数据库触发器（、、）与主表保持实时同步，确保全文索引始终准确。实际体验中，检索数千条记忆的响应时间在毫秒级别，体验流畅。

3.4 安全机制：敏感信息保护

代码中内置了敏感信息识别逻辑：当记忆内容被检测到包含 API Key、Access Token 等高风险关键词时，系统会自动将内容替换为 ，防止 WebUI 中无意泄露。WebUI 支持"显示密码"模式，但需要用户主动点击才可见。

3.5 备份与升级机制

ContextKeep 的升级流程设计非常谨慎。 脚本在执行任何替换操作前，会先创建完整备份，然后验证备份文件完整性，最后才执行迁移。即使迁移失败，用户也可以通过 一键回滚到之前的状态。这对于生产环境中的长期运行非常重要。

四、部署方式：三条路径任选

4.1 Docker Compose（推荐）

官方提供的 是最简单的启动方式，一条命令即可同时启动 MCP 服务（端口 5100）和 WebUI（端口 5000），两者共享同一个 SQLite 数据库文件，持久化存储在 Docker Volume 中。服务启动后自带健康检查（每 60 秒一次），自动重启策略保证长期稳定运行。

4.2 裸机安装

对于需要深度定制的用户，项目提供了 安装脚本，支持 Linux/macOS/Windows 三平台。安装脚本会自动创建数据目录、初始化数据库，并可选地安装 systemd 服务（Linux）或 launchd 服务（macOS）。

4.3 MCP Client 配置

项目提供了多种 MCP Client 配置模板：标准 HTTP 配置、SSE 回退配置（兼容老旧客户端）、Docker 容器内运行配置。支持 Claude Desktop、Cursor、Windsurf 等主流 MCP 客户端。

五、代码质量分析

架构类型：MCP Server + WebUI 双进程架构，采用分层设计。

核心模块：

• ：数据库初始化和连接管理（线程安全）
• ：记忆的 CRUD 操作核心逻辑（1500+ 行）
• ：分类管理和关键词推断逻辑
• ：FastMCP 驱动的 MCP Server
• ：Flask 驱动的 Web UI 服务
• ：辅助脚本（备份、恢复、升级、健康检查）

代码质量评分：8/10。代码结构清晰，分离良好，使用类型注解提升可读性。数据库操作有线程锁保护，敏感信息有脱敏处理，错误处理较为完善。文档质量极高，提供了完整的迁移指南、安全升级指南和客户端配置文档。主要扣分点：无公开测试套件，credentials 类别名有拼写错误。

技术栈：Python / Flask / FastMCP / SQLite / FTS5 / Docker

AI Framework：FastMCP（Model Context Protocol 实现）

数据隐私：所有数据本地存储，SQLite 数据库完全在用户控制之下，无云依赖。

六、行业意义与局限性

ContextKeep 代表了 AI Agent 基础设施的一个重要方向——记忆外部化。随着 MCP 协议的普及，Agent 之间的互操作性正在增强，ContextKeep 作为 MCP 生态中为数不多的记忆组件，有望成为 Agent 的"第二大脑"标准存储方案。

但也需要正视其局限性：目前不支持多 Agent 共享记忆（所有数据存储在单机 SQLite），对于需要团队协作的场景尚不适用。另外，基于关键词的全文检索无法理解语义，对于复杂查询场景可能需要配合向量数据库（如 ChromaDB）使用。