Memory MCP

为 AI 助手提供持久化语义记忆与知识图谱能力的 MCP 服务器

A Model Context Protocol server providing persistent semantic memory and knowledge graph capabilities for AI assistants

🎯 Why This Project?

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

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

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

✨ 核心特性

🧠 语义记忆系统

特性	说明
向量嵌入	使用阿里云 DashScope `text-embedding-v3` 模型，1024 维向量
HNSW 索引	pgvector 的高性能近似最近邻搜索，毫秒级响应
混合检索	向量相似度 (70%) + 关键词匹配 (30%) 加权融合
记忆衰减	基于访问频率和时间的自动权重调整，防止信息过载
LRU 缓存	嵌入向量缓存（最大 1000 条），减少 80%+ API 调用
版本历史	完整的变更审计日志，支持回溯

记忆衰减算法：

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

🕸️ 知识图谱引擎

特性	说明
实体管理	创建带类型和观察记录的实体节点
关系追踪	定义实体间的有向关系（如 `uses`, `depends_on`）
双向关系	自动创建反向关系（`A uses B` → `B is_used_by A`）
传递推理	递归查询多跳关系路径（A→B→C→D）
语义搜索	基于向量相似度搜索实体
Mermaid 导出	生成可视化图谱代码

支持的反向关系映射：

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
}

参数	类型	必填	说明
`type`	string	✅	记忆类型：`fact`, `preference`, `conversation`, `task` 等
`content`	object	✅	记忆内容（JSONB 存储，支持任意结构）
`source`	string	✅	来源：`user_message`, `system_inference`, `external_api`
`tags`	string[]	❌	标签数组，用于过滤
`confidence`	number	✅	置信度 0.0-1.0，影响检索权重

`memory_search` - 语义搜索

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

工作原理：

将查询文本转换为 1024 维向量
使用 HNSW 索引计算余弦相似度
按相似度排序返回结果
异步更新访问统计（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
}

参数	说明
`semantic: false`	关键词匹配（名称、类型、观察记录）
`semantic: true`	向量相似度搜索

`graph_open_nodes` - 打开指定实体

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

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

`graph_read` - 读取完整图谱

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

`graph_delete_*` - 删除操作

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

📊 数据库设计

表结构

`memories` - 语义记忆表

列名	类型	说明
`id`	UUID	主键，自动生成
`type`	TEXT	记忆类型
`content`	JSONB	结构化内容
`source`	TEXT	来源标识
`embedding`	vector(1024)	嵌入向量
`tags`	TEXT[]	标签数组
`confidence`	FLOAT	置信度
`access_count`	INT	访问次数
`last_accessed_at`	TIMESTAMPTZ	最后访问时间
`created_at`	TIMESTAMPTZ	创建时间
`updated_at`	TIMESTAMPTZ	更新时间

`entities` - 实体表

列名	类型	说明
`id`	UUID	主键
`name`	TEXT	实体名称（唯一）
`entity_type`	TEXT	实体类型
`observations`	TEXT[]	观察记录数组
`embedding`	vector(1024)	可选，用于语义搜索

`relations` - 关系表

列名	类型	说明
`id`	UUID	主键
`from_entity`	TEXT	源实体（外键）
`to_entity`	TEXT	目标实体（外键）
`relation_type`	TEXT	关系类型

`memory_history` - 历史记录表

列名	类型	说明
`memory_id`	UUID	关联的记忆 ID
`content`	JSONB	变更时的内容快照
`change_type`	TEXT	`create` / `update` / `delete`
`previous_confidence`	FLOAT	变更前置信度
`new_confidence`	FLOAT	变更后置信度

索引策略

索引	类型	用途
`idx_memories_embedding`	HNSW	向量相似度搜索
`idx_memories_tags`	GIN	标签数组包含查询
`idx_memories_type`	B-tree	类型过滤
`idx_entities_embedding`	HNSW (条件)	实体语义搜索
`idx_relations_from/to`	B-tree	关系查询

触发器与函数

名称	类型	说明
`update_memories_updated_at`	Trigger	自动更新 `updated_at`
`memory_history_trigger`	Trigger	自动记录变更历史
`calculate_memory_weight()`	Function	计算记忆衰减权重
`update_memory_access()`	Function	更新访问统计
`log_memory_change()`	Function	记录变更历史

⚙️ 配置参考

环境变量

变量	必填	默认值	说明
`DATABASE_URL`	✅	-	PostgreSQL 连接字符串
`DASHSCOPE_API_KEY`	✅	-	阿里云 DashScope API Key
`DASHSCOPE_API_URL`	❌	`https://dashscope.aliyuncs.com/...`	嵌入 API 端点
`EMBEDDINGS_MODEL`	❌	`text-embedding-v3`	嵌入模型
`EMBEDDINGS_DIMENSIONS`	❌	`1024`	向量维度
`DB_MAX_POOL_SIZE`	❌	`20`	数据库连接池大小
`DB_IDLE_TIMEOUT`	❌	`30000`	空闲连接超时 (ms)
`SEARCH_DEFAULT_LIMIT`	❌	`10`	默认搜索结果数
`MCP_DEBUG_LOG_PATH`	❌	`memory-debug.log`	调试日志路径

示例 `.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

📈 性能优化

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

优化项	效果
嵌入缓存	相同文本重复查询时，API 调用减少 80%+
HNSW 索引	向量搜索从 O(n) 降至 O(log n)
混合检索	召回率提升，避免纯语义搜索的遗漏
批量嵌入	创建多个实体时，单次 API 调用
异步访问统计	不阻塞搜索响应

📜 许可证

本项目采用 MIT License 开源。

🙏 致谢

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

🤝 贡献

欢迎提交 Issue 和 Pull Request！

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
migrations		migrations
src		src
.env.sample		.env.sample
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README_EN.md		README_EN.md
package-lock.json		package-lock.json
package.json		package.json

License

Calvin-Francis/memory-mcp

Folders and files

Latest commit

History

Repository files navigation

Memory MCP

🎯 Why This Project?

✨ 核心特性

🧠 语义记忆系统

🕸️ 知识图谱引擎

🏗️ 系统架构

🚀 快速开始

环境要求

安装步骤

MCP 客户端配置

🛠️ 工具详解

记忆操作 (Memory Tools)

memory_create - 创建记忆

memory_search - 语义搜索

memory_update - 更新记忆

memory_list - 列出记忆

memory_delete - 删除记忆

知识图谱操作 (Graph Tools)

graph_create_entities - 创建实体

graph_create_relations - 创建关系

graph_add_observations - 添加观察

graph_search_nodes - 搜索实体

graph_open_nodes - 打开指定实体

graph_read - 读取完整图谱

graph_delete_* - 删除操作

📊 数据库设计

表结构

memories - 语义记忆表

entities - 实体表

relations - 关系表

memory_history - 历史记录表