ContextKeep 🧠

为 AI 智能体提供无限的长期记忆

ContextKeep 是一个功能强大的独立内存服务器，为您的 AI 智能体（Claude、Cursor、Gemini、OpenCode 等）提供持久且可搜索的大脑。无需重复输入 — 让您的 AI 永久记住一切。

功能特性 • V1.3 新特性 • 安装指南 • MCP 工具 • Web 控制面板 • 配置说明

🌟 功能特性

• ♾️ 无限上下文： 存储无限的项目详情、偏好、决策和代码片段 — 无过期限制，无大小上限。

• 💰 节省金钱与 Token： 仅提取相关的记忆，大幅降低上下文窗口占用和 API 成本。

• 🔌 通用兼容性： 通过 Stdio（本地）或 SSE（远程/家庭实验室）与任何符合 MCP 标准的客户端配合使用。

• 🧭 记忆索引协议： 可靠的两步检索系统 — list_all_memories() → retrieve_memory() — 确保智能体每次都能找到正确的键。

• 🖥️ 现代 Web 控制面板： 在简洁的深色界面中，通过网格、列表和日历视图直观地管理您的记忆。

• 🔒 隐私至上： 100% 本地存储。您的数据绝不会触及任何外部服务器。

• 🔎 智能搜索： 对所有记忆内容进行关键词和语义搜索。

• 🐧 Linux 服务： 作为 systemd 服务在后台静默运行。

• 🐳 Docker 就绪： 使用 Docker Compose 一键部署。

• ⬇️ 导出与备份： 通过 MCP 工具或 WebUI 将所有记忆导出为 JSON。

🆕 V1.3 新特性 — Harbor

🐳 Docker 支持

社区呼声最高的功能。ContextKeep 现在附带 Dockerfile 和 docker-compose.yml，实现一键部署：

docker compose up --build

就是这样。MCP 服务器运行在 :5100，WebUI 运行在 :5000，并通过 Docker 卷实现持久化存储。

📦 现代 Python 打包

• pyproject.toml — 适用于 uv、poetry 或 pip 的规范依赖定义

• uv 支持 — 安装程序会自动检测 uv 并使用 uv sync 进行极速设置

• 向后兼容 — pip install -r requirements.txt 依然有效

🛠️ 3 个新增 MCP 工具（总数从 5 个增加到 8 个）

⬇️ WebUI 导出功能

• 工具栏中的 Export All 按钮（或按 Ctrl+E）

• 下载带有时间戳的 contextkeep_backup_YYYY-MM-DD.json 文件

🧹 代码质量优化

• 修复了 memory_manager.py 中的死代码（无法到达的重复 try/except）

• 添加了缺失的 core/__init__.py 以实现正确的 Python 打包

• 全局将裸露的 except: 替换为 except Exception:

🚀 安装指南

选项 1：快速开始 (pip)

1. 克隆仓库：

   git clone https://github.com/mordang7/ContextKeep.git
   cd ContextKeep

2. 运行安装程序：

   • Linux/macOS：

     python3 install.py

   • Windows：

     python install.py

3. 按照向导操作： 安装程序会创建虚拟环境、安装依赖并生成可直接使用的 mcp_config.json。

选项 2：uv (极速)

git clone https://github.com/mordang7/ContextKeep.git
cd ContextKeep
uv sync
uv run python server.py

选项 3：Docker (推荐用于家庭实验室)

git clone https://github.com/mordang7/ContextKeep.git
cd ContextKeep
docker compose up --build -d

这将启动：

记忆将持久化保存在 Docker 卷 (contextkeep-data) 中。

🛠️ MCP 工具

ContextKeep 向任何连接的智能体公开 8 个 MCP 工具：

推荐的智能体指令

将其添加到您的 GEMINI.md、AGENTS.md 或 CLAUDE.md 中：

## Memory Index Protocol (MANDATORY)
1. FIRST — call `list_all_memories()` to get the complete key directory
2. THEN — call `retrieve_memory(exact_key)` using the exact key from step 1
Only use `search_memories()` for content-based searches, NOT for key lookup.

🔌 配置说明

将 mcp_config.example.json 的内容复制到您的 AI 客户端配置文件中，并更新路径。

选项 1：本地 (Claude Desktop / Gemini CLI / Cursor)

{
  "mcpServers": {
    "context-keep": {
      "command": "/absolute/path/to/ContextKeep/venv/bin/python",
      "args": ["/absolute/path/to/ContextKeep/server.py"]
    }
  }
}

