🧠 memory-mcp
给 AI 助手的「跨会话持久记忆」—— 轻量、本地、零依赖的 MCP 服务端
让 opencode / Claude / Cursor 等任何 MCP 客户端,在会话之间记住用户偏好、决策与项目上下文。
✨ 为什么需要它
AI 对话是无状态的——每次新会话,AI 都会忘掉你之前交代过的偏好、约定与上下文,你只能一遍遍重复。
memory-mcp 用一个本地 SQLite 数据库 + MCP 标准协议,给 AI 装上「长期记忆」:
- ✅ 本地自托管 —— 数据留在你自己的磁盘,不经过任何云端
- ✅ 零外部依赖 —— 一个 jar + 一个 db 文件,即插即用
- ✅ 标准协议 —— 任意 MCP 客户端(opencode、Claude、Cursor…)开箱即用
- ✅ 中文友好 —— 全文检索内置 FTS5(trigram),中文子串直接命中
- ✅ 永不丢失 —— 定时在线一致性备份,崩溃也不慌
- ✅ 会遗忘 —— 记忆可设 TTL 自动过期,临时信息不再永久堆积
🚀 快速开始
1. 获取 jar
直接下载(推荐): 从 Releases 下载 memory-mcp.jar,跳过构建。
或自行构建 —— 需要 Java 17+ 与 Maven 3.6+:
git clone https://github.com/nouscow/memory-mcp.git
cd memory-mcp
mvn clean package
产物: target/memory-mcp.jar —— 一个可直接 java -jar 运行的 fat jar。
2. 运行
java -jar target/memory-mcp.jar # 使用默认库 ~/.memory-mcp/memory.db
MEMORY_MCP_DB="D:/my-memory.db" java -jar target/memory-mcp.jar # 指定库路径
3. 接入 MCP 客户端
opencode(opencode.json 或 .opencode/ 下):
{
"mcp": {
"memory-mcp": {
"type": "local",
"command": ["java", "-jar", "$JAR_PATH"] // 替换为 memory-mcp.jar 的实际路径
}
}
}
Claude / Cursor 等: 只需把上面的 command 配置到对应的 MCP 服务器设置中即可。
改完配置后重启客户端才生效。
🧩 9 个 MCP 工具
💡 使用示例
remember { key: "name", content: "用户叫张三", tags: ["identity"] }
→ 已保存记忆 [default:name]
remember { namespace: "project", key: "style", content: "代码注释用中文" }
remember { key: "hotfix", content: "临时补丁说明", ttl: 7 }
→ 7 天后自动失效(到期不可见并被定时清理)
search { query: "注释" }
→ 找到 1 条匹配: [project:style] 代码注释用中文
recall { key: "name" }
→ namespace: default | key: name | content: 用户叫张三
summarize
→ 共 2 条记忆, 2 个命名空间
→ [default] 1 条
→ - name: 用户叫张三
→ [project] 1 条
→ - style: 代码注释用中文
export → {"version":1,"exportedAt":"...","entries":[...]}
import { json: '{"entries":[{...}]}' } → 成功导入 N 条记忆
stats
→ 记忆条目数: 2, 命名空间数: 2, 数据库大小: 32.0 KB, 已过期待清理: 0
⚙️ 配置一览
数据安全
- 校验上限: content 8192 字符 / key 256 字符 / tags ≤20 个且每个 ≤64 字符 / ttl ≤ 36500 天
- 在线一致性备份: 内置调度,运行中备份不破坏数据(默认每 24h)
- 手动备份:
powershell -ExecutionPolicy Bypass -File scripts/backup.ps1 - 恢复: 停服务 → 用备份文件覆盖 → 重启(自动重建索引)
- 逻辑备份/迁移: 用
export导出 JSON,在目标机器import恢复,可跨机器搬运
🏗️ 工作原理
┌──────────────┐ tools/call (JSON-RPC over stdio) ┌──────────────────┐
│ MCP 客户端 │ ───────────────────────────────────► │ memory-mcp │
│ opencode/... │ ◄─────────────────────────────────── │ (Java 17,jar) │
└──────────────┘ 结果 / isError └────────┬─────────┘
│ SQLite
┌───────▼─────────┐
│ memory.db │
│ + FTS5 全文索引 │
└─────────────────┘
技术栈: Java 17 · MCP Java SDK 2.0 · SQLite(sqlite-jdbc,内置 FTS5) · SLF4J + Logback(日志走 stderr,不污染协议流)
分层结构:
src/main/java/org/example/memory/
├── MemoryMcpServer.java # 入口: stdio 传输 + 注册 9 工具 + 启动备份/过期清理调度
├── config/AppConfig.java # 配置解析(库路径 / 备份参数)
├── model/MemoryEntry.java # 数据模型(record,含 expiresAt)
├── repository/MemoryRepository.java# SQLite CRUD + FTS5 索引同步 + 在线备份 + 过期清理
└── service/
├── MemoryService.java # 业务规则 + 输入校验 + summarize/export/import
├── BackupService.java # 定时自动备份调度
└── ExpiryService.java # 过期记忆定时清理调度
📚 文档
🧪 测试
mvn test # 40 个测试(含 stdio 中文 export 回归)
# 端到端冒烟(真实子进程 + 真实 stdio 协议,使用临时库):
# 注意: Java 17 + 中文 Windows 必须给 JVM 指定 UTF-8,否则 GBK 会误读服务端输出致 export 超时:
$env:MEMORY_MCP_DB = "$env:TEMP\memory-mcp-e2e.db"
$env:MAVEN_OPTS = "-Dfile.encoding=UTF-8"
mvn -q test-compile exec:java "-Dexec.mainClass=org.example.memory.IntegrationSmokeClient" "-Dexec.classpathScope=test"
若在 Java 17 + 中文 Windows 下手动跑 Java 版 MCP 客户端,请同样给 JVM 加
-Dfile.encoding=UTF-8(mcp-core 客户端按 JVM 默认字符集读取服务端 UTF-8 输出)。
🗺️ 路线图
- 6 个核心 MCP 工具 + SQLite 持久化
- FTS5 全文检索(中文子串)
- 定时自动备份
- 记忆过期(TTL)+ 自动清理
- summarize 会话摘要
- JSON 导入导出备份
- 自动沉淀记忆(会话结束自动提炼关键信息写入,无需主动 remember)
- 万级数据搜索性能基准
- 语义/向量检索(embedding)评估
如果这个项目帮到了你,欢迎 ⭐ Star 支持一下,也欢迎提 Issue 或 PR 一起完善。