Unified Memory V5

Provides a layered memory management system with atomic transactions, smart deduplication, vector search optimization, and lifecycle management for consisten...

Security Scan

The package mostly matches a memory-management tool, but documentation/code claim no required environment or install steps while actually referencing config paths, env vars, lifecycle hooks and prompt-modifying hooks — and the SKILL.md contains prompt-injection patterns — so the bundle is internally inconsistent and warrants caution.

Purpose & Capability

Name/description match the included code and docs (memory management, vector search, WAL/atomic writes). However metadata declares 'no required env vars/config paths' while READMEs/merged-docs/SKILL.md and source reference many config paths (~/.unified-memory, ~/.openclaw/workspace) and environment variables (OLLAMA_URL, UNIFIED_MEMORY_*, etc.). The skill was labeled 'instruction-only' with no install spec but includes a large merged-src.js, package.json and scripts — this mismatch between claims and actual artifacts is incoherent.

Instruction Scope

SKILL.md and merged-docs give operational instructions (run deploy/verify scripts, node scripts, CLI commands) and reference filesystem locations in the user's home. The SKILL.md also contains detected prompt-injection patterns (e.g., 'ignore-previous-instructions', 'system-prompt-override'), and package.json defines OpenClaw hooks (before_prompt_build, agent_end) that let the skill run during prompt construction — giving it the ability to influence agent prompts. These behaviors exceed a simple data-store helper and grant the skill broad discretion over agent runtime prompts and local files.

Install Mechanism

No explicit install spec was provided, but the bundle includes package.json with non-trivial dependencies (lancedb, chromadb, express, better-sqlite3, etc.) and large merged source files (~3MB). That implies a heavier install footprint if you run npm install or use the repository. The lack of an explicit install mechanism plus large third-party dependencies is a provenance/maintenance concern (you should validate dependency sources and lockfiles before installing).

Credentials

Registry metadata declares no required env vars or credentials, yet the docs and code expect multiple environment variables and read/write under user home (UNIFIED_MEMORY_*, OLLAMA_*; config files under ~/.unified-memory and ~/.openclaw). The skill also auto-writes to a workspace memory file and attempts to push extracted information into the main memory system. Requesting/using local paths and env vars without declaring them is disproportionate and risky.

Persistence & Privilege

always:false (good) but package.json exposes lifecycle hooks (before_prompt_build, agent_end). Hooks that run before prompt construction are powerful: combined with the prompt-injection patterns found in SKILL.md, they could alter prompts or agent behavior. The skill also writes persistent files under home directories (~/.unified-memory, ~/.openclaw), so it gains persistent local presence. This combination increases blast radius and should be reviewed before enabling.

Scan Findings in Context

[ignore-previous-instructions] unexpected: SKILL.md contains text patterns that attempt to override or ignore prior instructions — not expected for a memory-storage documentation and raises prompt-injection concerns.

[system-prompt-override] unexpected: Detected phrasing indicative of system-prompt override attempts. Coupled with package.json hooks (before_prompt_build) this is concerning because it could enable the skill to inject content into agent prompts.

What to consider before installing

This bundle appears to implement a full-featured memory system, but there are several red flags and inconsistencies you should address before installing: - Don’t trust metadata alone: the package claims no env/config requirements but the README/SKILL.md and source reference many env vars and config files (e.g., OLLAMA_URL, UNIFIED_MEMORY_*, ~/.unified-memory, ~/.openclaw). Expect to be prompted to provide these and the code will read/write to your home directory. - Prompt-injection risk: the SKILL.md contains patterns that look like attempts to override prompts, and package.json declares a before_prompt_build hook. If you enable this skill it could modify agent prompts or behavior — only allow it if you fully trust the author. - Code provenance and install safety: there is no explicit install spec but package.json lists many dependencies. Inspect the repo, lockfile, and large merged-src.js for any network calls, hidden endpoints or exec() usage. Prefer running in an isolated environment (container or VM) first. - Operational caution: do not run installation or deploy scripts (deploy-atomic-fixes.sh, verify-repairs.sh, or any scripts under ./scripts) on a production system without auditing them. These scripts may perform filesystem operations. Actionable steps before installing: 1) Review the source (merged-src.js, scripts) for any outbound network calls, eval/exec usages, or unexpected endpoints. 2) Run the package inside a sandboxed container with minimal privileges and no access to secrets. 3) If you need its functionality, prefer installing from a verified upstream repo with reproducible builds and pinned dependencies. 4) If you enable hooks, audit what data they receive and ensure they cannot alter system-level prompts. If you cannot perform these checks or do not trust the author (github: mouxangithub appears in docs but source registry owner is unknown), treat this skill as risky and avoid installing it in production or on machines with sensitive data.

Unified Memory — SKILL.md

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

---

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

核心修复

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

1. 原子事务管理器

// 两阶段提交协议，保证 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. 数据持久化保证

// 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. 一键部署

# 部署原子写入修复
./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. 新增梦境查询功能

# 查看系统统计
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. 记忆类型注册系统

// 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. 异步处理队列

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

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

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

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

4. 智能去重系统

// 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. 增强版记忆系统

// 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)
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 数据库路径

使用示例

# 使用 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

# 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 / 权限

{
  "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 / 快速使用示例

# 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 -->

# 健康检查
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 for details.

<!-- zh -->

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

范围过滤通过内存 Map 索引实现 O(1) 查询，详见 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

<!-- zh -->

完整架构详见 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	Overview, quick start, architecture, FAQ
docs/en/HOOK_INTEGRATION.md	Hook mechanism, before_prompt_build, agent_end, performance
docs/en/MCP_INTEGRATION.md	MCP tools, manual usage, configuration examples
docs/en/INTEGRATION_COMPARISON.md	Hook+MCP vs MCP-only vs Hook-only comparison

中文文档

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

---

Related Documentation / 相关文档

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

---

v4.4 Supermemory Features / Supermemory 功能

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

🎯 Dynamic Profile (动态画像)

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

功能:

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

API:

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:

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:

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:

import { hybridSearch } from './search/hybrid_search.js';

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

特性:

• 结果合并与重排序
• 去重处理
• 权重可配置

---

🔌 Connectors Framework (连接器框架)

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

BaseConnector:

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:

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)

---

📦 导出汇总

// 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	运行召回率基准测试

使用方法:

// 直接调用
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

运行时添加新类型:

addEntityType('framework', {
  label: '框架',
  color: '#ff6b6b',
  keywords: ['React', 'Vue', 'Angular', 'Next.js'],
  priority: 7,
});

使用 MCP 工具:

{
  "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 接口:

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 导出汇总

// 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.