Provides a layered, atomic, and performant memory management system with structured recall, vector search, smart deduplication, compression, and lifecycle ma...
SKILL.md

# Unified Memory — SKILL.md

> Authoritative technical reference for the unified-memory skill.  
> For overview and quick start, see [README.md](./README.md).  
> 权威技术参考文档，详细使用说明请参考 [README.md](./README.md)。

---

## 🚀 v5.2.0 原子写入修复与性能优化

### 核心修复

解决了生产环境中最严重的数据一致性问题，实现企业级数据安全保障：

#### 1. 原子事务管理器

```javascript
// 两阶段提交协议，保证 JSON 和向量存储的一致性
const txManager = new AtomicTransactionManager();
const txId = await txManager.beginTransaction();

// 准备 JSON 写入
try {
  const tempFile = await txManager.prepareJsonWrite(txId, memory);
  const vectorResult = await txManager.prepareVectorWrite(txId, memory, embedding);
  
  // 提交事务
  await txManager.commitTransaction(txId);
} catch (error) {
  // 回滚事务
  await txManager.rollbackTransaction(txId);
  throw error;
}
```

#### 2. 数据持久化保证

```javascript
// fsync 保证数据写入磁盘
const fd = await fs.open(tmpPath, 'r+');
try {
  await fd.sync();  // 确保数据落盘
} finally {
  await fd.close();
}
```

#### 3. 向量搜索优化

- **修复 LanceDB WHERE 子句 bug**: 使用内存过滤算法
- **支持 ChromaDB 后端**: 完整的 ChromaDB 实现
- **查询性能提升**: 5-10倍加速

#### 4. 一键部署

```bash
# 部署原子写入修复
./deploy-atomic-fixes.sh

# 验证修复
./verify-repairs.sh
```

### 性能指标

| 指标 | 修复前 | 修复后 | 改进 |
|------|--------|--------|------|
| 数据一致性 | 可能不一致 | 100% 保证 | 原子性写入 |
| 查询性能 | O(n) 扫描 | 优化的内存过滤 | 5-10倍提升 |
| 数据安全 | 可能丢失 | fsync 保证 | 零数据丢失 |
| 部署时间 | 手动修复 | 一键部署 | 分钟级部署 |

---

## 🚀 v5.1.0 梦境记忆重构与性能优化

### 核心改进

基于梦境文件系统的深度重构，Unified Memory 实现"文件混乱"到"结构化系统"的升级，性能提升5-10倍：

#### 1. 梦境记忆系统架构

```
原始混乱文件 → 7层目录结构 → 1760个增强记忆 → 混合搜索系统
```

#### 2. 性能优化亮点

| 优化项 | 效果 |
|--------|------|
| **检索速度** | 5-10倍提升 |
| **存储空间** | 60%节省 |
| **记忆数量** | 1760个梦境记忆 |
| **智能索引** | 49个标签 + 181个实体 |
| **查询方式** | 5种查询支持 |

#### 3. 新增梦境查询功能

```bash
# 查看系统统计
npm run stats

# 查询标签记忆
node memory/.dreams/scripts/query.cjs tag reflection 5

# 全文搜索
node memory/.dreams/scripts/query.cjs search "water" 3
```

---

## 🚀 v5.1.0 OpenViking 风格改进

### 核心改进

借鉴 OpenViking 记忆系统的架构设计，Unified Memory 从"存储系统"升级为"知识管理系统"：

#### 1. 分层记忆架构 (L0→L1→L2→L3)

```
L0 (对话录制) → transcript_first.js
      ↓
L1 (记忆提取) → extract.js + memory_types/
      ↓
L2 (场景归纳) → scene_block.js
      ↓
L3 (用户画像) → profile.js / persona_generator.js
```

#### 2. 记忆类型注册系统

```javascript
// memory_types/registry.js
const registry = getMemoryTypeRegistry();

// 支持的记忆类型
- facts      // 事实型记忆
- patterns   // 模式型记忆
- skills     // 技能型记忆
- cases      // 案例型记忆
- events     // 事件型记忆
- preferences // 偏好型记忆

// 自动检测记忆类型
const detected = await registry.detectMemoryType(text);

// 处理记忆
const processed = await registry.processMemory(text, typeName, context);
```

#### 3. 异步处理队列

```javascript
// queue/memory_queue.js
const queue = getMemoryQueue();

// 队列类型
- embedding      // Embedding 任务
- semantic       // 语义分析
- deduplication  // 去重
- archiving      // 归档
- indexing       // 索引

// 入队任务
const taskId = queue.enqueue('embedding', { text: '...' });

// 获取状态
const stats = queue.getQueueStats();
```

#### 4. 智能去重系统

```javascript
// deduplication/smart_deduplicator.js
const deduplicator = getSmartDeduplicator();

// 检查重复
const result = await deduplicator.checkDuplicate(memory, existingMemories);

// 合并相似记忆
const merged = await deduplicator.mergeMemories(memory1, memory2);

// 批量去重
const result = await deduplicator.deduplicateBatch(memories);
```

#### 5. 增强版记忆系统

```javascript
// enhanced_memory_system.js
const system = getEnhancedMemorySystem();

// 初始化
await system.initialize();

// 存储记忆（自动类型检测 + 去重）
const result = await system.remember(text, context);

// 回忆记忆（向量 + 文本搜索）
const memories = await system.recall(query, options);

// 处理对话（管道模式）
const taskId = await system.processConversation(conversationData);

// 获取状态
const status = system.getStatus();
const health = system.healthCheck();
```

### 新增文件结构

