# Memory MCP

<div align="center">

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

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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-14%2B-blue)](https://www.postgresql.org/)
[![MCP Protocol](https://img.shields.io/badge/MCP-2024--11--05-purple)](https://modelcontextprotocol.io/)

</div>

---

## 🎯 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 导出** | 生成可视化图谱代码 |

**支持的反向关系映射**：
```javascript
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](https://github.com/pgvector/pgvector) 扩展
- **阿里云 DashScope API Key**（用于生成嵌入向量）

### 安装步骤

```bash
# 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`):
```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`):
```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` - 创建记忆

```json
{
  "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` - 语义搜索

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

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

#### `memory_update` - 更新记忆

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

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

#### `memory_list` - 列出记忆

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

#### `memory_delete` - 删除记忆

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

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

---

### 知识图谱操作 (Graph Tools)

#### `graph_create_entities` - 创建实体

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

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

#### `graph_create_relations` - 创建关系

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

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

#### `graph_add_observations` - 添加观察

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

#### `graph_search_nodes` - 搜索实体

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

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

#### `graph_open_nodes` - 打开指定实体

```json
{
  "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`

```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
```

---

## 🔧 开发指南

```bash
# 开发模式（自动重载）
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](docs/ROADMAP.md)）：

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

---

## 📜 许可证

本项目采用 [MIT License](LICENSE) 开源。

---

## 🙏 致谢

- [pgvector](https://github.com/pgvector/pgvector) - PostgreSQL 向量相似度搜索扩展
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP 协议规范
- [Aliyun DashScope](https://dashscope.aliyun.com/) - 嵌入向量 API 提供商

---

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！