Memory MCP

English

基于 MCP Streamable HTTP 的个人记忆服务：用 语义向量检索 + 知识图谱 持久化你的长期上下文，并支持对同一实体的记忆“演化”与冲突打标追溯。

特性

• MCP Streamable HTTP：不使用已废弃的 SSE
• Bearer Token 鉴权：/mcp 需要 Authorization: Bearer <token>（/health 免鉴权）
• 记忆演化而非覆盖：同一 entity_key 多版本链路可追溯（trace）
• 冲突判定与打标：命中也会判定并输出 labels：conflict / correction / reversal
• 语义检索：通过 OpenRouter Embedding API 获取向量，支持相似度检索（recall）
• 图谱关系：实体关系入/出边 + BFS 深度查询（relate / graph_query）
• 资源读取：提供 memory:///... 资源给 MCP Client（current/entities/entity）
• 可测试/可落盘：默认 LanceDB；可用 MEMORY_MCP_VECTOR_BACKEND=memory 作为无依赖后端

接口

• MCP Endpoint：/mcp（Streamable HTTP）
• 健康检查：/health

快速开始（本地）

1. 安装依赖：pip install .
2. 准备环境变量：cp .env.example .env 并填写至少：
   • MEMORY_MCP_AUTH_TOKEN
   • MEMORY_MCP_OPENROUTER_API_KEY
3. 启动：python -m memory_mcp
4. 验证：curl http://127.0.0.1:8765/health

Docker 部署（推荐）

1. 配置：cp .env.example .env 并填写必要变量
2. 构建并启动：docker compose up -d --build

说明：

• 当前 docker-compose.yml 默认不暴露 8765（避免直接公网暴露）。
• 若你需要在宿主机直接访问（本地调试），请在 memory-mcp service 增加端口映射：

  ports:
    - "8765:8765"
  

• 生产环境建议通过 Cloudflare Tunnel / 反向代理 暴露 HTTPS。

环境变量

.env.example 已包含可用模板：

• 必填
  • MEMORY_MCP_AUTH_TOKEN：鉴权 token
  • MEMORY_MCP_OPENROUTER_API_KEY：OpenRouter API Key
• 常用
  • MEMORY_MCP_HOST：默认 0.0.0.0
  • MEMORY_MCP_PORT：默认 8765
  • MEMORY_MCP_DATA_DIR：默认 ./data
  • MEMORY_MCP_DEBUG：默认 false
• Embedding
  • MEMORY_MCP_OPENROUTER_BASE_URL：默认 https://openrouter.ai/api/v1
  • MEMORY_MCP_EMBEDDING_MODEL：默认 openai/text-embedding-3-small
  • MEMORY_MCP_EMBEDDING_DIM：默认 1536
• 冲突判定（可选）
  • MEMORY_MCP_LLM_MODEL：默认 anthropic/claude-3-haiku
  • MEMORY_MCP_SIMILARITY_THRESHOLD：默认 0.85
• 向量后端（可选）
  • MEMORY_MCP_VECTOR_BACKEND：lancedb（默认）/ memory / auto
  • 说明：生产建议使用 lancedb；LanceDB 启动失败会中止服务，避免旧记忆被静默隐藏
  • memory 适合测试；auto 会在 LanceDB 初始化失败时切换到 memory
• Cloudflare Tunnel（可选）
  • CLOUDFLARE_TUNNEL_TOKEN

MCP 客户端配置示例

将域名与 token 替换为你自己的部署：

{
  "mcpServers": {
    "memory-mcp": {
      "url": "https://memory-mcp.your-domain.com/mcp",
      "transport": { "type": "http" },
      "headers": {
        "Authorization": "Bearer your-secure-token-here"
      }
    }
  }
}

Tools（工具）

• remember：写入/演化记忆（同 entity_key 自动演化与冲突打标）
• recall：按语义检索当前记忆（可选附带演化信息）
• recall_all：拉取全部当前记忆（用于初始化上下文）
• trace：追溯某实体的演化链（timeline/summary）
• forget：归档某实体当前记忆（不再作为 current）
• relate：创建实体关系边
• unrelate：按 relation id 删除实体关系边
• graph_query：按深度查询实体关系（入边+出边 BFS）

Resources（资源）

• memory:///current：当前全部记忆（JSON）
• memory:///entities：实体列表（JSON）
• memory:///entity/{entity_key}：实体演化历史（JSON）

数据落盘结构

默认目录为 ./data/：

data/
├── vectors/                # 向量（LanceDB 或 memories.json）
└── graph/                  # 图谱 JSON
    ├── entities.json
    ├── relations.json
    └── evolution_chains.json

开发与测试

• 安装开发依赖：pip install .[dev]
• 运行测试：pytest
• 静态检查：ruff check .

更多测试说明见：docs/testing.md

许可证

本项目采用 MIT License，详见 LICENSE。