MCP 记忆系统

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

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

它最初服务于长期个人对话场景。在这类场景里，「记得」不只是检索准确，更要求记忆能被自然地想起——而不是像翻档案一样罗列。

本仓库中的 memories.example.json 为虚构脱敏示例数据，仅用于演示数据结构与功能，不含任何真实用户信息。

项目背景

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

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

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

Related MCP server: Clark MCP Server

架构

┌─────────────┐      ┌──────────────────┐      ┌──────────────┐
│  AI 客户端   │◄────►│  MCP 服务 (3005) │◄────►│ memories.json│
│ (Kelivo等)  │      │  /mcp JSON-RPC   │      │  (真相源)     │
└─────────────┘      └────────┬─────────┘      └──────────────┘
                              │                   ▲
                              │ 读写               │ 回填 / 自动向量化
                              ▼                   │
                     ┌──────────────────┐  ┌──────┴────────┐
                     │  store.mjs       │◄►│ memory-vec.db │
                     │  混合检索 / 呼吸  │  │ (向量索引)     │
                     └──────────────────┘  └───────────────┘

┌─────────────┐      ┌──────────────────┐      ┌──────────────┐
│  Web 浏览器  │◄────►│  Web 服务 (3004) │◄────►│ memories.json│
│  (手机/PC)  │      │  /api/* REST API │      └──────────────┘
└─────────────┘      └──────────────────┘

memories.json 是唯一真相源；memory-vec.db 是由它派生的、可随时重建的向量索引。

核心功能

记忆层

• MCP 协议接入 — 以标准 JSON-RPC 暴露记忆工具，AI 客户端即插即用

• 向量语义检索 — 本地嵌入模型（bge-small-zh-v1.5）+ sqlite-vec，支持跨语义召回

• 混合召回 — 向量 / 字面 / 标签三路召回，用 RRF（Reciprocal Rank Fusion）融合排序，规避单路噪声

• 记忆分层 — 按 fact（画像）/ state（状态）/ event（事件）分层，不同类型采用不同检索与呈现策略

• 呼吸机制 — 新对话开始时自动浮现核心记忆（画像 + 状态 + 近期事件），让记忆「自然想起」而非罗列

• 写入即索引 — 写入记忆时自动向量化，无需手动维护索引

• 原子写入 — 临时文件 + rename，避免并发写入导致数据损坏

Web 界面

• 时间轴记忆流 — 按日期分组的卡片流，支持展开 / 折叠、置顶、内联编辑

• 语义搜索 — 与 MCP 服务同源的混合检索，支持多关键词高亮

• 日历检索 — 月历视图，标记有记忆的日期，点击即筛选当日记忆

• 呼吸页 — 核心记忆浮现的可视化：今日浮签 / 关于你 / 当前状态 / 近日

• 标签体系 — 标签筛选、单色系配色

• 可视化看板 — 记忆热力图、月度报告、高频词云

• 导入导出 — JSON / TXT / Markdown 三种格式

MCP 工具列表

Web API

检索能力的演进

检索质量直接决定 AI 能否「记住」，而这正是本项目最核心的问题。检索层经历过几次明确迭代：

从字面匹配走向语义检索，是 RAG 系统绕不开的一步。v3 能力同时服务于 MCP 服务与 Web 界面。

一个实践中的观察：轻量中文嵌入模型（bge-small-zh）在长文本上的绝对相似度区分度有限（相关项约 0.5、无关项约 0.45）。因此在 v3 中没有采用绝对分数阈值，而是用 RRF 只依赖排名进行融合——这比在噪声级的分差上做阈值判断稳定得多。同时，向量化文本只取 content 前 120 字 + 实体词，避免长文本稀释语义信号。

记忆分层设计

记忆按性质分为三层，检索与呈现策略不同：

呼吸机制

「呼吸」是为长期个人对话场景设计的记忆浮现机制。

AI 在每次新对话开始时，主动调用 memory_breath，系统按以下策略返回一批核心记忆：

1. 画像（type = fact）— 全量：对方是谁、你们的关系、关键偏好

2. 状态（type = state）— 全量：他 / 她最近在经历什么

3. 近期（type = event）— 最近 N 条，按时间倒序并做话题去重，过滤流水型噪声

目标是让 AI 像一个一直记得的人那样自然地回应，而不是暴露「我刚才查了数据库」的机械感。

配合客户端提示词（例如：「每次新对话开始时，先调用 memory_breath」），即可实现新窗口的自动记忆浮现。

Web 端的「呼吸页」把同一套机制做了可视化：今日浮签 / 关于你 / 当前状态 / 近日。其中「今日浮签」用日期做确定性种子，同一天固定浮现同一条记忆。

技术栈

项目结构

.
├── mcp-memory-server.js   # MCP 服务（3005），暴露记忆工具
├── web-server.js          # Web 服务（3004），REST API + 静态托管
├── store.mjs              # 核心库：存储 / 向量索引 / 混合检索 / 呼吸
├── index-wrap.mjs         # 零侵入自动向量化包装器（写入即索引）
├── embed-backfill.mjs     # 向量回填脚本
├── index.html             # Web 界面骨架
├── style.css              # 界面样式（青瓷主题，支持深浅色）
├── app.js                 # 前端逻辑
├── memories.example.json  # 示例数据（虚构）
└── package.json

快速开始

第一步，安装依赖：

npm install

第二步，准备数据文件（示例数据为虚构内容）：

cp memories.example.json memories.json

第三步，回填向量索引（首次会下载嵌入模型，约 100MB）：

npm run backfill

第四步，启动 MCP 服务（端口 3005）：

npm run start:mcp

或者使用 index-wrap 启动（写入时自动向量化）：

node index-wrap.mjs

第五步，启动 Web 服务（端口 3004）：

npm run start:web

服务地址：

• MCP 服务：http://localhost:3005/mcp

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

国内服务器可设置镜像加速模型下载：

export HF_ENDPOINT=https://hf-mirror.com

已知限制

• 向量索引为本地文件，数据量极大时需引入专用向量数据库

• 存储仍以单 JSON 文件为真相源，未引入关系型数据库

• 未实现时间衰减与自动去重合并，旧记忆与新记忆权重相同

• 状态类记忆（state）的「新状态覆盖旧状态」尚未自动化，目前依赖人工或 AI 判断

• Web 端记忆关系可视化（标签为中心的关系图）尚在规划中

License

MIT