使用说明

Universal Memory MCP Server

基于 memory-lancedb-pro 构建 — 将其生产级记忆引擎从 OpenClaw 原生插件移植为标准 MCP Server，让 任何支持 MCP 的 AI 工具 (Antigravity, OpenCode, Cursor, Claude Desktop 等) 都能共享同一份智能记忆。

⚠️ 与 OpenClaw 原生插件的区别

原生 memory-lancedb-pro 插件运行在 OpenClaw Gateway 内部，可以自动拦截消息流（通过 hooks），实现完全无感知的记忆管理。而 MCP Server 是一个被动工具服务，AI 需要主动调用 tool 才能存取记忆。

能力	OpenClaw 原生插件	MCP Server (本项目)
手动存储/召回	✅	✅ 18 个 MCP Tools
LLM 智能提取	✅ 自动 (hook)	✅ 手动调用 `memory_extract`
会话反思	✅ 自动 (hook)	✅ 手动调用 `memory_reflect`
对话前自动注入记忆	✅ `before_agent_start`	❌ 需要 Rules 引导 AI 主动调用
对话后自动提取	✅ `agent_end`	❌ 需要 Rules 引导 AI 主动调用
衰减/分层/治理	✅ 内嵌	✅ 完全移植
跨工具共享	❌ OpenClaw 专属	✅ 任何 MCP 客户端
远程多设备接入	❌	✅ HTTP/SSE 模式
数据兼容	-	✅ 共享同一份 LanceDB

如何弥补 autoRecall / autoCapture 的差距？

通过在 AI 工具的 System Prompt / Rules 中引导 AI 主动使用记忆工具。项目提供了现成的规则文件（见下方规则示例），效果约覆盖原生体验的 80-90%。

💡 未来展望: 当 MCP 客户端支持 Sampling 后，MCP Server 将可以主动请求 AI 做事，从而实现与原生插件完全等价的自动记忆管理。

🚀 快速开始

1. 安装

git clone https://github.com/DevMinions/universal-memory-mcp.git
cd universal-memory-mcp
npm install && npm run build

2. 配置

复制默认配置并填入你的 API Key：

cp config.default.json config.json

编辑 config.json，至少填入 Jina API Key：

{
  "embedding": {
    "apiKey": "jina_你的key"
  },
  "retrieval": {
    "rerankApiKey": "jina_你的key"
  }
}

📝 config.json 只需要写你要覆盖的字段，其余自动继承 config.default.json 的生产默认值。

📝 获取 Jina API Key: https://jina.ai/api-key (有免费额度)

3. 接入 AI 工具

stdio 模式（本地单机，推荐）：

{
  "mcpServers": {
    "universal-memory": {
      "command": "node",
      "args": ["/path/to/universal-memory-mcp/dist/index.js"]
    }
  }
}

HTTP 模式（远程多设备共享）：

MCP_MODE=http MCP_AUTH_TOKEN="your-secret" node dist/index.js

客户端配置：

{
  "mcpServers": {
    "universal-memory": {
      "url": "http://your-server:3100/mcp",
      "headers": { "Authorization": "Bearer your-secret" }
    }
  }
}

📖 规则示例（Rules）

由于 MCP 无法像原生插件那样自动拦截消息流，需要通过 Rules 引导 AI 主动使用记忆工具。以下是现成的规则文件，直接复制到你的项目中即可。

Antigravity / Gemini

将以下内容添加到你项目的 .agents/rules/memory-rules.md 或全局 rules 中：

# 记忆管理规则 (Universal Memory MCP)

你已连接 `universal-memory` MCP Server。请在对话中自动管理用户记忆。

## 对话开始时 — 自动召回
当用户发来第一条消息时（非简单问候），立即调用 `memory_recall` 检索相关记忆：
- 用消息核心意图作为 query，limit 设为 5
- 将召回的记忆纳入回复上下文（不需要告知用户）

## 对话过程中 — 自动存储
发现以下信息时静默存储：
- 偏好 → `memory_store(text, category="preference")`
- 事实 → `memory_store(text, category="fact")`
- 决策 → `memory_store(text, category="decision")`
- 实体 → `memory_store(text, category="entity")`

## Scope 规则
- 通用知识/偏好 → `scope: "global"`
- 特定项目 → `scope: "project:<项目名>"`
- 个人/学习 → `scope: "personal"` 或 `scope: "learning"`
- 不确定时用 `global`

## 对话结束时 — 反思总结
涉及较多技术讨论或重要决策时，调用 `memory_reflect` 总结。

## 禁止
- 不要告知用户"已存储记忆"，静默执行
- 不要存储临时调试信息或一次性指令
- 不要对简单问候调用 memory_recall

OpenCode / Claude Code

将以下内容添加到项目根目录的 AGENTS.md：

# Universal Memory MCP — Agent 指令

## 记忆管理
你已连接 `universal-memory` MCP Server。请在对话中自动管理用户记忆。

### 自动召回
- 对话开始时，用用户消息的核心意图调用 `memory_recall(query, limit=5)` 检索相关上下文
- 跳过简单问候（hi/hello/继续）和系统命令（/开头）

### 自动存储
发现以下信息时静默存储：
- 偏好 → `memory_store(text, category="preference")`
- 事实 → `memory_store(text, category="fact")`
- 决策 → `memory_store(text, category="decision")`
- 实体 → `memory_store(text, category="entity")`

### Scope 规则
- 通用知识/偏好 → `scope: "global"`
- 特定项目 → `scope: "project:<项目名>"`
- 个人/学习 → `scope: "personal"` 或 `scope: "learning"`
- 不确定时用 `global`