选项 2：通过 SSH 远程 (家庭实验室 / 树莓派)

在家庭服务器上运行 ContextKeep，并从网络上的任何机器访问它：

{
  "mcpServers": {
    "context-keep": {
      "command": "ssh",
      "args": [
        "-i", "/path/to/private_key",
        "user@192.168.1.X",
        "'/path/to/ContextKeep/venv/bin/python'",
        "'/path/to/ContextKeep/server.py'"
      ]
    }
  }
}

选项 3：SSE 模式 (HTTP)

适用于 OpenCode、Web 应用或任何偏好 HTTP 传输的客户端：

{
  "mcpServers": {
    "context-keep": {
      "transport": "sse",
      "url": "http://localhost:5100/sse"
    }
  }
}

选项 4：Docker

使用 mcp_config.docker.example.json 或将您的客户端指向容器：

{
  "mcpServers": {
    "context-keep": {
      "transport": "sse",
      "url": "http://localhost:5100/sse"
    }
  }
}

🌐 Web 控制面板

ContextKeep 附带一个功能齐全的 Web UI，无需触碰 CLI 即可管理您的记忆。

• URL: http://localhost:5000

• 网格视图： 带有标签、字符计数和内联操作的记忆卡片

• 列表视图： 紧凑、可扫描的表格，按最后更新时间排序

• 日历视图： 按月份浏览您的记忆历史

• 搜索： 跨标题、键和内容的实时过滤

• 完整 CRUD： 在浏览器中创建、查看、编辑和删除记忆

• 导出： 一键下载所有记忆为 JSON (Ctrl+E)

手动启动：

./venv/bin/python webui.py

🐧 Linux 服务设置 (推荐用于家庭实验室)

将 MCP 服务器和 Web UI 作为持久的后台服务运行：

chmod +x install_services.sh
./install_services.sh

这将安装：

管理服务：

sudo systemctl status contextkeep-server
sudo systemctl restart contextkeep-webui

📋 更新日志

V1.3 — Harbor

• ✅ Docker 支持 — Dockerfile + docker-compose.yml 实现一键部署

• ✅ 现代打包 — pyproject.toml + uv 支持（同时保留 pip）

• ✅ 新增 MCP 工具：delete_memory() — 智能体现在可以删除记忆

• ✅ 新增 MCP 工具：get_memory_stats() — 一览记忆数量与大小

• ✅ 新增 MCP 工具：export_memories() — 完整的 JSON 备份

• ✅ WebUI：导出全部按钮，支持 Ctrl+E 快捷键

• ✅ WebUI：统计信息 API 端点

• ✅ 修复：移除 memory_manager.py 中的死代码

• ✅ 修复：添加缺失的 core/__init__.py 以支持 Docker/包导入

• ✅ 修复：将裸露的 except 替换为 except Exception

• ✅ 更新安装程序至 V1.3，支持 uv 检测

• ✅ 感谢社区贡献者 🙏

V1.2 — Obsidian Lab

• ✅ 新增 list_all_memories() MCP 工具 — 一次调用获取完整记忆目录

• ✅ Obsidian Lab UI 重设计 — 带有青色/霓虹色点缀的深色高级美学

• ✅ 标题栏实时记忆计数徽章

• ✅ 日历月份导航（前进/后退）

• ✅ 网格卡片现在显示标签和字符计数徽章

• ✅ 移除“最近记忆”侧边栏，以获得更整洁的日历布局

• ✅ 记忆索引协议 V1.2 — 标准化的两步智能体检索模式

V1.1

• 带有网格、列表和日历视图的 Web 控制面板

• 除 Stdio 外支持 SSE 传输

• Linux systemd 服务安装程序

• 记忆标题和时间戳

V1.0

• 核心 MCP 服务器，支持 store_memory、retrieve_memory、search_memories

• 基于 JSON 的持久化存储

• 支持 SSH 远程传输

🤝 贡献

欢迎贡献代码。提交 PR、提出问题或建议功能 — 所有的反馈都非常宝贵。

V1.3 社区贡献者

衷心感谢所有为 Harbor 版本做出贡献的人：

• @shuft — 开启了 Issue #1，请求 Docker 支持

• @Cyberdogs7 — PR #2：初步的 Docker 和 Docker Compose 实现

• @frehov — PR #3：Dockerfile、pyproject.toml、uv 支持、__init__.py 修复

• @thinkstylestudio — 社区推广

☕ 支持项目

如果 ContextKeep 为您节省了时间、Token 或精力，请考虑请我喝杯咖啡。