# MCP 记忆系统

> 基于 Model Context Protocol 的个人 AI 长期记忆服务

与 AI 助手长期对话时，上下文窗口会溢出，跨会话的记忆会丢失——这是深度用户的核心痛点。本项目通过 MCP 协议，为 AI 客户端提供一个可读可写的结构化长期记忆库，让对话内容能够沉淀、检索、回溯。

---

## 项目背景

现有的 AI 对话产品普遍存在一个问题：**每次新开对话，AI 就"忘了"之前聊过什么**。

常见的做法是把历史对话全部塞进上下文，但这会迅速耗尽 token 预算。更合理的方案是：**把记忆外置，由 AI 在需要时主动检索**。

本项目实现的就是这个"外置记忆层"。

---

## 架构

```
┌─────────────┐      ┌──────────────────┐      ┌─────────────┐
│  AI 客户端   │◄────►│  MCP 服务 (3005) │◄────►│             │
│ (Kelivo等)  │      │  /mcp JSON-RPC   │      │  memories   │
└─────────────┘      └──────────────────┘      │    .json    │
                                               │             │
┌─────────────┐      ┌──────────────────┐      │             │
│  Web 浏览器  │◄────►│  Web 服务 (3004) │◄────►│             │
│  (手机/PC)  │      │  /api/* REST API │      └─────────────┘
└─────────────┘      └──────────────────┘
```

两个服务共享同一份 `memories.json`，分别面向 AI 客户端与人类用户。

---

## 核心功能

- **MCP 协议接入** — 以标准 JSON-RPC 暴露 9 个记忆工具，AI 客户端即插即用
- **多关键词检索** — 空格分隔多个关键词，按命中比例加权打分，并按时间倒序排列
- **标签系统** — 支持打标签、按标签精确检索
- **结果截断** — 检索结果限制条数与单条长度，避免撑爆上下文窗口
- **原子写入** — 临时文件 + rename，避免并发写入导致数据损坏
- **可视化** — 记忆热力图、月度报告、高频词云

## MCP 工具列表

| 工具 | 说明 |
|---|---|
| `memory_create` | 创建记忆 |
| `memory_search` | 多关键词检索，支持 limit / snippet 参数 |
| `memory_search_by_tag` | 按标签检索 |
| `memory_recent` | 按时间倒序获取最近记忆 |
| `memory_list` | 列出记忆 |
| `memory_update` | 更新记忆 |
| `memory_delete` | 按 ID 删除 |
| `memory_search_delete` | 按关键词搜索并删除 |
| `memory_clear` | 清空全部记忆 |

---

## 检索能力的演进

这个项目的检索层经历过一次明确的迭代，后续仍会继续演进：

| 版本 | 方案 | 能力边界 |
|---|---|---|
| v1 | 单一字符串包含匹配 | 多关键词无法查询；命中结果全量返回 |
| **v2（当前）** | 多关键词加权打分 + 相关度排序 + top-k 截断 | 仍是字面匹配，无法处理语义近似（如「受伤」无法命中「摔了一跤」） |
| v3（规划） | 向量语义检索 + BM25 混合召回 + RRF 融合 | — |

**为什么记录这个演进过程**：检索质量直接决定 AI 能否"记住"，而这正是本项目最核心的问题。从字面匹配走向语义检索，是 RAG 系统绕不开的一步。

---

## 技术栈

| 层级 | 技术 |
|---|---|
| 运行时 | Node.js |
| 后端 | Express |
| 协议 | MCP (Model Context Protocol) |
| 存储 | JSON 文件 |
| 前端 | 原生 HTML / CSS / JavaScript |
| 部署 | Linux 云服务器 + pm2 |

---

## 快速开始

```bash
# 1. 安装依赖
npm install

# 2. 准备数据文件（示例数据为虚构内容）
cp memories.example.json memories.json

# 3. 启动 MCP 服务（端口 3005）
node mcp-memory-server.js

# 4. 启动 Web 服务（端口 3004）
node web-server.js
```

MCP 服务地址：`http://localhost:3005/mcp`

Web 界面：`http://localhost:3004`

---

## 已知限制

- 检索当前为字面匹配，尚未实现向量语义检索
- 存储为单 JSON 文件，数据量大时检索性能会下降，未引入数据库
- 记忆未做分层（事实 / 事件 / 状态），不同类型记忆的检索策略尚未区分
- Web 服务（3004）的检索逻辑仍是 v1 方案，尚未与 MCP 服务同步

---

## License

MIT