Context Keep

ContextKeep Banner

上下文保持🧠

AI代理的无限长期记忆

](https://github.com/mordang7/ContextKeep)      ](https://docs.docker.com/) 

上下文保持 是一个强大的独立内存服务器，为您的AI代理（Claude、Cursor、Gemini、OpenCode等）提供持久的、可搜索的大脑。别再重复了——让你的AI永远记住一切。

特性 • V1.3的新增功能 • 安装 • MCP工具 • 网络仪表盘 • 配置

______________________________________________________________________

🌟 特性

• ♾️ 无限上下文： 存储无限的项目详细信息、首选项、决策和片段——没有到期日，没有大小上限。
• 💰 节省资金和代币： 只提取重要的内存，大幅削减上下文窗口的使用和API成本。
• 🔌 通用兼容性： 适用于 *任何* 通过Stdio（本地）或SSE（远程/家庭实验室）的MCP兼容客户端。
• 🧭 内存索引协议： 可靠的两步检索系统-- list_all_memories() → retrieve_memory() --所以特工每次都能找到正确的钥匙。
• 🖥️ 现代网络仪表板： 在时尚的深色界面中，使用网格、列表和日历视图直观地管理您的记忆。
• 🔒 隐私第一： 100%本地存储。您的数据永远不会接触到外部服务器。
• 🔎 智能搜索： 在所有内存内容中进行关键字和语义搜索。
• 🐧 Linux服务： 作为systemd服务在后台静默运行。
• 🐳 Docker就绪： 使用Docker Compose进行一次命令部署。
• ⬇️ 导出和备份： 通过MCP工具或WebUI将所有内存导出为JSON。

______________________________________________________________________

ContextKeep Showcase

______________________________________________________________________

🆕 V1.3中的新功能--Harbor

🐳 Docker支持

#1社区请求。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导出

• 导出全部 工具栏中的按钮（或按 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

1. 运行安装程序：

- Linux/macOS：

     python3 install.py

- 窗户：

     python install.py

1. 跟随向导： 安装程序创建一个虚拟环境，安装依赖项，并生成一个即用型 mcp_config.json.

选项2:uv（快速）

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

选项3:Docker（推荐用于Homelabs）

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桌面/Gemini CLI/光标）

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

选项2：通过SSH远程连接（Homelab/Raspberry Pi）

在家庭服务器上运行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"
    }
  }
}

______________________________________________________________________

🌐 网络仪表盘

ContextKeep附带了功能齐全的web UI，无需触摸CLI即可管理您的记忆。

• 网址： http://localhost:5000
• 网格视图： 带有标签芯片、字符计数和内联操作的存储卡
• 列表视图： 密集、可扫描的表格，所有内存按上次更新时间排序
• 日历视图： 按月浏览您的记忆历史记录
• 搜索： 实时过滤标题、关键字和内容
• 完整CRUD： 在浏览器中创建、查看、编辑和删除记忆
• 出口： 一键下载所有JSON格式的内存(Ctrl+E)

要手动启动，请执行以下操作：

./venv/bin/python webui.py

______________________________________________________________________

🐧 Linux服务设置（建议用于Homelabs）

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

chmod +x install_services.sh
./install_services.sh

这将安装：

管理服务：

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

______________________________________________________________________

📋 更新日志

V1.3--港口

• ✅ 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--黑曜石实验室

• ✅ 新 list_all_memories() MCP工具--一次调用完成内存目录
• ✅ 黑曜石实验室UI重新设计——带有青色/霓虹色调的深色高级美学
• ✅ 标题中的内存计数实时徽章
• ✅ 日历月导航（前进/后退）
• ✅ 网格卡现在显示标签芯片和字符计数徽章
• ✅ 删除了“最近的回忆”侧边栏，以实现更清晰的日历布局
• ✅ 内存索引协议V1.2——标准化的两步代理检索模式

V1.1

• 具有网格、列表和日历视图的Web仪表板
• 与Stdio一起提供SSE运输支持
• Linux系统服务安装程序
• 内存标题和时间戳

V1.0

• 核心MCP服务器 store_memory, retrieve_memory, search_memories
• JSON支持的持久存储
• SSH远程传输支持

______________________________________________________________________

🤝 贡献

欢迎捐款。打开一个PR，提交一个问题，或建议一个功能——所有的输入都受到赞赏。

V1.3社区贡献者

非常感谢所有为Harbor发布做出贡献的人：

• @thinkstylestudy --社区宣传

☕ 支持项目

如果ContextKeep为你节省了时间、代币或理智——考虑给我买杯咖啡。


______________________________________________________________________

Built with ❤️ by GeekJohn