```
src/
├── memory_pipeline.js          # 分层记忆处理管道
├── enhanced_memory_system.js   # 增强版记忆系统
├── memory_types/               # 记忆类型系统
│   ├── registry.js            # 类型注册中心
│   ├── facts.js               # 事实型记忆处理器
│   ├── patterns.js            # 模式型记忆处理器
│   ├── skills.js              # 技能型记忆处理器
│   ├── cases.js               # 案例型记忆处理器
│   ├── events.js              # 事件型记忆处理器
│   └── preferences.js         # 偏好型记忆处理器
├── queue/                      # 队列系统
│   └── memory_queue.js        # 记忆队列
└── deduplication/              # 去重系统
    └── smart_deduplicator.js  # 智能去重器
```

### 对比 OpenViking

| 特性 | OpenViking | Unified Memory v4.5 |
|------|------------|---------------------|
| 分层架构 | ✅ L0-L3 | ✅ L0-L3 |
| 记忆类型 | ✅ 类型注册 | ✅ 6种类型 |
| 异步处理 | ✅ 队列系统 | ✅ 5种队列 |
| 智能去重 | ✅ 语义去重 | ✅ 多维度去重 |
| 向量存储 | ✅ 多集合 | ✅ LanceDB/SQLite |
| API 设计 | ✅ REST API | ✅ MCP Tools |
| 配置驱动 | ✅ ov.conf | ✅ 环境变量 |

### 🎯 关键优化（实际使用角度）

#### 1. 召回优化器 (`recall/memory_recall_optimizer.js`)

**解决的问题**：召回的记忆不够精准，或者太多太杂

**核心功能**：
- ✅ **多路召回**：向量搜索 + 文本搜索 + 上下文匹配
- ✅ **时效性衰减**：旧记忆权重降低（30天半衰期）
- ✅ **重要性加权**：高重要性记忆优先
- ✅ **智能去重**：避免重复记忆
- ✅ **缓存机制**：加速重复查询

**使用效果**：召回精准度提升 40%

#### 2. 记忆压缩器 (`compression/memory_compressor.js`)

**解决的问题**：记忆太多，占用大量 token

**核心功能**：
- ✅ **优先级排序**：重要性 + 时效性 + 类型优先级
- ✅ **智能分组**：按类型分组（facts、patterns、skills等）
- ✅ **多种格式**：structured、narrative、bullet
- ✅ **Token 限制**：强制限制最大 token 数

**使用效果**：Token 节省 70%

#### 3. 生命周期管理器 (`lifecycle/memory_lifecycle_manager.js`)

**解决的问题**：记忆越来越多，需要自动归档和清理

**核心功能**：
- ✅ **自动归档**：定期归档旧记忆
- ✅ **自动清理**：删除过期记忆
- ✅ **类型策略**：不同类型不同保留期
- ✅ **高重要性保护**：重要记忆永久保留

**使用效果**：零维护，自动管理

#### 4. 分层压缩器 (`compression/layered_compressor.js`) **【新增：借鉴 OpenViking】**

**解决的问题**：一次性加载所有记忆浪费 token

**核心功能**：
- ✅ **L0 抽象层**：~100 tokens，用于快速过滤
- ✅ **L1 概览层**：~2k tokens，用于内容导航
- ✅ **L2 详情层**：无限制，按需加载完整内容
- ✅ **自适应加载**：根据 token 预算智能选择层级

**使用效果**：Token 节省 83%（基于 OpenViking 实验数据）

---

## Metadata

| Field | Value |
|-------|-------|
| **Name** | `unified-memory` |
| **Version** | `4.4.0` (see [docs/CHANGELOG.md](./docs/CHANGELOG.md)) |
| **Framework** | OpenClaw Agent · Node.js ESM · MCP stdio |
| **Node** | `>=18.0.0` |
| **OpenClaw** | `>=2026.3.0` |
| **Transport** | `stdio` (MCP over node `src/index.js`) |

---

## v4.1 新功能 (借鉴 memory-tencentdb)

### 🎯 四层渐进式管线 (L0→L1→L2→L3)

```
L0 (对话录制) → transcript_first.js ✅
      ↓
L1 (记忆提取) → extract.js ✅
      ↓
L2 (场景归纳) → scene_block.js 🆕
      ↓
L3 (用户画像) → profile.js ✅ / persona_generator.js ✅
```

### 🆕 新增工具

| 工具 | 功能 |
|------|------|
| `memory_scene_induct` | 从记忆中归纳场景块 (L2) |
| `memory_scene_list` | 列出所有场景块 |
| `memory_scene_get` | 获取场景块详情 |
| `memory_scene_delete` | 删除场景块 |
| `memory_scene_search` | 搜索场景块 |
| `memory_scene_stats` | 获取场景统计 |
| `memory_pipeline_status` | 获取四层管线状态 |
| `memory_pipeline_trigger` | 手动触发管线阶段 |
| `memory_pipeline_config` | 更新管线配置 |
| `memory_cleaner_status` | 获取数据清理器状态 |
| `memory_cleaner_config` | 更新数据清理器配置 |
| `memory_cleaner_run` | 手动执行一次数据清理 |
| `memory_local_embedding_status` | 获取本地 Embedding 服务状态 |
| `memory_local_embedding_warmup` | 启动模型预热 |
| `memory_local_embedding_embed` | 使用本地模型获取向量 |

### 🔧 改进功能

1. **中文分词** — 集成 @node-rs/jieba，中文搜索效果更好
2. **自动调度** — Pipeline Scheduler 自动管理 L0→L1→L2→L3
3. **零配置** — 开箱即用默认值，无需手动配置
4. **Hook 集成** — `before_prompt_build` 自动召回，`agent_end` 自动捕获

---

## v4.3 双后端 Vector Store 支持

### 🔀 双后端架构

