MCP内存守护者
项目介绍
MCP Memory Keeper - Claude Code Context Management
一个提供持久上下文管理的MCP服务器，专为Claude AI编码助手设计。再也不用担心在压缩过程中丢失上下文了！这个MCP服务器帮助Claude Code在会话之间维护上下文，保存您的工作历史、决策和进度。
🚀 快速开始
在30秒内开始使用：
# 将memory-keeper添加到Claude
claude mcp add memory-keeper npx mcp-memory-keeper
# 开始新的Claude会话并使用它！
# 尝试：分析当前仓库并将分析结果保存到memory-keeper中
就这样！Memory Keeper现在可以在所有Claude会话中使用了。您的上下文存储在~/mcp-data/memory-keeper/中，并且会在会话之间持续存在。
🚀 实用的Memory Keeper工作流程示例
自定义命令 + CLAUDE.md = 自动上下文管理
CLAUDE.md（简化示例）
# 项目配置
## 开发规则
- 始终使用memory-keeper跟踪进度
- 保存架构决策和测试结果
- 在上下文限制之前创建检查点
## 质量标准
- 所有测试必须通过才能标记为完成
- 记录实际与预期的结果
自定义命令示例：/my-dev-workflow
# 我的开发工作流
当处理提供的项目时：
- 使用memory-keeper，通道：<项目名称>
- 在每个主要里程碑处保存进度
- 使用类别："decision"记录所有决策
- 使用类别："progress"跟踪实施状态
- 在声明任何内容已完成之前，保存测试结果
## 工作流步骤
1. 使用项目名称作为通道初始化会话
2. 在调查期间保存发现
3. 在重大更改之前创建检查点
4. 记录实际工作的内容与应该工作的内容
使用示例
用户：/my-dev-workflow authentication-service
AI：正在设置authentication-service的工作流。
[使用memory-keeper，通道："authentication-service"]
[... AI工作，自动保存上下文...]
用户："接近上下文限制。创建检查点并给我一个键"
AI："已创建检查点：authentication-service-checkpoint-20250126-143026"
[继续工作直到上下文重置或手动压缩]
用户："从键恢复：authentication-service-checkpoint-20250126-143026"
AI："已恢复！继续OAuth实现。我们完成了令牌验证，正在处理刷新逻辑..."
模式：
- 自定义命令包括使用memory-keeper的指令
- AI自动遵循这些指令
- 当您注意到对话变长时，您需要请求Claude保存一个检查点（就像在进行BOSS战之前保存游戏一样）
- 当Claude空间不足并重新开始时，您需要告诉它使用检查点键恢复
🎯 关键特性： Memory Keeper是一个共享板！您可以：
- 在重置后继续同一会话
- 开始全新的会话并恢复
- 并行运行多个Claude会话，所有会话共享相同的内存
- 一个会话可以保存另一个会话检索的上下文
这使得强大的工作流程成为可能，例如一个Claude会话进行研究，而另一个会话实施代码，两者都通过Memory Keeper共享发现！
为什么选择MCP Memory Keeper？
Claude Code用户经常面临上下文丢失的问题，因为对话窗口填满了。这个MCP服务器通过为Claude AI提供持久的记忆层解决了这个问题。无论您是在进行复杂的重构、多文件更改还是长时间的调试会话，Memory Keeper都能确保您的Claude助手记住重要的上下文、决策和进度。
完美适用于：
- 长时间的Claude Code编码会话
- 需要上下文保存的复杂项目
- 使用Claude AI进行协作开发的团队
- 想要在Claude会话之间保持持久上下文的开发者
特性
- 🔄 在Claude Code会话之间保存和恢复上下文
- 📁 文件内容缓存及变化检测
- 🏷️ 使用类别和优先级组织上下文
- 📺 通道 - 基于主题的持久组织（自动从git分支派生）
- 📸 检查点系统以完全捕获上下文快照
- 🤖 智能压缩助手，永远不会丢失关键信息
- 🔍 跨所有保存的上下文进行全文搜索
- 🕐 增强过滤 - 时间查询、正则表达式模式、分页
- 📊 变更追踪 - 查看自任意点以来添加、修改或删除的内容
- 💾 导出/导入用于备份和共享
- 🌿 与git集成，自动关联上下文
- 📊 AI友好的总结，具有优先级意识
- 🚀 基于SQLite的快速存储，针对Claude优化
- 🔁 批处理操作 - 原子地保存、更新或删除多项
- 🔄 通道重新分配 - 根据模式在通道之间移动项
- 🔗 上下文关系 - 使用类型化关系链接相关项
- 👁️ 实时监控 - 使用过滤器监视上下文变化
安装
推荐：NPX安装
claude mcp add memory-keeper npx mcp-memory-keeper
此单一命令：
- ✅ 始终使用最新版本
- ✅ 自动处理所有依赖项
- ✅ 跨macOS、Linux和Windows工作
- ✅ 无需手动构建或处理本机模块问题
其他安装方法
<details> <summary>全局安装</summary>npm install -g mcp-memory-keeper
claude mcp add memory-keeper mcp-memory-keeper
# 1. 克隆仓库
git clone https://github.com/mkreyman/mcp-memory-keeper.git
cd mcp-memory-keeper
# 2. 安装依赖项
npm install
# 3. 构建项目
npm run build
# 4. 添加到Claude
claude mcp add memory-keeper node /绝对路径/to/mcp-memory-keeper/dist/index.js
配置
环境变量
存储和安装
DATA_DIR- 数据库存储目录（默认：~/mcp-data/memory-keeper/）MEMORY_KEEPER_INSTALL_DIR- 安装目录（默认：~/.local/mcp-servers/memory-keeper/）MEMORY_KEEPER_AUTO_UPDATE- 设置为1启用自动更新
令牌限制配置
MCP_MAX_TOKENS- 响应中允许的最大令牌数（默认：25000，范围：1000-100000）- 如果您的MCP客户端有不同的限制，请调整此值
MCP_TOKEN_SAFETY_BUFFER- 安全缓冲百分比（默认：0.8，范围：0.1-1.0）- 只使用最大令牌数的这一部分以防止溢出
MCP_MIN_ITEMS- 即使超出限制也要返回的最小项数（默认：1，范围：1-100）- 确保至少返回一些结果
MCP_MAX_ITEMS- 每个响应中允许的最大项数（默认：100，范围：10-1000）- 不管令牌限制如何，结果集的上限
MCP_CHARS_PER_TOKEN- 每个令牌的字符比率（默认：3.5，范围：2.5-5.0）[高级]- 调整不同类型内容的令牌估计准确性
- 较低值 = 更保守（更安全但返回较少项）
- 较高值 = 更激进（返回更多项但风险溢出）
严格的令牌限制示例配置：
export MCP_MAX_TOKENS=20000 # 较少的最大令牌数
export MCP_TOKEN_SAFETY_BUFFER=0.7 # 更保守的缓冲
export MCP_MAX_ITEMS=50 # 每次响应较少项
export MCP_CHARS_PER_TOKEN=3.0 # 更保守的估算（可选）
Claude Code（CLI）
配置范围
选择保存配置的位置：
# 项目特定（默认）- 仅在此项目中为您
claude mcp add memory-keeper npx mcp-memory-keeper
# 通过.mcp.json与团队共享
claude mcp add --scope project memory-keeper npx mcp-memory-keeper
# 在所有项目中可用
claude mcp add --scope user memory-keeper npx mcp-memory-keeper
验证配置
# 列出所有配置的服务器
claude mcp list
# 获取Memory Keeper的详细信息
claude mcp get memory-keeper
Claude桌面应用
- 打开Claude桌面设置
- 导航至“开发者”→“模型上下文协议”
- 点击“添加MCP服务器”
- 添加以下配置：
{
"mcpServers": {
"memory-keeper": {
"command": "npx",
"args": ["mcp-memory-keeper"]
}
}
}
就这样！无需路径 - npx会自动处理一切。
验证安装
对于Claude Code：
- 重启Claude Code或开始新会话
- Memory Keeper工具应自动可用
- 测试：
mcp_memory_save({ key: "test", value: "Hello Memory Keeper!" }) - 如果不起作用，请检查服务器状态：
claude mcp list # 应显示memory-keeper为"运行中"
对于Claude桌面：
- 添加配置后重启Claude桌面
- 在新对话中，Memory Keeper工具应可用
- 使用上面的相同命令测试
故障排除
如果Memory Keeper不起作用：
# 移除并重新添加服务器
claude mcp remove memory-keeper
claude mcp add memory-keeper npx mcp-memory-keeper
# 检查日志中的错误
# 服务器输出将在Claude Code的输出面板中出现
更新到最新版本
使用npx安装方法时，每次都会自动获取最新版本！无需手动更新。
如果您使用的是全局安装方法：
# 更新到最新版本
npm update -g mcp-memory-keeper
# 开始新的Claude会话
# 更新的功能将立即可用
注意：更新后无需在Claude中重新配置MCP服务器。只需开始新的会话！
使用
会话管理
// 开始新会话
mcp_context_session_start({
name: '功能开发',
description: '正在开发用户认证',
});
// 使用项目目录启动会话以进行git跟踪
mcp_context_session_start({
name: '功能开发',
description: '正在开发用户认证',
projectDir: '/path/to/your/project',
});
// 使用默认通道启动会话
mcp_context_session_start({
name: '功能开发',
description: '正在开发用户认证',
projectDir: '/path/to/your/project',
defaultChannel: 'auth-feature', // 如果未指定，将从git分支自动派生
});
// 为当前会话设置项目目录
mcp_context_set_project_dir({
projectDir: '/path/to/your/project',
});
// 列出最近的会话
mcp_context_session_list({ limit: 5 });
// 继续之前的会话
mcp_context_session_start({
name: '功能开发继续',
continueFrom: 'previous-session-id',
});
使用通道（新增于v0.10.0）
通道提供了持久的主题组织，即使会话崩溃和重启也能存活：
// 通道将从git分支自动派生（如果设置了projectDir）
// 分支"feature/auth-system"变为通道"feature-auth-system"（最多20个字符）
// 保存到特定通道
mcp_context_save({
key: 'auth_design',
value: '使用JWT和刷新令牌',
category: 'decision',
priority: 'high',
channel: 'auth-feature', // 显式设置通道
});
// 从特定通道获取项
mcp_context_get({ channel: 'auth-feature' });
// 跨所有通道获取项（默认行为）
mcp_context_get({ category: 'task' });
// 通道跨会话持久 - 完美适用于：
// - 多分支开发
// - 特定功能的上下文
// - 团队在不同主题上的协作
增强的上下文存储
// 使用类别和优先级保存
mcp_context_save({
key: 'current_task',
value: '实现OAuth集成',
category: 'task',
priority: 'high',
});
// 保存决策
mcp_context_save({
key: 'auth_strategy',
value: '使用24小时过期的JWT令牌',
category: 'decision',
priority: 'high',
});
// 保存进度笔记
mcp_context_save({
key: 'progress_auth',
value: '已完成用户模型，正在生成令牌',
category: 'progress',
priority: 'normal',
});
// 按类别检索
mcp_context_get({ category: 'task' });
// 检索特定项
mcp_context_get({ key: 'current_task' });
// 从特定会话检索上下文
mcp_context_get({
sessionId: 'session-id-here',
category: 'decision',
});
// 增强过滤（新增于v0.10.0）
mcp_context_get({
category: 'task',
priorities: ['high', 'normal'],
includeMetadata: true, // 获取时间戳、大小信息
sort: 'created_desc', // created_asc/desc, updated_asc/desc, priority
limit: 10, // 分页
offset: 0,
});
// 时间查询（新增于v0.10.0）
mcp_context_get({
createdAfter: '2025-01-20T00:00:00Z',
createdBefore: '2025-01-26T23:59:59Z',
includeMetadata: true,
});
// 正则匹配（新增于v0.10.0）
mcp_context_get({
keyPattern: 'auth_.*', // 匹配键的正则表达式
category: 'decision',
});
文件缓存
// 缓存文件内容以进行变化检测
mcp_context_cache_file({
filePath: '/src/auth/user.model.ts',
content: fileContent,
});
// 检查文件是否发生变化
mcp_context_file_changed({
filePath: '/src/auth/user.model.ts',
currentContent: newFileContent,
});
// 获取当前会话状态
mcp_context_status();
完整的工作流程示例
// 1. 开始新会话
mcp_context_session_start({
name: '设置重构',
description: '为了更好的性能重构设置模块',
});
// 2. 保存高优先级任务
mcp_context_save({
key: 'main_task',
value: '重构Settings.Context以使用行为',
category: 'task',
priority: 'high',
});
// 3. 缓存重要文件
mcp_context_cache_file({
filePath: 'lib/settings/context.ex',
content: originalFileContent,
});
// 4. 在工作中保存决策
mcp_context_save({
key: 'architecture_decision',
value: '将设置拆分为读写模块',
category: 'decision',
priority: 'high',
});
// 5. 跟踪进度
mcp_context_save({
key: 'progress_1',
value: '已完成行为定义，剩余5个模块',
category: 'progress',
priority: 'normal',
});
// 6. 在上下文窗口填满之前
mcp_context_status(); // 检查已保存的内容
// 7. 在Claude Code重启后
mcp_context_get({ category: 'task', priority: 'high' }); // 获取高优先级任务
mcp_context_get({ key: 'architecture_decision' }); // 获取特定决策
mcp_context_file_changed({ filePath: 'lib/settings/context.ex' }); // 检查变化
检查点（第二阶段）
创建整个上下文的命名快照，稍后可以恢复：
// 在重大更改之前创建检查点
mcp_context_checkpoint({
name: 'before-refactor',
description: '重大设置重构前的状态',
includeFiles: true, // 包含缓存文件
includeGitStatus: true, // 捕获git状态
});
// 继续工作...
// 如果出现问题，从检查点恢复
mcp_context_restore_checkpoint({
name: 'before-refactor',
restore