MCP内存守护者

Name: MCP内存守护者
Author: mkreyman

作者：mkreyman68 星标更新：2025-10-10

安装使用来源：spider==github.com

项目介绍

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工作
✅ 无需手动构建或处理本机模块问题

其他安装方法

npm install -g mcp-memory-keeper
claude mcp add memory-keeper mcp-memory-keeper

</details> <details> <summary>从源码安装（用于开发）</summary>

# 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

</details>

配置

环境变量

存储和安装

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