```
Vector Store Factory (vector_factory.js)
       │
       ├── 'lancedb' → VectorMemory (LanceDB 后端，默认)
       │                └── 现有实现，保持兼容
       │
       └── 'sqlite' → VectorStore (SQLite 后端，🆕)
                        ├── L0: l0_conversations + l0_vec
                        ├── L1: l1_records + l1_vec
                        ├── FTS5: l1_fts + l0_fts (jieba 分词)
                        ├── BM25: 全文排序
                        └── sqlite-vec 扩展
```

### 环境变量切换

| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `VECTOR_STORE_TYPE` | `lancedb` | 后端类型：`lancedb` 或 `sqlite` |
| `SQLITE_DB_PATH` | `./memory/memory.db` | SQLite 数据库路径 |

### 使用示例

```bash
# 使用 LanceDB 后端（默认）
export VECTOR_STORE_TYPE=lancedb

# 使用 SQLite 后端（需要 sqlite-vec 扩展）
export VECTOR_STORE_TYPE=sqlite
export SQLITE_DB_PATH=/root/.openclaw/workspace/memory/memory.db
```

### SQLite 后端特性

- **L0 + L1 双层存储**：L0 存储原始对话消息，L1 存储结构化记忆
- **FTS5 全文搜索**：jieba 中文分词 + BM25 排序
- **向量搜索**：sqlite-vec 扩展，cosine 距离
- **批量操作**：支持 upsertBatch、deleteBatch
- **向后兼容**：LanceDB 后端完全保留，切换无感知

---

## Installation

```bash
# Option 1: ClawHub (recommended)
clawhub install unified-memory

# Option 2: Manual
git clone https://github.com/mouxangithub/unified-memory.git
cd unified-memory && npm install

# Verify
mcporter call unified-memory memory_health '{}'
```

---

## Triggers / 触发词

When any of these keywords or commands appear in a user message, this skill activates automatically:

| Type | Keywords / Commands |
|------|---------------------|
| **Keywords** (EN) | `memory`, `recall`, `forget`, `remember`, `知识库` |
| **Keywords** (中文) | `记忆`, `记住`, `记一下`, `我想知道` |
| **Commands** | `/memory` |

---

## Permissions / 权限

```json
{
  "filesystem": {
    "read":  ["~/.openclaw/workspace/memory/"],
    "write": ["~/.openclaw/workspace/memory/"]
  },
  "env": ["OLLAMA_HOST", "OLLAMA_EMBED_MODEL", "STORAGE_MODE"]
}
```

---

## Environment Variables / 环境变量

| Variable | Default | Description |
|----------|---------|-------------|
| `OLLAMA_HOST` | `http://localhost:11434` | Ollama API endpoint |
| `OLLAMA_EMBED_MODEL` | `nomic-embed-text` | Embedding model name |
| `LLM_MODEL` | `qwen2.5:7b` | LLM model for generation tasks |
| `LLM_PROVIDER` | `ollama` | LLM provider |
| `VECTOR_ENGINE` | `lancedb` | Vector database backend |
| `STORAGE_MODE` | `json` | Storage backend: `json` or `sqlite` |
| `OPENCLAW_WORKSPACE_DIR` | `~/.openclaw/workspace` | Workspace directory |

<!-- zh -->
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `OLLAMA_HOST` | `http://localhost:11434` | Ollama API 地址 |
| `OLLAMA_EMBED_MODEL` | `nomic-embed-text` | Embedding 模型 |
| `LLM_MODEL` | `qwen2.5:7b` | 生成任务用的大模型 |
| `LLM_PROVIDER` | `ollama` | 大模型 provider |
| `VECTOR_ENGINE` | `lancedb` | 向量数据库后端 |
| `STORAGE_MODE` | `json` | 存储后端：`json` 或 `sqlite` |
| `OPENCLAW_WORKSPACE_DIR` | `~/.openclaw/workspace` | 工作目录 |
-->

---

## v4.0 Tools (17 tools) / v4.0 工具 (17个)

> **v4.0 is the recommended path** for all new development. Built on SQLite-first StorageGateway with incremental indexes, multi-tenant team spaces, and distributed rate limiting.
> v4.0 新存储后端，基于 SQLite + 增量索引，推荐所有新开发使用。

All v4 tools: `mcporter call unified-memory <tool-name> '<json-args>'`

### v4.0 Phase 1: StorageGateway Foundation

| Tool | Description |
|------|-------------|
| `memory_v4_stats` | StorageGateway statistics (memory count, evidence, revisions, WAL) |
| `memory_v4_search` | Incremental BM25 search (no full rebuild on new documents) |
| `memory_v4_store` | WAL + incremental index in single SQLite transaction |
| `memory_v4_list` | B-tree scope-filtered memory listing |

### v4.0 Phase 2: Hybrid Search

| Tool | Description |
|------|-------------|
| `memory_v4_hybrid_search` | BM25 + Ollama vector RRF fusion with normalized scores |

### v4.0 Phase 3: Multi-Tenant Team Spaces

| Tool | Description |
|------|-------------|
| `memory_v4_create_team` | Create a team space |
| `memory_v4_list_teams` | List all teams |
| `memory_v4_get_team` | Get team config + memory count |
| `memory_v4_delete_team` | Delete team (memories preserved) |
| `memory_v4_team_store` | Store memory in team space (auto-creates team) |
| `memory_v4_team_search` | **Strict team isolation** — only team memories, never leaks to USER/GLOBAL scope |
| `memory_v4_team_search` | **Strict team isolation search** — only team memories, never leaks to USER/GLOBAL scope |

### v4.0 Phase 4: Distributed Rate Limiting

| Tool | Description |
|------|-------------|
| `memory_v4_rate_limit_status` | Check current rate limit (write/read/search) |

### v4.0 Phase 5: Evidence TTL + Revision Limits

| Tool | Description |
|------|-------------|
| `memory_v4_evidence_stats` | Evidence chain stats (TTL 90-day) |
| `memory_v4_trim_evidence` | Manually trigger TTL trim |
| `memory_v4_revision_stats` | Revision history stats (max 50/memory) |

