Calvin-Francis/memory-mcp

Memory MCP

🎯 Why This Project?

AI 助手（如 Claude、ChatGPT）在对话结束后会"失忆"。本项目通过 MCP (Model Context Protocol) 为 AI 提供：

• 跨会话记忆：用户偏好、历史对话、学习到的事实都能持久保存
• 语义检索：不是简单的关键词匹配，而是理解"意思相近"的内容
• 知识图谱：构建实体之间的关系网络，支持复杂推理

用户: "我之前说过喜欢什么编程语言？"
AI:   [调用 memory_search] → 找到 3 个月前的对话记录
      "您提到过喜欢 Rust 的内存安全特性，以及 Python 的简洁语法。"

✨ 核心特性

🧠 语义记忆系统

记忆衰减算法：

权重 = 置信度 × 时间衰减 × 访问加成
     = confidence × 0.9^(天数/30) × (1 + min(访问次数×0.05, 0.5))

🕸️ 知识图谱引擎

支持的反向关系映射：

uses ↔ is_used_by
depends_on ↔ is_dependency_of
contains ↔ is_contained_in
calls ↔ is_called_by
owns ↔ is_owned_by
creates ↔ is_created_by
manages ↔ is_managed_by

🏗️ 系统架构

┌────────────────────────────────────────────────────────────────┐
│                MCP Client (Claude Desktop / Windsurf)          │
└───────────────────────────┬────────────────────────────────────┘
                            │ JSON-RPC 2.0 over stdio
┌───────────────────────────▼────────────────────────────────────┐
│                      Memory MCP                         │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                    Tool Dispatcher                       │  │
│  │   memory_*  →  memoryService    graph_*  →  graphService │  │
│  └──────────────────────────────────────────────────────────┘  │
│                              │                                 │
│  ┌─────────────┐  ┌─────────▼─────────┐  ┌─────────────────┐   │
│  │   Memory    │  │    Embedding      │  │     Graph       │   │
│  │   Service   │  │    Service        │  │     Service     │   │
│  │             │  │  ┌─────────────┐  │  │                 │   │
│  │ • create    │  │  │ LRU Cache   │  │  │ • entities      │   │
│  │ • search    │  │  │ (1000 max)  │  │  │ • relations     │   │
│  │ • update    │  │  └──────┬──────┘  │  │ • transitive    │   │
│  │ • delete    │  │         │         │  │ • mermaid       │   │
│  │ • hybrid    │  │         ▼         │  │                 │   │
│  └──────┬──────┘  │  Aliyun DashScope │  └────────┬────────┘   │
│         │         │  text-embedding-v3│           │            │
│         │         └─────────┬─────────┘           │            │
│         └───────────────────┼─────────────────────┘            │
│                             │                                  │
└─────────────────────────────┼──────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│                   PostgreSQL 14+ with pgvector                  │
│  ┌────────────┐  ┌────────────┐  ┌───────────┐  ┌────────────┐  │
│  │  memories  │  │  entities  │  │ relations │  │  history   │  │
│  │            │  │            │  │           │  │            │  │
│  │ • HNSW idx │  │ • HNSW idx │  │ • FK refs │  │ • triggers │  │
│  │ • GIN tags │  │ • UNIQUE   │  │ • UNIQUE  │  │ • audit    │  │
│  └────────────┘  └────────────┘  └───────────┘  └────────────┘  │
└─────────────────────────────────────────────────────────────────┘

🚀 快速开始

环境要求

• Node.js >= 18.0.0
• PostgreSQL >= 14 + pgvector 扩展
• 阿里云 DashScope API Key（用于生成嵌入向量）

安装步骤

# 1. 克隆仓库
git clone https://github.com/YOUR_USERNAME/mcp-memory.git
cd mcp-memory

# 2. 安装依赖
npm install

# 3. 配置环境变量
cp .env.sample .env
# 编辑 .env 填入数据库连接和 API Key

# 4. 初始化数据库
psql -c "CREATE DATABASE mcp_memory;"
psql -d mcp_memory -f migrations/init.sql

# 5. 启动服务
npm start

MCP 客户端配置

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["C:/path/to/mcp-memory/src/server.js"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mcp_memory",
        "DASHSCOPE_API_KEY": "sk-your-api-key"
      }
    }
  }
}

Windsurf (mcp_config.json):

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["src/server.js"],
      "cwd": "C:/path/to/mcp-memory",
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mcp_memory",
        "DASHSCOPE_API_KEY": "sk-your-api-key"
      }
    }
  }
}

🛠️ 工具详解

记忆操作 (Memory Tools)

