putao520/gmemory

gmemory

Generative Memory - MCP server for semantic conversation memory with Qdrant and Ollama

gmemory是一个基于Model Context Protocol (MCP)的服务器，为AI对话系统提供长期记忆能力。通过语义向量存储和检索，实现对话历史的持久化和智能查询。

✨ 核心特性

• 🧠 语义记忆: 使用Ollama + qwen3-embedding生成语义向量
• 🔍 智能检索: 基于Qdrant向量数据库的相似度搜索
• 📝 TODO管理: 自动追踪对话中的待办任务
• 🚀 高性能: Rust + gRPC，低延迟高吞吐
• 🔌 标准协议: 完全兼容MCP规范，可被任何MCP客户端使用
• 🛡️ 类型安全: 编译期类型检查，运行时错误少

🎯 使用场景

• AI助手长期记忆: 让AI记住之前的对话内容
• 上下文检索: 快速查找相关历史对话
• 任务跟踪: 自动管理对话中提到的TODO
• 知识库构建: 基于对话构建语义知识库

🏗️ 技术架构

┌─────────────────────────────────────────────────────────┐
│                    MCP Client                            │
│                 (Claude Code / etc.)                     │
└─────────────────┬───────────────────────────────────────┘
                  │ JSON-RPC via STDIO
                  ▼
┌─────────────────────────────────────────────────────────┐
│              gmemory MCP Server (Rust)                   │
│  ┌──────────────────────────────────────────────────┐  │
│  │  MCP Tools (rmcp SDK)                            │  │
│  │  - write_message  - search_messages              │  │
│  │  - query_todos                                   │  │
│  └──────────────┬───────────────────────────────────┘  │
│  ┌──────────────┴───────────────────────────────────┐  │
│  │  Services                                         │  │
│  │  - EmbeddingService (ollama-rs)                  │  │
│  │  - StorageService (qdrant-client)                │  │
│  └──────────────┬───────────────────────────────────┘  │
└─────────────────┼───────────────────────────────────────┘
         ┌────────┴────────┐
         ▼                 ▼
┌──────────────┐  ┌──────────────────┐
│   Ollama     │  │     Qdrant       │
│              │  │   Vector DB      │
│ qwen3-emb    │  │                  │
│ :0.6b        │  │ gRPC: 26333     │
└──────────────┘  └──────────────────┘

核心技术栈

• MCP框架: rmcp 0.5 (官方Rust SDK)
• 向量数据库: Qdrant >= 1.7.0
• Ollama客户端: ollama-rs 0.3.1
• 嵌入模型: qwen3-embedding:0.6b (通过Ollama)
• 异步运行时: Tokio 1.x

📦 安装

前置依赖

1. Rust >= 1.70

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   

2. Ollama >= 0.1.0

   # macOS/Linux
   curl -fsSL https://ollama.com/install.sh | sh
   
   # 下载qwen3-embedding模型
   ollama pull qwen3-embedding:0.6b
   

3. Qdrant >= 1.7.0

   # 使用Docker
   docker run -p 26333:6334 -p 26334:6333 \
       -v $(pwd)/qdrant_storage:/qdrant/storage \
       qdrant/qdrant
   

构建项目

# 克隆仓库
git clone https://github.com/yourusername/gmemory.git
cd gmemory

# 构建（开发模式）
cargo build

# 构建（发布模式）
cargo build --release

🚀 快速开始

1. 配置环境变量（可选）

创建 .env 文件：

# Ollama配置
OLLAMA_ENDPOINT=http://localhost:11434
OLLAMA_MODEL=qwen3-embedding:0.6b
# OLLAMA_API_KEY=  # 可选

# Qdrant配置
QDRANT_ENDPOINT=http://localhost
QDRANT_PORT=26333
# QDRANT_API_KEY=  # 可选

# 日志级别
RUST_LOG=info

2. 运行服务器

# 开发模式
cargo run

# 发布模式
./target/release/gmemory

3. 在MCP客户端中使用

Claude Code配置示例

在 .claude/mcp.json 中添加：

{
  "mcpServers": {
    "gmemory": {
      "command": "/path/to/gmemory/target/release/gmemory",
      "env": {
        "OLLAMA_ENDPOINT": "http://localhost:11434",
        "QDRANT_PORT": "26333"
      }
    }
  }
}

🛠️ MCP工具

write_message

写入对话消息到向量数据库。

参数:

{
  "session_id": "uuid-string",
  "role": "user|assistant|system",
  "content": "消息内容",
  "metadata": {}  // 可选
}

返回: 消息ID

search_messages

基于语义相似度搜索历史对话。

参数:

{
  "query": "搜索查询文本",
  "session_id": "uuid-string",  // 可选
  "limit": 10,  // 可选，默认10
  "min_score": 0.7  // 可选，默认0.0
}

返回: Top-K相似消息列表

query_todos

查询指定会话的未完成TODO任务。

参数:

{
  "session_id": "uuid-string",
  "include_completed": false  // 可选
}

返回: TODO任务列表

📖 文档

完整的设计文档和架构决策请参见 目录：

• - 需求规格
• - 系统架构
• - 数据结构
• - API设计
• - 变更日志

🔧 开发

项目结构

gmemory/
├── src/
│   ├── main.rs          # 入口
│   ├── config.rs        # 配置管理
│   ├── server.rs        # MCP服务器实现
│   ├── tools/           # 工具参数定义
│   ├── services/        # 业务逻辑
│   └── models/          # 数据模型
├── SPEC/                # 完整设计文档
├── Cargo.toml
└── README.md

运行测试

cargo test

代码风格

cargo fmt
cargo clippy

🤝 贡献

欢迎贡献！请查看 （待添加）了解详情。

开发流程

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'feat: Add AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 详见 文件

🙏 致谢

• Model Context Protocol - MCP规范
• rmcp - 官方Rust SDK
• Qdrant - 高性能向量数据库
• Ollama - 本地LLM运行时
• ollama-rs - Ollama Rust客户端

📬 联系方式

• 问题反馈: GitHub Issues
• 功能建议: GitHub Discussions

注意: 本项目目前处于 v1.0.0 开发阶段，API可能会有变化。