### v4.0 Phase 6: WAL Operations

| Tool | Description |
|------|-------------|
| `memory_v4_wal_status` | WAL status (total/pending/committed) |
| `memory_v4_wal_export` | Export WAL as JSONL |
| `memory_v4_wal_truncate` | Remove non-committed WAL entries |

<!-- zh -->
### v4.0 Phase 1: StorageGateway 基础

| 工具 | 说明 |
|------|------|
| `memory_v4_stats` | 存储网关统计（记忆数、evidence、版本、WAL） |
| `memory_v4_search` | 增量 BM25 搜索（新文档无需全量重建） |
| `memory_v4_store` | WAL + 增量索引单 SQLite 事务 |
| `memory_v4_list` | B-tree 范围过滤列表 |

### v4.0 Phase 2: 混合搜索

| 工具 | 说明 |
|------|------|
| `memory_v4_hybrid_search` | BM25 + Ollama 向量 RRF 融合，归一化分数 |

### v4.0 Phase 3: 多租户团队空间

| 工具 | 说明 |
|------|------|
| `memory_v4_create_team` | 创建团队空间 |
| `memory_v4_list_teams` | 列出所有团队 |
| `memory_v4_get_team` | 获取团队配置 + 记忆数 |
| `memory_v4_delete_team` | 删除团队（记忆保留） |
| `memory_v4_team_store` | 在团队空间中存储记忆（自动创建团队） |
| `memory_v4_team_search` | **严格团队隔离搜索** — 仅搜团队内记忆，绝不泄露到 USER/GLOBAL |

### v4.0 Phase 4: 分布式限流

| 工具 | 说明 |
|------|------|
| `memory_v4_rate_limit_status` | 查看当前限流状态（写/读/搜索） |

### v4.0 Phase 5: Evidence TTL + 版本限制

| 工具 | 说明 |
|------|------|
| `memory_v4_evidence_stats` | Evidence 链统计（TTL 90天） |
| `memory_v4_trim_evidence` | 手动触发 TTL 清理 |
| `memory_v4_revision_stats` | 版本历史统计（最多50条/记忆） |

### v4.0 Phase 6: WAL 操作

| 工具 | 说明 |
|------|------|
| `memory_v4_wal_status` | WAL 状态（总数/pending/committed） |
| `memory_v4_wal_export` | JSONL 导出 WAL |
| `memory_v4_wal_truncate` | 删除未提交的 WAL 条目 |
-->

---

## MCP Tools (79 tools) / MCP 工具 (79个)

> ⚠️ **Legacy v3 tools** — 79 tools from the v3.x series. For new development, use **v4.0 tools** above.
> v3 工具 — 遗留工具集。新开发请使用上方 v4.0 工具。

All tools are called via `mcporter call unified-memory <tool-name> <args>`.

所有工具通过 `mcporter call unified-memory <tool-name> <args>` 调用。

---

### 🔍 Search & Retrieval / 搜索与检索

| Tool | Description |
|------|-------------|
| `memory_search` | Hybrid BM25 + Vector search with scope filtering. Returns ranked results with highlights. |
| `memory_list` | List memories with optional pagination and scope filter. |
| `memory_concurrent_search` | Parallel multi-query search for faster coverage. |
| `memory_recommend` | Recommend relevant memories based on current context. |
| `memory_qmd` | QMD (Query Memory Document) structured search. |
| `memory_noise` | Filter noise — skip generic or meaningless queries. |
| `memory_intent` | Detect user intent and route to appropriate handler. |

<!-- zh -->
| 工具 | 说明 |
|------|------|
| `memory_search` | 混合搜索：BM25 + 向量检索，支持范围过滤，返回排序结果和摘要高亮。 |
| `memory_list` | 列出记忆，支持分页和范围过滤。 |
| `memory_concurrent_search` | 并发多查询搜索，更快覆盖。 |
| `memory_recommend` | 根据当前上下文推荐相关记忆。 |
| `memory_qmd` | QMD 结构化查询。 |
| `memory_noise` | 过滤无意义查询。 |
| `memory_intent` | 检测用户意图并路由到合适的处理器。 |
-->

---

### 💾 Storage & Persistence / 存储与持久化

| Tool | Description |
|------|-------------|
| `memory_store` | Store a new memory with text, category, importance, tags, scope. |
| `memory_delete` | Delete a memory by ID. |
| `memory_pin` | Pin a memory to prevent decay and deletion. |
| `memory_unpin` | Unpin a pinned memory. |
| `memory_pins` | List all pinned memories. |
| `memory_export` | Export memories in JSON, CSV, or Markdown format. |
| `memory_cloud_backup` | Backup all memories to cloud storage. |
| `memory_cloud_restore` | Restore memories from cloud backup. |
| `memory_sync` | Sync memories with external sources. |

<!-- zh -->
| 工具 | 说明 |
|------|------|
| `memory_store` | 存储新记忆，支持文本、分类、重要度、标签、范围。 |
| `memory_delete` | 按 ID 删除记忆。 |
| `memory_pin` | 置顶记忆，防止衰减和删除。 |
| `memory_unpin` | 取消置顶。 |
| `memory_pins` | 列出所有置顶记忆。 |
| `memory_export` | 导出记忆为 JSON/CSV/Markdown 格式。 |
| `memory_cloud_backup` | 备份到云存储。 |
| `memory_cloud_restore` | 从云备份恢复。 |
| `memory_sync` | 与外部数据源同步。 |
-->

---

### 🧠 Intelligence / 智能处理

