# memory-mcp

**Repository Path**: SeniorAgentTeam/memory-mcp

## Basic Information

- **Project Name**: memory-mcp
- **Description**: 基于关键词和向量实现长期记忆的MCP。
n8n工作流演示
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2025-11-16
- **Last Updated**: 2025-11-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP (Model Control Protocol) 记忆与再学习系统

一个为大语言模型设计的记忆存储和再学习能力增强系统，基于MCP协议实现，支持与n8n集成。

## 功能特性

- **记忆存储**: 支持存储不同类型和重要性的记忆
- **RAG语义检索**: 基于向量相似度的智能搜索，理解查询语义
- **混合搜索**: 结合关键词和语义搜索，获得最佳结果
- **记忆关联**: 建立记忆之间的关联关系
- **学习管理**: 记录和分析学习会话
- **自适应学习**: 根据表现调整学习策略
- **RESTful API**: 提供完整的HTTP接口
- **MCP协议支持**: 支持JSON-RPC和SSE流式传输，与n8n完美集成

## 技术栈

- Node.js + Express
- PostgreSQL + pgvector（向量数据库）
- OpenAI Embeddings（文本向量化）
- RESTful API 设计
- MCP 协议 (JSON-RPC 2.0)
- Server-Sent Events (SSE)

## 安装与启动

### 本地部署

```bash
# 克隆项目
git clone <repository-url>
cd memory-qoder

# 安装依赖
npm install

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，设置 EMBEDDING_PROVIDER 和相应的API密钥
# 可选提供商: openai (默认), siliconflow, 或 custom

# 启动服务
npm start

# 或者开发模式启动
npm run dev
```

### Docker部署

```bash
# 设置环境变量（根据使用的提供商选择其一）
export OPENAI_API_KEY="your-openai-api-key-here"
# 或者
export SILICONFLOW_API_KEY="your-siliconflow-api-key-here"
# 或者通用配置
export EMBEDDING_PROVIDER="custom"
export EMBEDDING_API_KEY="your-api-key-here"
export EMBEDDING_BASE_URL="https://api.example.com/v1"
export EMBEDDING_MODEL="your-embedding-model"

# 使用Docker Compose启动服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 停止服务
docker-compose down
```

服务默认运行在 `http://localhost:3000`

## 与n8n集成

### 1. 在n8n中配置MCP Client节点

#### 基本配置
- **Endpoint**: `http://host.docker.internal:3000/mcp/stream`
- **Server Transport**: `HTTP Streamable`
- **Authentication**: `None`
- **Tools to Include**: 选择`Selected`，勾选需要的工具

#### 可用工具
- `store_memory` - 存储记忆
- `retrieve_memories` - 检索记忆（关键词匹配）
- `vector_search` - RAG语义搜索（理解语义）
- `hybrid_search` - 混合搜索（关键词+语义）
- `get_memory` - 获取特定记忆
- `link_memories` - 关联记忆
- `search_similar` - 相似记忆搜索
- `record_learning` - 记录学习会话
- `get_analytics` - 获取学习分析
- `get_recommendations` - 获取学习建议

### 2. AI Agent节点配置

#### System Message示例：
```
你是一个具有长期记忆能力的AI助手。你**必须**使用MCP工具来存储和检索信息。

重要规则：
1. 当用户分享个人信息时，**立即调用store_memory工具**存储
2. 回答问题前，**必须先调用retrieve_memories工具**检索
3. 不要只是口头说"已记住"，必须真实调用工具

## 存储记忆规则

遇到以下情况立即调用store_memory：
- 用户说"我叫XXX" → 存储"用户姓名：XXX"
- 用户说职业/爱好 → 存储"用户职业：XXX"或"用户爱好：XXX"

参数设置：
- content: 格式化描述，如"用户姓名：硅基流码"
- type: "personal"（个人信息）
- importance: 0.9（重要身份信息）

## 检索记忆规则

用户询问"我是谁"、"你还记得我吗"等问题时：
1. 调用retrieve_memories(query="用户 姓名 职业", type="personal", limit=10)
2. 根据检索结果组合回答
```

### 3. 使用示例

**场景1：存储用户信息**
```
用户：我叫硅基流码，是一个AI领域的短视频博主
AI：[调用store_memory]
    - content: "用户姓名：硅基流码", type: "personal", importance: 0.9
    - content: "用户职业：AI领域的短视频博主", type: "personal", importance: 0.9
AI回复：好的，我已记住：您是硅基流码，一位AI领域的短视频博主。
```