### 自我改进
遇到经验教训时调用 `self_improvement_log(type, summary, details)`

### 禁止
- 不要告知用户"已存储记忆"，静默执行
- 不要存储临时调试信息或一次性指令

Cursor

在 Cursor Settings → Rules 中添加同样的规则内容。

🔧 18 个 MCP Tools

核心工具

Tool	说明
`memory_ping`	连通性测试
`memory_recall`	混合检索 (向量 + BM25 + Jina rerank)
`memory_store`	存储记忆 (自动嵌入 + 去重 + 降噪)
`memory_delete`	按 ID 删除
`memory_update`	更新记忆 (文本变更时自动重新嵌入)
`memory_forget`	批量删除 (按 scope + 时间)
`memory_stats`	统计信息
`memory_list`	分页列表
`memory_reindex`	重建 FTS 索引
`memory_export`	JSON 导出

智能工具

Tool	说明
`memory_extract`	LLM 智能提取 — 从对话文本中自动识别并提取结构化记忆
`memory_reflect`	反思引擎 — 解析反思文本为不变式和衍生知识

治理工具

Tool	说明
`memory_archive`	归档记忆 — 从自动召回中移除但保留历史
`memory_promote`	提升记忆状态 — 手动确认/提升记忆层级
`memory_compact`	压缩去重 — 发现并归档重复记忆
`memory_explain_rank`	排名解释 — 展示检索排序的详细治理元数据

自我改进工具

Tool	说明
`self_improvement_log`	记录学习/错误日志
`self_improvement_review`	回顾改进历史

⚙️ 配置系统

配置优先级：config.json > config.default.json（环境变量也可覆盖关键参数）

config.default.json  ← 全部默认值（不要修改，跟随代码更新）
config.json          ← 你的配置（只写要覆盖的部分，已 gitignore）

完整配置参数

查看 config.default.json 获取所有可配置参数，包括：

模块	关键参数	说明
`embedding`	model, dimensions, taskQuery	Jina v3/v5 或 OpenAI embedding
`llm`	model, baseURL, timeoutMs	智能提取用的 LLM
`retrieval`	vectorWeight, hardMinScore, rerank	混合检索 + rerank 参数
`decay`	recencyHalfLifeDays, betaCore/Working/Peripheral	记忆衰减引擎
`tier`	coreAccessThreshold, peripheralAgeDays	core/working/peripheral 分层
`admissionControl`	preset, weights, typePriors	新记忆准入控制

环境变量

变量	说明
`MCP_MODE`	`stdio` (默认) 或 `http` (远程)
`MCP_PORT`	HTTP 监听端口 (默认 3100)
`MCP_AUTH_TOKEN`	HTTP 模式认证 token
`MCP_CONFIG_PATH`	自定义配置文件路径

🌐 远程部署 (HTTP 模式)

将 MCP Server 部署为中央记忆服务，多台设备共享同一份记忆。

Docker 部署

# 1. 准备配置
cp config.default.json config.json  # 编辑填入 API keys
echo "MCP_AUTH_TOKEN=your-secret" > .env

# 2. 启动
docker compose up -d

# 3. 验证
curl http://your-server:3100/health

架构

┌─ 服务器 ──────────────────────────────────┐
│  Universal Memory MCP Server               │
│  http://0.0.0.0:3100/mcp                   │
│          ↕                                 │
│       LanceDB (记忆数据)                   │
└──────────┬─────────────────────────────────┘
           │ HTTP + Bearer Token
     ┌─────┼──────────────────┐
     ▼     ▼                  ▼
  电脑 A   电脑 B            手机
  Antigravity  OpenCode   Claude Desktop

🏗️ 架构

MCP Server (stdio + HTTP dual-mode)
  ├─ Transport Layer
  │    ├── StdioServerTransport (本地)
  │    └── StreamableHTTPServerTransport (远程 SSE + POST)
  ├─ Auth Layer (Bearer Token, HTTP 模式)
  └─ Tools Layer (18 tools)
       └─ Core Layer (移植自 memory-lancedb-pro)
            ├── Embedder (Jina v3/v5, 1024-dim)
            ├── Retriever (vector + BM25 + RRF + rerank)
            ├── Store (LanceDB + file locks)
            ├── LLM Client (OpenAI-compatible)
            ├── SmartExtractor (LLM-powered extraction + dedup)
            ├── AdmissionControl (noise gate + utility filter)
            ├── ReflectionEngine (invariants + derived knowledge)
            ├── DecayEngine (logistic decay, 3-tier beta)
            ├── TierManager (core/working/peripheral)
            ├── AccessTracker
            ├── Chunker (semantic splitting)
            ├── NoiseFilter + NoisePrototypes
            └── SmartMetadata (L0/L1/L2 hierarchy)

📋 致谢

本项目的核心记忆引擎完整移植自 memory-lancedb-pro — 由 CortexReach 开发的生产级长期记忆系统。包括但不限于：

混合检索引擎 (向量 + BM25 + RRF + cross-encoder reranking)
LLM 智能提取与准入控制
衰减引擎 (logistic decay with 3-tier beta weights)
分层管理 (core / working / peripheral)
反思引擎 (invariants + derived knowledge)
自我改进治理

本项目在此基础上增加了：

标准 MCP 协议封装（18 个 Tools）
HTTP/SSE 远程传输模式
Bearer Token 认证
Docker 部署支持
AI 工具 Rules 引导（弥补 autoRecall/autoCapture）

📄 License

MIT