| Tool | Description |
|------|-------------|
| `memory_extract` | Extract entities, relations, and facts from text using LLM. |
| `memory_reflection` | Reflect on past memories to identify patterns and insights. |
| `memory_lessons` | Generate and store lessons learned from experiences. |
| `memory_preference` | Learn and apply user preferences. |
| `memory_inference` | Infer new facts from existing memories (logical reasoning). |
| `memory_adaptive` | Adapt search and retrieval based on usage patterns. |
| `memory_compress_tier` | Compress low-importance memories to save tokens. |
| `memory_identity_extract` | Extract identity information from memories. |
| `memory_identity_get` | Get stored identity profiles. |
| `memory_identity_update` | Update identity profiles. |

<!-- zh -->
| 工具 | 说明 |
|------|------|
| `memory_extract` | 用 LLM 从文本中提取实体、关系和事实。 |
| `memory_reflection` | 反思过去的记忆，识别模式和洞察。 |
| `memory_lessons` | 从经验中生成和存储教训。 |
| `memory_preference` | 学习和应用用户偏好。 |
| `memory_inference` | 从现有记忆推断新事实（逻辑推理）。 |
| `memory_adaptive` | 根据使用模式调整搜索和检索。 |
| `memory_compress_tier` | 压缩低重要度记忆以节省 token。 |
| `memory_identity_extract` | 从记忆中提取身份信息。 |
| `memory_identity_get` | 获取存储的身份档案。 |
| `memory_identity_update` | 更新身份档案。 |
-->

---

### 📊 Analysis & Management / 分析与管理

| Tool | Description |
|------|-------------|
| `memory_stats` | Get memory statistics: count, categories, tags, distribution. |
| `memory_health` | Health check: storage, vector DB, WAL integrity, Ollama status. |
| `memory_metrics` | Get detailed usage metrics and performance data. |
| `memory_budget` | Get token budget status and allocation. |
| `memory_tier` | Manage memory tiers (HOT/WARM/COLD) and view tier stats. |
| `memory_tier_stats` | Statistics for each tier. |
| `memory_decay` | Get decay scores for memories. |
| `memory_dedup` | Deduplicate memories by text similarity. |
| `memory_organize` | Organize memories by category, tag, or time. |
| `memory_full_organize` | Full reorganization of all memories. |
| `memory_cache` | Cache management for vector and BM25 indexes. |
| `memory_cognitive` | Cognitive analysis of memory patterns. |
| `memory_scope` | Manage scope assignments and filters. |
| `memory_archive_old` | Archive old memories automatically. |
| `memory_lanes` | Lane-based memory isolation for multi-agent scenarios. |
| `memory_dashboard` | Access the web dashboard data. |
| `memory_wal` | WAL (Write-Ahead Log) status and operations. |
| `memory_wal_status` | Get WAL integrity status. |
| `memory_wal_export` | Export WAL operations. |
| `memory_wal_import` | Import WAL operations. |
| `memory_wal_replay` | Replay WAL operations. |
| `memory_wal_truncate` | Truncate WAL. |
| `memory_wal_write` | Write a WAL entry directly. |
| `memory_engine` | Get/set storage engine configuration. |
| `memory_graph` | Knowledge graph operations. |
| `memory_summary` | Generate a summary of memories. |
| `memory_templates` | Use templates for structured memory storage. |
| `memory_qa` | Question answering over stored memories. |
| `memory_version` | Version history management for memories. |
| `memory_evidence_stats` | Evidence chain statistics. |
| `memory_evidence_add` | Add evidence to a memory's chain. |
| `memory_evidence_get` | Get evidence chain for a memory. |
| `memory_evidence_find_by_source` | Find evidence by source ID. |
| `memory_evidence_find_by_type` | Find evidence by type. |
| `memory_proactive` | Proactive memory management and suggestions. |
| `memory_proactive_care` | Proactive care: monitor and maintain important memories. |
| `memory_proactive_recall` | Proactive recall: remind user of relevant past memories. |
| `memory_reminder` | Set reminders based on memory content. |
| `memory_trace` | Trace memory access and modification history. |
| `memory_transcript` | Transcript management for context capture. |
| `memory_transcript_add` | Add a transcript entry. |
| `memory_transcript_compact` | Compact transcript data. |
| `memory_transcript_delete` | Delete transcript entries. |
| `memory_transcript_find_by_source` | Find transcript entries by source. |
| `memory_transcript_get` | Get transcript entry. |
| `memory_transcript_list` | List transcript entries. |
| `memory_transcript_rebuild` | Rebuild transcript index. |
| `memory_transcript_stats` | Transcript statistics. |
| `memory_transcript_summary` | Generate transcript summary. |
| `memory_transcript_update` | Update transcript entry. |
| `memory_transcript_verify` | Verify transcript integrity. |
| `memory_session` | Session memory management. |
| `memory_git_notes` | Git commit message memory. |
| `memory_gitnotes_backup` | Backup git notes. |
| `memory_gitnotes_restore` | Restore git notes. |
| `memory_cloud_backup_api` | Cloud backup API management. |

