远程内存mcp服务器
远程内存MCP服务器
一个集成了GitHub的远程内存管理MCP服务器，它将知识图数据与GitHub存储库同步，以进行远程存储和协作。
特性
- 实体、关系和观察的CRUD操作
- 与GitHub存储库实时同步
- 冲突检测与解决
- 自动/手动同步选项
- 搜索和过滤功能
- 项目级内存隔离 （v1.4.0）
- 多个项目，每个项目都有独立的内存 - 持续活动项目（存储在GitHub中 memory/index.json) - 每次调用项目覆盖，不切换活动项目
- 增强的实体查询功能 （v1.3.0）
- 实体列表检索（带过滤、排序、分页） - 快速查找实体名称 - 实体类型统计 - 日期范围过滤
- 增强的提交消息（可定制）
- 备份功能（每个项目）
- 提交历史跟踪
- 可选自动推送（auto_push环境变量）
- 本地镜像模式 （v2）：将活动项目的图持久化为人择内存规范格式的本地JSONL文件，以便外部工具（如图视图）可以直接读写它。包括用于多PC安全的发散防护。
安装
cd C:\YOUR_PATH\remote-memory-mcp
npm install
npm run build配置
必需参数
GITHUB_TOKEN：GitHub个人访问令牌（需要repo权限）GITHUB_OWNER：GitHub存储库所有者GITHUB_REPO：GitHub存储库名称
可选参数
GITHUB_BRANCH：要使用的分支名称（默认：main）SYNC_INTERVAL：自动同步间隔（秒）（手动为0）AUTO_PUSH：CRUD操作后自动推送（true/false，默认值：false）PROJECT_NAME：启动时的活动项目（默认值：从memory/index.json，回退："default")LOCAL_MIRROR_PATH：本地JSONL镜像文件的绝对路径（v2）。设置后，每个突变 活跃的 项目以人类记忆规范格式镜像到此文件中。外部工具（如图形视图）可以读写同一个文件。Unset=遗留行为（仅在内存+GitHub中）。
Claude桌面设置
添加到您的 claude_desktop_config.json 文件：
{
"mcpServers": {
"remote-memory": {
"command": "node",
"args": ["C://YOUR_PATH//remote-memory-mcp//dist//index.js"],
"env": {
"GITHUB_TOKEN": "YOUR_GITHUB_TOKEN_HERE",
"GITHUB_OWNER": "YOUR_GITHUB_USERNAME",
"GITHUB_REPO": "YOUR_GITHUB_REPO",
"GITHUB_BRANCH": "main",
"SYNC_INTERVAL": "0",
"AUTO_PUSH": "false",
"PROJECT_NAME": "my-project"
}
}
}
}用法
有关API的详细用法和示例，请参见 规格.md.
项目级内存（v1.4.0）
每个项目在GitHub存储库中独立存储内存：
memory/
├── index.json ← project index + active project pointer
├── graph.json ← "default" project (backward compatible)
├── blog/
│ └── graph.json ← "blog" project
└── my-app/
└── graph.json ← "my-app" project快速开始
// 1. Create a project
create_project({ name: "blog", description: "Blog memory" })
// 2. Switch to it
switch_project({ project: "blog" })
// 3. Work normally — all tools now target "blog"
create_entities({ entities: [...] })
// 4. Access another project without switching
read_graph({ project: "my-app" })活动项目优先级
PROJECT_NAME env 是 → memory/index.json → "default"
本地镜像模式（v2）
集 LOCAL_MIRROR_PATH 要启用镜像 活动项目 将图形转换为人类内存规范格式的本地JSONL文件。外部工具（如图视图）可以读写同一个文件，在远程内存支持的图上为用户提供一个UI，而图视图不需要了解GitHub。
行为
- 独自创立：如果镜像文件存在 *和* 它的侧车(
.sync-state.json)命名当前活动的项目，从镜像加载远程内存（更喜欢用户的本地编辑而不是GitHub）。否则，GitHub将被拉取，镜像将被播种。 - 每次工具调用前：检查镜像时间；如果它发生了变化（外部写入程序），内存中的图形将从镜像重新加载。
- 每次突变后：内存中的图被原子性地写回镜像(
.tmp+重命名）。如果在操作（竞争）期间从外部修改了文件，则会回滚内存中的突变并显示错误。 - JSONL行格式：兼容MCP的人择存储器--
{"type":"entity"|"relation", ...}可选createdAt/updatedAt扩展字段。读取时，未知字段会自动删除。 - 每次呼叫
project以（权力）否决 （例如。read_graph({ project: "blog" }))确实如此 不 触摸镜子——镜子总是代表活动项目。 switch_project用新的活动项目的图重写镜像，并更新sidecar。
发散防护（多PC安全）
当同一GitHub仓库在多台机器上共享时， sync_pull / sync_push 遵循此策略（仅限活动项目）：
| 国家 | sync_pull 结果 |
|---|---|
| 仅GitHub更改 | 正常拉取，镜像更新（状态： pulled) |
| 仅本地更改 | 跳过拉取，建议 sync_push （状态： local-only) |
| 两者都发生了变化（分歧） | 拉拒绝，选择 force_sync （状态： diverged) |
| 均未更改 | 无操作（状态： up-to-date) |
sync_push 应用相同的基线检查——如果GitHub自上次同步以来一直处于高级状态，则推送将被拒绝(remote-ahead). force_sync 是逃生口，绕过两个警卫。
基线（最后一次拉取SHA+图摘要+项目名称）被持久化到sidecar文件中(.sync-state.json)因此，它能够在进程重启后幸存下来。 sidecar归远程内存所有；外部工具不得对其进行修改。
图形视图集成示例
{
"mcpServers": {
"remote-memory": {
"command": "node",
"args": ["C:/YOUR_PATH/remote-memory-mcp/dist/index.js"],
"env": {
"GITHUB_TOKEN": "ghp_...",
"GITHUB_OWNER": "...",
"GITHUB_REPO": "...",
"LOCAL_MIRROR_PATH": "D:/memory/memory.jsonl"
}
},
"graph-view": {
"command": "node",
"args": ["D:/mcpapps/graph-view/dist/server.js"],
"env": {
"MEMORY_FILE_PATH": "D:/memory/memory.jsonl"
}
}
}
}图形视图自动检测 LOCAL_MIRROR_PATH （通过env或 mcpServers.remote-memory.env)并自动切换到镜像后端。
数据结构
内存数据按项目存储在GitHub存储库中：
{
"entities": {
"Kim Kim": {
"name": "Kim Kim",
"entityType": "Person",
"observations": ["Software developer", "Lives in Seoul"],
"createdAt": "2025-01-01T00:00:00.000Z",
"updatedAt": "2025-01-01T00:00:00.000Z"
}
},
"relations": [
{
"from": "Kim Kim",
"to": "Company ABC",
"relationType": "works_at",
"createdAt": "2025-01-01T00:00:00.000Z"
}
],
"metadata": {
"version": "1.0.0",
"lastModified": "2025-01-01T00:00:00.000Z",
"lastSync": "2025-01-01T00:00:00.000Z"
}
}建筑
核心组件
- GitHubClient：处理GitHub API交互
- 内存图示管理器：管理内存中的知识图
- 同步管理器：处理同步和项目管理
- 远程内存MCP服务器：主MCP服务器类
同步策略
- 冲突解决：根据最新修改时间戳进行优先级排序
- 自动推送：立即将本地更改推送到远程
- 自动拉：按配置的时间间隔检查远程更改
- 强制同步：执行双向同步，忽略冲突
重要说明
- 需要GitHub个人访问令牌（具有repo权限）
- GitHub API限制：通过身份验证的用户每小时5000次请求
- 需要网络连接
- 项目名称：字母数字、连字符、下划线；
"default"已预订
许可证
MIT许可证-免费使用、修改和分发
更新日志
v1.4.0版本
- 项目级内存隔离
- list_projects：列出所有项目和活动项目 - create_project：创建新的独立项目 - switch_project：切换活动项目（持久化到GitHub）
project所有工具上的参数：每次通话都针对任何项目，无需切换- 每个项目的备份路径:
backups/{project}/backup-*.json - 添加
PROJECT_NAME环境变量 - 服务器版本升级到1.4.0
v1.3.0版本
- 新的查询工具
- list_entities：检索实体列表（带过滤、排序、分页） - get_entity_names：快速查找实体名称 - get_entity_types：实体类型统计
- 增强的查询功能
- EntityType筛选 - 日期范围过滤（基于createdAt） - 排序选项（createdAt、updatedAt、name） - 分页（限制、偏移）
- 改进了对大型数据集的处理
v1.2.0版本
- 防止初始化时不必要的自动提交
- 为可选的自动推送添加了AUTO_PUSH环境变量
- 添加了防止推送空图的逻辑
- 改进了初始负载状态跟踪
v1.1.0版本
- 自定义提交消息支持
- 添加备份系统(
create_backup) - 提交历史跟踪(
get_commit_history) - 自动生成提交消息
v1.0.0
- 初始版本