AI导哈

记忆向量检索服务

基于语义向量检索和知识图谱的个人记忆服务，支持记忆演化与冲突追溯。

  • by kassol
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 kassol/memory-mcp

使用说明

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。

相关 MCP