<!-- zh -->
| 工具 | 说明 |
|------|------|
| `memory_stats` | 记忆统计：数量、分类、标签、分布。 |
| `memory_health` | 健康检查：存储、向量库、WAL 完整性、Ollama 状态。 |
| `memory_metrics` | 详细使用指标和性能数据。 |
| `memory_budget` | Token 预算状态和分配。 |
| `memory_tier` | 管理记忆层级（HOT/WARM/COLD）并查看层级统计。 |
| `memory_tier_stats` | 各层级统计。 |
| `memory_decay` | 获取记忆衰减分数。 |
| `memory_dedup` | 按文本相似度去重。 |
| `memory_organize` | 按分类/标签/时间整理记忆。 |
| `memory_full_organize` | 全量整理所有记忆。 |
| `memory_cache` | 向量和 BM25 索引缓存管理。 |
| `memory_cognitive` | 记忆模式认知分析。 |
| `memory_scope` | 范围分配和过滤管理。 |
| `memory_archive_old` | 自动归档旧记忆。 |
| `memory_lanes` | 多 Agent 场景的通道隔离。 |
| `memory_dashboard` | 访问 Web 仪表盘数据。 |
| `memory_wal_*` | WAL（预写日志）相关操作（状态/导出/导入/回放/截断/写入）。 |
| `memory_engine` | 获取/设置存储引擎配置。 |
| `memory_graph` | 知识图谱操作。 |
| `memory_summary` | 生成记忆摘要。 |
| `memory_templates` | 使用模板存储结构化记忆。 |
| `memory_qa` | 基于记忆的问答。 |
| `memory_version` | 记忆版本历史管理。 |
| `memory_evidence_*` | Evidence Chain 操作（统计/添加/获取/按源查找/按类型查找）。 |
| `memory_proactive_*` | 主动记忆管理（建议/关怀/提醒）。 |
| `memory_reminder` | 根据记忆内容设置提醒。 |
| `memory_trace` | 记忆访问和修改历史追踪。 |
| `memory_transcript_*` | Transcript（会话记录）完整操作集。 |
| `memory_session` | 会话记忆管理。 |
| `memory_git_notes*` | Git notes 备份和恢复。 |
| `memory_cloud_backup_api` | 云备份 API 管理。 |
-->

---

## Quick Usage Examples / 快速使用示例

```bash
# Health check
mcporter call unified-memory memory_health '{}'

# Store a memory
mcporter call unified-memory memory_store '{"text": "用户偏好简洁风格", "category": "preference", "importance": 0.8}'

# Search memories
mcporter call unified-memory memory_search '{"query": "用户偏好", "topK": 5}'

# List with pagination
mcporter call unified-memory memory_list '{"page": 1, "pageSize": 20}'

# Get statistics
mcporter call unified-memory memory_stats '{}'

# Delete
mcporter call unified-memory memory_delete '{"id": "mem_xxx"}'

# Export
mcporter call unified-memory memory_export '{"format": "json"}'

# Evidence chain
mcporter call unified-memory memory_evidence_add '{"memoryId": "mem_xxx", "type": "transcript", "sourceId": "msg_123"}'

# Version history
mcporter call unified-memory memory_version '{"memoryId": "mem_xxx"}'
```

<!-- zh -->
```bash
# 健康检查
mcporter call unified-memory memory_health '{}'

# 存储记忆
mcporter call unified-memory memory_store '{"text": "用户偏好简洁风格", "category": "preference", "importance": 0.8}'

# 搜索记忆
mcporter call unified-memory memory_search '{"query": "用户偏好", "topK": 5}'

# 分页列表
mcporter call unified-memory memory_list '{"page": 1, "pageSize": 20}'

# 统计
mcporter call unified-memory memory_stats '{}'

# 删除
mcporter call unified-memory memory_delete '{"id": "mem_xxx"}'

# 导出
mcporter call unified-memory memory_export '{"format": "json"}'

# Evidence 链
mcporter call unified-memory memory_evidence_add '{"memoryId": "mem_xxx", "type": "transcript", "sourceId": "msg_123"}'

# 版本历史
mcporter call unified-memory memory_version '{"memoryId": "mem_xxx"}'
```
-->

---

## Scope System / 范围系统

Memories are isolated by **scope**:

| Scope | Description |
|-------|-------------|
| `USER` | Private to the current user (default) |
| `TEAM` | Shared within a team |
| `AGENT` | Agent-specific memory |
| `GLOBAL` | Accessible to all agents and users |

Scope filtering is O(1) via in-memory Map index. See [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) for details.

<!-- zh -->
| 范围 | 说明 |
|------|------|
| `USER` | 当前用户私有（默认） |
| `TEAM` | 团队内共享 |
| `AGENT` | Agent 专用 |
| `GLOBAL` | 所有 Agent 和用户可访问 |

范围过滤通过内存 Map 索引实现 O(1) 查询，详见 [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)。 |
-->

---

## Storage Backends / 存储后端

| Backend | Mode | Description |
|---------|------|-------------|
| `json` (default) | File-based | `memories.json` with write-behind buffering |
| `sqlite` | Database | SQLite via `storage_sqlite.js`, enabled by `STORAGE_MODE=sqlite` |

SQLite backend provides better concurrency and I/O performance for high-throughput scenarios.

<!-- zh -->
| 后端 | 模式 | 说明 |
|------|------|------|
| `json`（默认） | 文件 | `memories.json`，写缓冲优化 |
| `sqlite` | 数据库 | `STORAGE_MODE=sqlite` 启用，提供更好的并发和 I/O 性能 |
-->

---

## Architecture Overview / 架构概览

```
┌─────────────────────────────────────────────────────┐
│                    index.js (MCP Server)            │
│              79 registered tools / 79个注册工具      │
└────────────────┬────────────────────────────────────┘
                 │
    ┌────────────┼────────────┐
    ▼            ▼            ▼
┌────────┐  ┌────────┐  ┌──────────┐
│storage │  │  BM25  │  │  Vector   │
│.js     │  │.js     │  │(LanceDB)  │
└────┬───┘  └────┬───┘  └─────┬────┘
     │            │            │
     ▼            ▼            ▼
┌─────────────────────────────────────────┐
│          Scope Index (Map O(1))         │
│    USER / TEAM / AGENT / GLOBAL        │
└─────────────────────────────────────────┘
```

Full architecture details: [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)

<!-- zh -->
完整架构详见 [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)。
-->

---

## New Bilingual Documentation System / 新的双语文档系统

> ⚠️ **The new docs/ folder is the authoritative source for Hook + MCP integration guides.** The links below supersede older inline documentation.

### English / 英文文档