memory_create - 创建记忆

{
  "type": "preference",
  "content": { "topic": "编程语言", "preference": "喜欢 Rust 和 Python" },
  "source": "user_message",
  "tags": ["programming", "preferences"],
  "confidence": 0.95
}

memory_search - 语义搜索

{
  "query": "用户喜欢什么编程语言",
  "type": "preference",
  "tags": ["programming"],
  "limit": 5
}

工作原理：

1. 将查询文本转换为 1024 维向量
2. 使用 HNSW 索引计算余弦相似度
3. 按相似度排序返回结果
4. 异步更新访问统计（access_count, last_accessed_at）

memory_update - 更新记忆

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "content": { "updated": true },
  "confidence": 0.8
}

特性：内容变更时自动重新生成嵌入向量

memory_list - 列出记忆

{
  "type": "fact",
  "tags": ["important"],
  "limit": 20
}

memory_delete - 删除记忆

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

注意：删除操作会记录到 memory_history 表

知识图谱操作 (Graph Tools)

graph_create_entities - 创建实体

{
  "entities": [
    {
      "name": "Memory MCP",
      "entityType": "Project",
      "observations": [
        "使用 PostgreSQL + pgvector",
        "支持语义搜索",
        "MIT 开源协议"
      ]
    },
    {
      "name": "pgvector",
      "entityType": "Technology",
      "observations": ["PostgreSQL 向量扩展", "支持 HNSW 索引"]
    }
  ]
}

特性：

• 自动为实体生成嵌入向量（批量处理）
• 同名实体会合并观察记录（UPSERT）

graph_create_relations - 创建关系

{
  "relations": [
    {
      "from": "Memory MCP",
      "to": "pgvector",
      "relationType": "uses"
    }
  ]
}

自动双向关系：创建 A uses B 时自动创建 B is_used_by A

graph_add_observations - 添加观察

{
  "observations": [
    {
      "entityName": "Memory MCP",
      "contents": ["新增混合检索功能", "支持 Mermaid 导出"]
    }
  ]
}

graph_search_nodes - 搜索实体

{
  "query": "向量数据库",
  "semantic": true,
  "limit": 10
}

graph_open_nodes - 打开指定实体

{
  "names": ["Memory MCP", "pgvector"]
}

返回实体详情及其所有关联关系

graph_read - 读取完整图谱

返回所有实体和关系，适合小规模图谱

graph_delete_* - 删除操作

• graph_delete_entities: 删除实体（级联删除关系）
• graph_delete_relations: 删除指定关系
• graph_delete_observations: 删除实体的特定观察记录

📊 数据库设计

表结构

memories - 语义记忆表

entities - 实体表

relations - 关系表

memory_history - 历史记录表

索引策略

触发器与函数

⚙️ 配置参考

环境变量

示例 .env

# 数据库
DATABASE_URL=postgresql://postgres:password@localhost:5432/mcp_memory

# 阿里云 DashScope
DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

# 可选配置
DB_MAX_POOL_SIZE=10
SEARCH_DEFAULT_LIMIT=20

🔧 开发指南

# 开发模式（自动重载）
npm run dev

# 查看调试日志
Get-Content memory-debug.log -Wait  # PowerShell
tail -f memory-debug.log            # Linux/Mac

# 初始化数据库
npm run db:init

项目结构

mcp-memory/
├── src/
│   ├── server.js          # MCP 服务入口，JSON-RPC 处理
│   ├── config.js          # 配置加载
│   ├── db/
│   │   ├── index.js       # 数据库导出
│   │   └── pool.js        # 连接池管理
│   ├── services/
│   │   ├── memory.js      # 记忆服务（CRUD + 搜索）
│   │   ├── graph.js       # 知识图谱服务
│   │   └── embedding.js   # 嵌入生成 + LRU 缓存
│   ├── tools/
│   │   └── definitions.js # MCP 工具定义
│   └── utils/
│       ├── logger.js      # 日志工具
│       └── response.js    # JSON-RPC 响应格式化
├── migrations/
│   └── init.sql           # 数据库初始化脚本（幂等）
├── docs/
│   └── ROADMAP.md         # 开发路线图
├── .env.sample            # 环境变量模板
└── package.json

📈 性能优化

本项目已实现以下优化（详见 ）：

📜 许可证

本项目采用 开源。

🙏 致谢

• pgvector - PostgreSQL 向量相似度搜索扩展
• Model Context Protocol - MCP 协议规范
• Aliyun DashScope - 嵌入向量 API 提供商

🤝 贡献

欢迎提交 Issue 和 Pull Request！