Skill: mouxangithub/unified-memory-v5 (version 5.2.4)

# 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. | | [REDACTED_SECRET] | 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).


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: clean (LOW)