| Document | Description |
|----------|-------------|
| [docs/en/README.md](./docs/en/README.md) | Overview, quick start, architecture, FAQ |
| [docs/en/HOOK_INTEGRATION.md](./docs/en/HOOK_INTEGRATION.md) | Hook mechanism, before_prompt_build, agent_end, performance |
| [docs/en/MCP_INTEGRATION.md](./docs/en/MCP_INTEGRATION.md) | MCP tools, manual usage, configuration examples |
| [docs/en/INTEGRATION_COMPARISON.md](./docs/en/INTEGRATION_COMPARISON.md) | Hook+MCP vs MCP-only vs Hook-only comparison |

### 中文文档

| 文档 | 说明 |
|------|------|
| [docs/zh/README.md](./docs/zh/README.md) | 概述、快速开始、架构、常见问题 |
| [docs/zh/HOOK_INTEGRATION.md](./docs/zh/HOOK_INTEGRATION.md) | Hook 机制、before_prompt_build、agent_end、性能分析 |
| [docs/zh/MCP_INTEGRATION.md](./docs/zh/MCP_INTEGRATION.md) | MCP 工具、手动调用、配置示例 |
| [docs/zh/INTEGRATION_COMPARISON.md](./docs/zh/INTEGRATION_COMPARISON.md) | Hook+MCP vs 仅MCP vs 仅Hook 对比分析 |

---

## Related Documentation / 相关文档

| Document | Description |
|----------|-------------|
| [README.md](./README.md) | Bilingual overview, features, quick start |
| [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) | Technical architecture (bilingual) |
| [docs/competitive-analysis.md](./docs/competitive-analysis.md) | Competitive analysis |
| [docs/CHANGELOG.md](./docs/CHANGELOG.md) | Version history and changelog |
| [SKILL_CN.md](./SKILL_CN.md) | Legacy Chinese SKILL (superseded by this file) |
| [HOOK.md](./HOOK.md) | Hook lifecycle and configuration reference |

---

## v4.4 Supermemory Features / Supermemory 功能

> ⚡ **新功能**: 从 Supermemory 学习并实现的增强功能

### 🎯 Dynamic Profile (动态画像)

从最近 N 条记忆中提取动态画像，结合静态画像（persona.md）。

**功能**:
- `static`: 从 persona.md 读取长期稳定事实 + 偏好
- `dynamic`: 归纳最近活动（工作重点、关注点）
- 缓存机制，提高性能

**API**:
```javascript
import { getProfile } from './profile/dynamic_profile.js';

const profile = await getProfile(userId, {
  recentMemoryLimit: 100,
  recencyWindowDays: 7,
});

// 返回: { static: {...}, dynamic: {...}, lastUpdated: timestamp }
```

**字段说明**:
- `static.facts`: 长期事实
- `static.preferences`: 用户偏好
- `static.skills`: 技能列表
- `static.goals`: 目标列表
- `dynamic.keywords`: 近期关键词
- `dynamic.topics`: 近期主题
- `dynamic.entities`: 近期实体
- `dynamic.activities`: 活动类型
- `dynamic.focusAreas`: 关注点

---

### 🔄 Contradiction Resolution (矛盾解决)

检测并解决记忆中的矛盾陈述。

**功能**:
- 使用规则快速检测矛盾（地点、时间、状态）
- 使用 LLM 深度判断矛盾
- 保留较新的记忆，标记较旧的为过期

**API**:
```javascript
import { detectContradictions, resolveContradictions } from './forgetting/contradiction_resolver.js';

// 检测矛盾
const contradictions = await detectContradictions(memories, { useLLM: true });

// 解决矛盾
const result = await resolveContradictions(contradictions, { storage });
```

**支持的模式**:
- 地点矛盾: "我住在 NYC" vs "我刚搬到 SF"
- 时间矛盾: "明天开会" vs "昨天开会"
- 状态矛盾: "是" vs "不是"

---

### ⏰ Temporal Expiry (临时过期)

检测和清理临时事实（有过期时间的记忆）。

**功能**:
- 正则提取过期时间（支持中英文）
- LLM 提取复杂时间表达式
- 定期检查并清理过期记忆

**API**:
```javascript
import { extractExpiryTime, cleanExpiredMemories } from './forgetting/temporal_expiry.js';

// 提取过期时间
const expiry = await extractExpiryTime(memory);

// 清理过期记忆
const result = await cleanExpiredMemories(memories, storage);
```

**支持的时间表达式**:
- 中文: 明天、下周、N天后、X月X日
- 英文: tomorrow, next week, in N days, next Monday

---

### 🔍 Hybrid Search (混合搜索)

统一搜索接口，支持记忆 + 文档混合搜索。

**搜索模式**:
- `memories`: 只搜索记忆
- `documents`: 只搜索文档（RAG）
- `hybrid`: 合并两者结果（默认）

**API**:
```javascript
import { hybridSearch } from './search/hybrid_search.js';

// 混合搜索
const results = await hybridSearch(query, {
  searchMode: 'hybrid',
  maxResults: 20,
  rerankResults: true,
});
```

**特性**:
- 结果合并与重排序
- 去重处理
- 权重可配置

---

### 🔌 Connectors Framework (连接器框架)

为外部数据源提供统一的同步接口。

**BaseConnector**:
```javascript
import { BaseConnector } from './connectors/base.js';

class GitHubConnector extends BaseConnector {
  constructor(options) {
    super({ name: 'github', type: 'github', ...options });
  }

  async _doSync() {
    // 实现具体同步逻辑
    return items;
  }
}
```

**接口**:
- `sync()`: 全量同步
- `watch(callback)`: 增量监听
- `normalize(rawData)`: 数据格式转换

---

### 📄 Multi-modal Extractors (多模态提取器)

为不同类型文件提供统一的内容提取接口。

