Which integrations are available for this server?

Enables the generation of Mermaid diagram code to visualize knowledge graph entities and their relationships. Integrates with PostgreSQL and the pgvector extension to provide persistent storage and semantic search capabilities for AI memory.

How do I use Memory MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Memory MCP What did I mention in previous chats about my favorite programming languages?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Memory MCP

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

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

License: MIT Node.js Version PostgreSQL MCP Protocol

🎯 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！

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_* - 删除操作