**场景2：检索用户信息**
```
用户：我是谁？
AI：[调用retrieve_memories]
    - query: "用户 姓名 职业", type: "personal", limit: 10
AI回复：您是硅基流码，AI领域的短视频博主。
```

### 4. 故障排查

如果AI没有调用工具：
1. 检查System Message是否明确要求"必须调用工具"
2. 确认使用支持Function Calling的模型（如GPT-4）
3. 查看日志：`docker-compose logs -f mcp-server`

## API 接口文档

### MCP协议端点

#### 初始化
```
POST /mcp/stream
Body: {"jsonrpc":"2.0", "method":"initialize", "params":{...}, "id":0}
```

#### 获取工具列表
```
POST /mcp/stream
Body: {"jsonrpc":"2.0", "method":"tools/list", "params":{}, "id":1}
```

#### 调用工具
```
POST /mcp/stream
Body: {"jsonrpc":"2.0", "method":"tools/call", "params":{"name":"store_memory", "arguments":{...}}, "id":2}
```

### 记忆管理

#### 存储记忆
```
POST /mcp/memory/store
```
请求体:
```json
{
  "content": "记忆内容",
  "type": "记忆类型",
  "importance": 0.8,
  "metadata": {}
}
```

#### 检索记忆
```
GET /mcp/memory/retrieve?query=关键词&type=类型&limit=数量
```

#### 获取记忆详情
```
GET /mcp/memory/{id}
```

#### 更新记忆重要性
```
PUT /mcp/memory/importance/{id}
```
请求体:
```json
{
  "importance": 0.9
}
```

#### 删除记忆
```
DELETE /mcp/memory/{id}
```

#### 建立记忆关联
```
POST /mcp/memory/link
```
请求体:
```json
{
  "from_memory_id": "来源记忆ID",
  "to_memory_id": "目标记忆ID",
  "relation_type": "关联类型",
  "strength": 0.8
}
```

#### 获取记忆关联
```
GET /mcp/memory/links/{memory_id}
```

### 学习管理

#### 记录学习会话
```
POST /mcp/learning/session
```

#### 获取学习会话
```
GET /mcp/learning/sessions
```

#### 学习分析
```
GET /mcp/learning/analytics
```

#### 学习建议
```
GET /mcp/learning/recommendations
```

#### 自适应学习调整
```
POST /mcp/learning/adaptive
```

## 使用示例

运行示例客户端:
```bash
npm run example
```

或者查看 [examples/clientExample.js](examples/clientExample.js) 文件了解如何使用。

## RAG (检索增强生成) 功能

### 功能概述

本系统现在支持真正的RAG功能，通过向量相似度搜索实现语义理解：

1. **向量搜索** (`vector_search`): 理解查询语义，即使关键词不同也能找到相关内容
2. **混合搜索** (`hybrid_search`): 结合关键词匹配和语义搜索，获得最佳结果
3. **智能嵌入**: 使用OpenAI Embeddings或兼容的Embeddings将文本转换为向量

### Embedding提供商配置

系统支持多种Embedding提供商：

#### OpenAI (默认)
- 模型: `text-embedding-3-small`
- 维度: 1536
- 配置:
  ```env
  EMBEDDING_PROVIDER=openai
  OPENAI_API_KEY=your-api-key
  OPENAI_EMBEDDING_MODEL=text-embedding-3-small
  ```

#### 硅基流动 (SiliconFlow)
- 模型: `BAAI/bge-large-zh-v1.5` (中文优化)
- 维度: 1024
- 配置:
  ```env
  EMBEDDING_PROVIDER=siliconflow
  SILICONFLOW_API_KEY=your-api-key
  SILICONFLOW_EMBEDDING_MODEL=BAAI/bge-large-zh-v1.5
  ```

#### 通用自定义配置
适用于任何兼容OpenAI的Embedding服务：
- 配置:
  ```env
  EMBEDDING_PROVIDER=custom
  EMBEDDING_API_KEY=your-api-key
  EMBEDDING_BASE_URL=https://api.example.com/v1
  EMBEDDING_MODEL=your-embedding-model
  EMBEDDING_DIMENSION=1536
  ```

### 工作原理

```
[用户查询] → [文本向量化] → [向量数据库搜索] → [相似度计算] → [结果排序]
```

### 优势对比

| 搜索方式 | 原理 | 优点 | 缺点 |
|---------|------|------|------|
| 关键词搜索 | 匹配特定词语 | 快速、精确 | 无法理解语义 |
| 向量搜索 | 语义相似度 | 理解含义、泛化能力强 | 计算复杂 |
| 混合搜索 | 两者结合 | 最佳平衡 | 需要调参 |