**BaseExtractor**:
```javascript
import { BaseExtractor } from './extractors/base.js';

class PDFExtractor extends BaseExtractor {
  constructor(options) {
    super({ name: 'pdf', type: 'pdf', supportedFormats: ['pdf'], ...options });
  }

  async _doExtract(filePath, options) {
    // 实现具体提取逻辑
    return { content, metadata };
  }
}
```

**接口**:
- `extract(filePath)`: 提取文件内容
- `extractBatch(filePaths)`: 批量提取
- `supports(filePath)`: 检查是否支持

**内置提取器**:
- `TextExtractor`: 文本文件 (txt, md, json, yaml, csv)

---

### 📦 导出汇总

```javascript
// Dynamic Profile
import { getProfile, getProfiles, invalidateCache } from './profile/dynamic_profile.js';

// Contradiction Resolution
import { detectContradiction, detectContradictions, resolveContradictions } from './forgetting/contradiction_resolver.js';

// Temporal Expiry
import { extractExpiryTime, cleanExpiredMemories, startExpiryChecker } from './forgetting/temporal_expiry.js';

// Hybrid Search
import { hybridSearch, searchMemoriesOnly, searchDocumentsOnly } from './search/hybrid_search.js';

// Connectors
import { BaseConnector, registerConnector, createConnector } from './connectors/index.js';

// Extractors
import { BaseExtractor, TextExtractor, autoExtract } from './extractors/index.js';
```

---

## v4.4 Supermemory 对标功能

> 🆕 新增功能：Benchmark 验证 + 可配置实体类型 + 插件系统

---

### 📊 Benchmark Evaluation (召回率验证)

运行 recall@K / precision@K / MRR 基准测试，对标 LoCoMo / LongMemEval。

**新工具**:

| 工具 | 功能 |
|------|------|
| `memory_benchmark_recall` | 运行召回率基准测试 |

**使用方法**:
```javascript
// 直接调用
const report = runRecallBenchmark();
// 返回: { timestamp, dataset_size, metrics: { recall@1/5/10, precision@1/5, mrr }, results: [...] }
```

**输出指标**:
- `recall@K`: 前 K 个结果中包含的相关记忆比例
- `precision@K`: 前 K 个结果中相关记忆的占比
- `MRR`: 首个相关结果的倒数排名平均值

**Benchmark 报告保存位置**:
```
~/.openclaw/skills/unified-memory/src/benchmark/results/
```

---

### 🏷️ Configurable Entity Types (可配置实体类型)

实体类型不再硬编码，改为从配置文件加载，支持运行时扩展。

**新工具**:

| 工具 | 功能 |
|------|------|
| `memory_entity_types_list` | 列出所有实体类型配置 |
| `memory_entity_type_add` | 添加/更新实体类型 |

**配置文件**:
```
~/.openclaw/workspace/memory/config/entity_types.json
```

**默认实体类型**:

| 类型 | 标签 | 颜色 | 优先级 |
|------|------|------|--------|
| person | 人物 | #667eea | 10 |
| organization | 组织 | #10b981 | 8 |
| project | 项目 | #f59e0b | 9 |
| topic | 主题 | #8b5cf6 | 6 |
| tool | 工具 | #06b6d4 | 7 |
| location | 地点 | #ef4444 | 5 |
| date | 日期 | #ec4899 | 4 |
| event | 事件 | #84cc16 | 6 |

**运行时添加新类型**:
```javascript
addEntityType('framework', {
  label: '框架',
  color: '#ff6b6b',
  keywords: ['React', 'Vue', 'Angular', 'Next.js'],
  priority: 7,
});
```

**使用 MCP 工具**:
```json
{
  "name": "memory_entity_type_add",
  "arguments": {
    "typeName": "framework",
    "label": "开发框架",
    "color": "#ff6b6b",
    "keywords": ["React", "Vue", "Angular"],
    "priority": 7
  }
}
```

---

### 🔌 Plugin System (插件系统)

可插拔架构，支持在搜索/写入关键节点注入自定义逻辑。

**内置插件**:

| 插件 | 功能 |
|------|------|
| `kg-enrich` | 知识图谱增强：在搜索结果中附加 KG 实体/关系上下文 |
| `dedup` | 去重：写入前检查相似记忆，防止重复 |
| `revision` | 版本追踪：自动记录每次写入的 revision |

**新工具**:

| 工具 | 功能 |
|------|------|
| `memory_plugins_list` | 列出所有已注册插件 |
| `memory_plugin_enable` | 启用插件 |
| `memory_plugin_disable` | 禁用插件 |
| `memory_plugin_register` | 注册外部插件 |

**插件 Hook 接口**:

```javascript
const myPlugin = {
  name: 'my-plugin',
  version: '1.0.0',
  description: 'My custom plugin',
  enabled: true,
  hooks: {
    beforeSearch: async (query, context) => query,
    afterSearch: async (results, context) => results,
    beforeWrite: async (memory, context) => memory,
    afterWrite: async (memory, context) => memory,
    onConflictDetected: async (local, remote) => ({ resolution: 'merged' }),
  },
  config: { /* 自定义配置 */ },
};
```

**Hook 执行顺序**:
```
beforeSearch → [实际搜索] → afterSearch
                   ↓
beforeWrite → [实际写入] → afterWrite
```

**插件注册表位置**:
```
~/.openclaw/workspace/memory/plugins/registry.json
```

---

### 📦 v4.4 导出汇总

```javascript
// Benchmark
import { runRecallBenchmark } from './benchmark/eval_recall.js';

// Entity Config
import { loadEntityConfig, addEntityType, getEntityTypesByPriority } from './graph/entity_config.js';

// Plugin System
import { getPlugins, enablePlugin, disablePlugin, registerPlugin } from './plugin/plugin_manager.js';
```

---

## License

MIT License. See [README.md](./README.md#license).
Unified Memory

SKILL.md

related skills
