MCP GitHub内存服务器
一个高性能的MCP（模型上下文协议）服务器，用Rust编写，将内存存储在GitHub存储库或本地文件系统中。
概述
此MCP服务器提供与基本内存协议的直接兼容性，同时提供以下强大功能：
- GitHub存储：将内存存储在具有完整版本历史记录的GitHub存储库中
- 本地存储：适用于气隙环境的离线第一本地文件系统存储
- 快速搜索：使用milli-core（LMDB）进行嵌入式全文搜索，BM25排名
- 加密：使用X25519的可选端到端加密
- 多项目：在孤立的项目中组织记忆
- 自动同步：每次写入操作后自动推送到远程
快速开始
安装
# Clone the repository
git clone https://github.com/yourusername/mcp-github-memory-server.git
cd mcp-github-memory-server
# Build the release binary
cargo build --release --features backend-github,index-tantivy,encryption,mcp-gitmem-storage-github/remote-git
# Install using the provided script
./scripts/install.shmacOS用户：如果遇到“Killed:9”错误，请运行：
./scripts/fix-macos-security.sh看 docs/故障排除/macos-security.md 了解详情。
配置
- 获取GitHub个人访问令牌 （适用于GitHub存储）：
- 访问：https://github.com/settings/tokens - 使用创建令牌 repo 范围 - 安全保存令牌
- 配置您的MCP客户端 （例如，光标）：
创建或编辑 ~/.cursor/mcp.json:
{
"mcpServers": {
"gitmem": {
"command": "/usr/local/bin/gitmem",
"args": ["serve", "--config", "/path/to/gitmem.yaml"],
"env": {
"GITHUB_TOKEN": "ghp_your_token_here"
}
}
}
}- 创建配置文件 （例如。，
~/.config/gitmem.yaml):
server:
transport: stdio
storage:
backend: github
github:
root: /Users/yourname/memory
auto_push: true
remote_url: https://github.com/yourusername/memory.git
credentials:
mode: token
username: x-access-token
secret_env: GITHUB_TOKEN
encryption:
enabled: false
index:
engine: tantivy- 重新启动MCP客户端 加载新配置。
建筑
┌─────────────────────────────────────────────────────────────────┐
│ MCP Client (IDE, Agent) │
│ JSON-RPC over stdio or WebSocket │
└──────────────┬──────────────────────────────────────────────────┘
│
JSON-RPC server (MCP)
│
┌──────────────▼─────────────────────┐
│ Memory Service Layer │
│ validation, ID generation, merge │
└──────────────┬─────────────────────┘
│
Storage abstraction
┌─────────┴───────────┬────────────┐
│ │ │
┌────▼────┐ ┌─────▼─────┐ ┌────▼─────┐
│ GitHub │ │ Local FS │ │ Ephemeral│
│ adapter │ │ adapter │ │ adapter │
└────┬────┘ └─────┬─────┘ └────┬─────┘
│ │ │
│ ┌────────────▼────────────┐
│ │ Search Index Engine │
│ │ (milli-core or Tantivy)│
│ └────────────┬────────────┘
│ │
│ ┌────────────▼────────────┐
│ │ Crypto (optional) │
│ │ age X25519 │
│ └─────────────────────────┘特性
MCP工具兼容性
与基本内存协议完全兼容，并具有扩展功能：
核心内存操作：
memory.save-创造新的回忆memory.get-按ID检索memory.search-带过滤器的全文搜索memory.update-修补现有内存memory.delete-软删除或硬删除memory.import.basic-从JSONL导入memory.sync-与存储后端同步
项目管理：
list_memory_projects-列出所有项目create_memory_project-创建新项目delete_memory_project-删除项目
知识库（基本内存兼容性）：
write_note,read_note,edit_note,delete_notesearch_notes,recent_activity,build_contextmove_note-在项目之间移动笔记
外部文件夹链接：
project.link_folder-链接外部文件夹（例如黑曜石保险库）project.unlink_folder-删除链接文件夹project.list_links-列出所有文件夹链接
存储后端
GitHub存储：
- 完整的git历史记录和审计跟踪
- 设备特定分支(
devices/) - 每次写入时自动推送（可选）
- 通过三方合并解决冲突
- 拉取请求工作流（可选）
本地存储：
- 离线首次操作
- 使用fsync进行原子文件操作
- 用于并发访问的文件锁
- 与GitHub相同的磁盘布局，便于迁移
搜索和索引
- 毫内核（默认）：嵌入式LMDB指数，BM25评分
- 坦特维（可选）：替代高性能搜索引擎
- 异步索引：通过后台worker进行非阻塞索引更新
- TTL执行：查询时自动过期
- 现场增压：优先考虑标题匹配而非内容
安全
- 可选加密：年龄X25519端到端加密
- 多个收件人：安全地共享加密记忆
- 凭据管理：环境变量、操作系统钥匙链或助手
- 最小特权：细粒度的GitHub令牌作用域
- PII编辑：可配置的内容过滤器
文档
发展
先决条件
- 锈蚀1.89.0或更高版本（在
rust-toolchain.toml) - Git
- 可选：Docker用于容器化构建
建筑
# Default build with milli-core index
cargo build --workspace
# With all features
cargo build --workspace --features backend-github,backend-local,index-tantivy,encryption,transport-stdio,mcp-gitmem-storage-github/remote-git
# With real Tantivy backend (non-Apple ARM)
cargo build --workspace --features real_tantivy,backend-github,index-tantivy,encryption
# Release build
cargo build --release --features backend-github,index-tantivy,encryption,mcp-gitmem-storage-github/remote-git测试
# Run all tests
cargo test --workspace
# Run with all features
cargo test --workspace --all-features
# Run benchmarks
cargo bench -p mcp-gitmem-benchmarks --bench performance代码质量
# Format code
cargo fmt --all
# Run linter
cargo clippy --all-targets -- -D warnings -D clippy::pedantic -A clippy::module_name_repetitions
# Check for security issues
cargo audit项目结构
.
├── crates/
│ ├── core/ # Domain model, validation, types
│ ├── proto/ # MCP protocol definitions
│ ├── storage/
│ │ ├── github/ # GitHub adapter
│ │ ├── local/ # Local filesystem adapter
│ │ └── ephemeral/ # In-memory adapter (testing)
│ ├── index/
│ │ └── tantivy/ # Search index implementations
│ ├── crypto/ # Encryption (age X25519)
│ ├── server/ # MCP server runtime
│ ├── cli/ # Command-line interface
│ ├── compat/ # Basic memory compatibility
│ ├── testing/ # Test utilities and fixtures
│ └── benchmarks/ # Performance benchmarks
├── docs/ # Documentation
├── examples/ # Sample configurations
└── scripts/ # Installation and utility scripts演出
- 保存：p50\每秒1k次写入本地索引
- 记忆：\<50 MiB基线空闲
看 基准 查看详细的性能数据。
贡献
欢迎投稿！请阅读 代理商.md 用于：
- 架构指南
- 编码标准
- 测试要求
- 提交流程
开发工作流程
- 分叉存储库
- 创建要素分支
- 按照编码标准进行更改
- 运行测试和过梁
- 提交拉取请求
路线图
当前版本（v1.0）
- ✅ 基本内存协议兼容性
- ✅ GitHub和本地存储后端
- ✅ 使用milli-core进行全文搜索
- ✅ 可选加密
- ✅ 自动推送支持
- ✅ 外部文件夹链接
v1.1（计划中）
- Webhook支持远程同步
- 自动PR工作流程
- 冲突解决UI
- 增强可观察性（开放遥测）
v1.2（未来）
- 可选嵌入本地模型
- 混合搜索（BM25+矢量）
- 重新排名策略
- 链接文件夹的本地平台监视器
v2.0（未来）
- 多租户支持
- 每个租户的加密密钥
- 基于策略的访问控制
- 协作内存工作流
许可证
根据以下任一方式获得许可：
- Apache许可证，版本2.0(特许通行证 或http://www.apache.org/licenses/LICENSE-2.0)
- MIT许可证(许可证-麻省理工学院 或http://opensource.org/licenses/MIT)
由您选择。
致谢
支持
- 问题:
- 文档: docs/
- 讨论:
______________________________________________________________________
由以下材料制成❤️ MCP GitMem团队