README.md
Persistent semantic memory and knowledge graph capabilities for AI assistants
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"
Tools (2)
memory_searchSearch for relevant memories using hybrid vector and keyword matching.graph_entitiesManage and query knowledge graph entities.Environment Variables
DATABASE_URLrequiredPostgreSQL connection stringDASHSCOPE_API_KEYrequiredAPI key for Aliyun DashScope embedding serviceConfiguration
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"}}}}Try it
→What were the key technical requirements I mentioned for the project last month?
→Create a knowledge graph entry for the new API service and link it to the existing database entity.
→Search my past conversations to find the preferred coding style I discussed for Rust projects.
→Visualize the relationship between the user authentication module and the database schema.