### 使用示例

**场景1：语义理解**
```javascript
// 用户问："这个人是做什么的？"
// 系统能找到："用户职业：AI领域的短视频博主"

const result = await mcpRequest('tools/call', {
  name: 'vector_search',
  arguments: {
    query: '这个人是做什么的？',
    limit: 5,
    threshold: 0.6
  }
});
```

**场景2：概念搜索**
```javascript
// 用户问："什么是检索增强生成？"
// 系统能找到："RAG (Retrieval-Augmented Generation) 是一种结合检索和生成的技术"

const result = await mcpRequest('tools/call', {
  name: 'vector_search',
  arguments: {
    query: '什么是检索增强生成？',
    limit: 3,
    threshold: 0.7
  }
});
```

### 配置说明

在 `.env` 文件中配置：

```env
# 通用自定义配置示例
EMBEDDING_PROVIDER=custom
EMBEDDING_API_KEY=your-api-key-here
EMBEDDING_BASE_URL=https://api.example.com/v1
EMBEDDING_MODEL=your-embedding-model
EMBEDDING_DIMENSION=1536
```

### API端点

#### 向量搜索
```bash
GET /mcp/memory/search/vector?query=查询内容&limit=10&threshold=0.7&type=类型
```

#### 混合搜索
```bash
GET /mcp/memory/search/hybrid?query=查询内容&limit=10&vectorWeight=0.7&keywordWeight=0.3
```

### n8n集成

在n8n的MCP Client节点中，可以使用以下新工具：

- `vector_search`: 语义搜索工具
- `hybrid_search`: 混合搜索工具

配置与原有工具相同，只需在工具参数中设置合适的阈值和权重。

### memories 表
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | TEXT | 记忆唯一标识 |
| content | TEXT | 记忆内容 |
| type | TEXT | 记忆类型 |
| created_at | TIMESTAMP | 创建时间 |
| accessed_at | TIMESTAMP | 最后访问时间 |
| importance | REAL | 重要性 (0-1) |
| metadata | TEXT | 元数据 (JSON) |
| embedding | vector(1536) | 向量表示（RAG） |

### memory_relations 表
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | TEXT | 关联唯一标识 |
| from_memory_id | TEXT | 来源记忆ID |
| to_memory_id | TEXT | 目标记忆ID |
| relation_type | TEXT | 关联类型 |
| strength | REAL | 关联强度 (0-1) |
| created_at | TIMESTAMP | 创建时间 |

### learning_sessions 表
| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | TEXT | 会话唯一标识 |
| session_data | TEXT | 会话数据 (JSON) |
| performance_metrics | TEXT | 性能指标 (JSON) |
| created_at | TIMESTAMP | 创建时间 |

## 架构设计

```
┌─────────────────┐
│   MCP Client    │
└─────────────────┘
         │
         ▼
┌─────────────────┐
│   MCP Server    │
│  (Express App)  │
└─────────────────┘
         │
         ▼
┌─────────────────┐
│  MemoryManager  │◄──►│  LearningManager  │
└─────────────────┘    └───────────────────┘
         │
         ▼
┌─────────────────┐
│  DatabaseManager│
│  (PostgreSQL)   │
└─────────────────┘
```

## 开发指南

### 项目结构
```
├── index.js          # 应用入口
├── package.json      # 项目配置
├── Dockerfile        # Docker配置
├── docker-compose.yml # Docker Compose配置
├── src/
│   ├── app.js        # 主应用类
│   ├── database.js   # 数据库管理
│   ├── memoryManager.js  # 记忆管理
│   └── learningManager.js # 学习管理
├── examples/
│   └── clientExample.js  # 客户端示例
└── test/
    └── mcp.test.js   # 测试文件
```

### 添加新功能

1. 在相应的管理器中添加方法
2. 在app.js中注册路由
3. 更新README文档

## 测试

### 运行单元测试
```bash
npm test
```

### 运行场景测试
测试存储和检索功能：
```bash
node test-scenario.js
```

### 运行RAG测试
测试语义搜索功能：
```bash
node test-rag.js
```

### 运行Embedding测试
测试通用Embedding功能：
```bash
npm run test-embedding
```

### 运行调试工具
全面测试MCP服务：
```bash
node debug-mcp.js
```

### 实时监控日志
```bash
docker-compose logs -f mcp-server
```

## 许可证

MIT