Universal Memory Mcp

Universal Memory MCP

让任何 AI CLI 工具拥有长期记忆，成为你的超级个人助理

简体中文 | [English](./README_EN.md)

[](https://opensource.org/licenses/MIT) [](https://www.npmjs.com/package/universal-memory-mcp) [](https://www.npmjs.com/package/universal-memory-mcp?v=beta)

[功能特性](#-核心特性) • [快速开始](#-快速开始) • [为什么选择](#-为什么选择) • [文档](#-文档)

---

> [!IMPORTANT] > 项目主线已迁移。 > universal-memory-mcp 现在保留为兼容层 / 维护线。新的 runtime-first 主线已经迁移到 > slicenferqin/project-memory-runtime > 如果你关心 V2 架构、contract 文档、lifecycle-first 设计与后续实现，请优先查看新仓库。

✨ 核心特性

• 🌍 通用 - 基于 MCP 协议，支持所有 AI CLI 工具
• 🔄 跨项目 - 统一管理所有项目的记忆和知识
• 🔌 跨 CLI - 支持 Claude Code、OpenCode、Copilot、Gemini CLI 等
• 🤖 超级个人助理 - 让 AI 从工具进化为真正了解你的智能伙伴
• 🔒 超级隐私 - 零数据收集、零遥测，完全加密存储
• 💻 100% 本地私有 - 全部本地运行，无云服务，核心功能无需 API 密钥

🚀 快速开始

安装

npm install -g universal-memory-mcp

配置 Claude Code（自动设置）

安装脚本会自动配置：

• ✅ MCP Server（~/.claude/settings.json）
• ✅ Memory Assistant Skill（引导 AI 使用记忆）
• ✅ Stop Hook（自动记录对话）

重启 Claude Code 即可使用！

配置 OpenCode（自动设置）

npm install -g universal-memory-mcp

安装脚本会自动配置：

• ✅ MCP Server（~/.config/opencode/opencode.json）
• ✅ OpenCode 插件（自动记录对话）
• ✅ 基于 session.idle 事件自动捕获

重启 OpenCode 即可使用！

配置任何 MCP 兼容的 CLI

编辑你的 CLI 配置文件：

{
  "mcpServers": {
    "universal-memory": {
      "command": "npx",
      "args": ["-y", "universal-memory-mcp"]
    }
  }
}

🎯 为什么选择 Universal Memory？

问题：AI 工具缺乏长期记忆

| 方面 | 当前 AI 工具 | 你的需求 | | ---------- | --------------------- | ---------------------- | | 记忆 | ❌ 跨会话无记忆 | ✅ 记住一切 | | 上下文 | ❌ 仅限当前对话 | ✅ 访问所有历史知识 | | 隐私 | ❌ 数据发送到云端 API | ✅ 100% 本地，私有存储 | | 项目 | ❌ 每个项目孤立 | ✅ 跨所有项目统一 | | 所有权 | ❌ 锁定在特定工具 | ✅ 适用于任何 AI CLI |

我们的方案：三层记忆架构

借鉴人类脑科学，我们设计了模拟记忆形成和整合机制的系统：

┌─────────────────────────────────────────────────────────────┐
│  Level 0: 感觉记忆 (daily/*.md)                            │
│  • 捕获原始对话                                            │
│  • 0-7 天生命周期                                          │
│  • 完整但冗余                                              │
└────────────────────┬────────────────────────────────────────┘
                     │ 自动提取（每日）
                     ▼
┌─────────────────────────────────────────────────────────────┐
│  Level 1: 短期记忆 (long_term/*.md)                        │
│  • 提取的事实、决策、偏好                                  │
│  • 7-30 天生命周期                                         │
│  • 结构化、可追溯                                          │
└────────────────────┬────────────────────────────────────────┘
                     │ 整合（每周）
                     ▼
┌─────────────────────────────────────────────────────────────┐
│  Level 2: 长期记忆 (*-summary.md)                          │
│  • 整合的知识库                                            │
│  • 30+ 天生命周期                                          │
│  • 可直接使用，高价值                                      │
└─────────────────────────────────────────────────────────────┘

优势：

• 🧠 自然记忆流程 - 模拟人类记忆整合
• 📈 信息密度递增 - L0（原始）→ L1（事实）→ L2（知识）
• ⚡ 高效检索 - 在 L1/L2 搜索相关事实，而非原始日志
• 💾 智能存储 - 归档旧记忆，保留新记忆

我们的不同之处

| 特性 | Universal Memory | mem0 | 其他方案 | | -------------- | ---------------- | ------------ | -------- | | 架构 | 3 层 (L0/L1/L2) | 2 层（扁平） | 各异 | | 隐私 | 100% 本地 | 云服务/SaaS | 混合 | | 跨 CLI | ✅ 所有 MCP 工具 | ❌ 特定工具 | ❌ 锁定 | | 跨项目 | ✅ 统一管理 | ❌ 孤立 | ❌ 无 | | 数据所有权 | 你拥有 | 他们控制 | 各异 | | 成本 | 免费（本地） | 付费分层 | 各异 | | 开源协议 | MIT License | Apache 2.0 | 各异 |

📖 工作原理

架构

用户 ←→ AI CLI (Claude Code / OpenCode / Gemini / Copilot)
              │
              │ MCP 协议
              ↓
┌───────────────────────────────────────────────────────────┐
│  Universal Memory MCP 服务器                              │
│  ├── memory_search: 搜索历史记忆                          │
│  ├── memory_record: 记录对话                              │
│  └── memory_update_long_term: 存储重要信息                │
└───────────────────────┬───────────────────────────────────┘
                        │
                        ↓
┌───────────────────────────────────────────────────────────┐
│  ~/.universal-memory/                                     │
│  ├── daily/              # Level 0: 感觉记忆              │
│  ├── long_term/          # Level 1-2: 长期记忆            │
│  ├── archive/            # 冷存储（7+ / 30+ 天）          │
│  └── index.db           # 向量索引（SQLite）              │
└───────────────────────────────────────────────────────────┘

记忆生命周期

自动化管理：

1. 捕获 - 每次对话记录到 daily/（Level 0）
2. 提取 - 每日任务提取事实到 long_term/（Level 1）
3. 整合 - 每周任务整合为摘要（Level 2）
4. 归档 - 每月任务移动旧记忆到 archive/
5. 搜索 - 语义 + 关键词搜索，时间衰减 + 项目相关性

全自动化！ 你只需正常使用 AI 工具即可。

🔍 核心功能（v0.6.0-beta.0）

三层记忆架构 ✨

• **Level 0 (daily/\.md)*: 原始对话日志（0-7 天）
• **Level 1 (long_term/\.md)*: 提取的事实、决策、偏好（7-30 天）
• **Level 2 (long_term/\-summary.md)*: 整合的知识库（30+ 天）

智能搜索

• 语义搜索 - 基于向量的相似度搜索 + 时间衰减
• 关键词搜索 - 快速 FTS5 全文搜索
• 混合搜索 - RRF 算法结合两者
• 项目相关性 - 同项目记忆提升 1.5x 权重
• 归档支持 - 可选搜索归档记忆

性能

• ⚡ 搜索延迟：**80%、监控、文档）

🎯 计划中

• v1.0.0: 生产就绪（所有功能稳定、基准测试达标）

时间线：总计 ~3 个月（已完成 6 周，剩余 5 周）

🤝 贡献

欢迎贡献！请查看我们的[贡献指南](./CONTRIBUTING.md)。

高优先级领域：

• 单元测试（覆盖率 >80%）
• 错误重试机制
• 性能优化
• 文档改进
• Bug 修复

📄 开源协议

MIT License - 详见 [LICENSE](./LICENSE)

🙏 致谢

受以下项目启发：

• Clawdbot - 记忆系统设计理念
• Model Context Protocol - MCP 协议
• 脑科学研究 - 记忆整合机制

💡 核心理念

AI 效果 = AI 能力 × 上下文质量 × 记忆深度

AI 能力是固定的，但上下文质量和记忆深度是你可以控制的变量。

Universal Memory MCP 为任何 AI CLI 工具解锁了记忆维度。

---

[⬆ 返回顶部](#universal-memory-mcp)

由 slicenferqin 用 ❤️ 制作

Star ⭐ • Fork 🔱 • Issue 🐛

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: slicenferqin
• Source: slicenferqin/universal-memory-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.