// 两阶段提交协议，保证 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;
}

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

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

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

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

# 查看系统统计
npm run stats

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

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

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

// 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);

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

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

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

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

// 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);

// 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  # 智能去重器

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

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 扩展

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

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

# 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 '{}'

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

# 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"}'

# 健康检查
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"}'

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

import { getProfile } from './profile/dynamic_profile.js';

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

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

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

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

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

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

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

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

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

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

import { BaseConnector } from './connectors/base.js';

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

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

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 };
  }
}

// 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';

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

~/.openclaw/skills/unified-memory/src/benchmark/results/

~/.openclaw/workspace/memory/config/entity_types.json

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

{
  "name": "memory_entity_type_add",
  "arguments": {
    "typeName": "framework",
    "label": "开发框架",
    "color": "#ff6b6b",
    "keywords": ["React", "Vue", "Angular"],
    "priority": 7
  }
}

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: { /* 自定义配置 */ },
};

beforeSearch → [实际搜索] → afterSearch
                   ↓
beforeWrite → [实际写入] → afterWrite

~/.openclaw/workspace/memory/plugins/registry.json

// 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';