@tdai/memory-tdai

Four-layer local memory system plugin for OpenClaw.

为 AI Agent 提供完全本地化的长期记忆能力。通过 L0→L1→L2→L3 四层渐进式管线，自动将对话内容提炼为结构化记忆、场景块和用户画像，无需任何外部 API 依赖。

✨ 核心功能

• L0 — 对话录制：自动捕获每轮对话原始消息到本地 SQLite + JSONL 双写
• L1 — 记忆提取：由本地 LLM 从对话中提取结构化记忆，支持向量去重与冲突检测
• L2 — 场景归纳：基于 L1 记忆自动归纳场景块（Scene Block），由 LLM 增量提取
• L3 — 用户画像：基于场景块自动生成/更新用户画像（Persona）
• 自动召回（Auto-Recall）：对话开始前自动注入相关记忆和用户画像到上下文
• 语义搜索工具：Agent 可调用 tdai_memory_search（L1 记忆搜索）和 tdai_conversation_search（L0 对话搜索）
• 向量搜索：基于 sqlite-vec + node-llama-cpp 的本地 embedding，支持 hybrid（关键词 + 向量 RRF 融合）搜索策略
• Session 隔离：不同渠道/Agent 的对话独立调度、独立提取
• 本地数据清理：可配置 L0/L1 数据保留天数，定时自动清理过期文件
• 支持纯本地：支持纯本地部署，不强依赖任何外部 API 依赖
• 支持零配置：支持零配置工作，简单易用

🏗️ 关键原理

对话开始
  → Auto-Recall: 向量/混合搜索相关记忆 + 加载 Persona → 注入系统上下文

对话结束
  → Auto-Capture (L0): 录制对话消息 → SQLite vec0 + JSONL 双写
  → Pipeline Scheduler: 达到 N 轮后按序触发 L1 → L2 → L3
     ├── L1: 本地 LLM 提取结构化记忆 + 向量去重 → 写入 JSONL + SQLite
     ├── L2: 本地 LLM 归纳场景块 → Markdown 文件
     └── L3: 本地 LLM 生成/更新用户画像 → persona.md

数据目录结构

<pluginDataDir>/
├── conversations/     — L0 每日 JSONL 分片（每行一条消息）
├── records/           — L1 每日 JSONL 分片（提取的记忆）
├── scene_blocks/      — L2 场景块 .md 文件
├── vectors.db         — SQLite + vec0 向量数据库
├── .metadata/         — checkpoint, scene_index.json
└── .backup/           — 滚动备份（persona, scene_blocks）

📋 前置依赖

| 依赖 | 版本要求 | 说明 | |------|---------|------| | OpenClaw | >= 2026.3.13 | 宿主框架，提供插件 SDK 及 Gateway 运行环境 | | Node.js | >= 22.16.0 | 运行时环境 | | node-llama-cpp | ^3.16.2 | 本地 embedding 模型（GGUF 格式），提供离线向量化能力。首次运行会自动下载模型 | | sqlite-vec | 0.1.7-alpha.2 | SQLite 向量搜索扩展，提供 KNN 近邻查询 |

node-llama-cpp 和 sqlite-vec 作为 dependencies 会随插件自动安装，无需手动处理。

📦 安装

# 安装插件
openclaw plugins install @tdai/memory-tdai

# 更新插件
openclaw plugins update memory-tdai

# 卸载插件
openclaw plugins uninstall memory-tdai

安装完成后，重启 Gateway 使插件生效：

openclaw gateway restart

⚙️ 配置

插件配置位于 ~/.openclaw/openclaw.json 中 memory-tdai 字段下。所有字段均有合理默认值，零配置即可使用。

最小配置

最小配置，安装启用后即为该状态

{
  "memory-tdai": {
    "enabled": true
  }
}

完整配置

用户可按需配置，提升使用体验

{
  "memory-tdai": {
    "capture": {
      "enabled": true,
      "excludeAgents": ["bench-judge-*"],
      "l0l1RetentionDays": 90,
      "cleanTime": "03:00"
    },
    "extraction": {
      "enabled": true,
      "enableDedup": true,
      "maxMemoriesPerSession": 10,
      "model": "provider/model-name"
    },
    "pipeline": {
      "everyNConversations": 5,
      "enableWarmup": true,
      "l1IdleTimeoutSeconds": 60,
      "l2DelayAfterL1Seconds": 90,
      "l2MinIntervalSeconds": 300,
      "l2MaxIntervalSeconds": 1800,
      "sessionActiveWindowHours": 24
    },
    "recall": {
      "enabled": true,
      "maxResults": 5,
      "scoreThreshold": 0.3,
      "strategy": "hybrid"
    },
    "embedding": {
      "enabled": true,
      "provider": "local", 
      "model": "",
      "dimensions": 768
    },
    "persona": {
      "triggerEveryN": 50,
      "maxScenes": 20,
      "backupCount": 3,
      "sceneBackupCount": 10,
      "model": "provider/model-name"
    }
  }
}

配置说明

capture — 对话捕获 (L0)

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | enabled | boolean | true | 是否启用自动对话捕获 | | excludeAgents | string[] | [] | Agent 排除 glob 模式列表，匹配的 agent 不参与捕获/召回/调度 | | l0l1RetentionDays | number | 0 | L0/L1 本地文件保留天数。0 = 不清理；非 0 时需 >= 3（除非开启 allowAggressiveCleanup） | | allowAggressiveCleanup | boolean | false | 是否允许 1–2 天的高风险清理配置 | | cleanTime | string | "03:00" | 每日清理执行时间（HH:mm 格式） |

extraction — 记忆提取 (L1)

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | enabled | boolean | true | 是否启用后台记忆提取 | | enableDedup | boolean | true | 启用 L1 智能去重（基于向量相似度冲突检测） | | maxMemoriesPerSession | number | 10 | 单次 L1 提取每 session 最大记忆条数 | | model | string | (默认) | 提取使用的 LLM 模型（格式：provider/model） |

pipeline — 管线调度 (L1→L2→L3)

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | everyNConversations | number | 5 | 每 N 轮对话触发一次 L1 批处理 | | enableWarmup | boolean | true | Warm-up 模式：新 session 从 1 轮触发开始，每次 L1 后翻倍（1→2→4→...→N） | | l1IdleTimeoutSeconds | number | 60 | 用户停止对话后多久触发 L1（秒） | | l2DelayAfterL1Seconds | number | 90 | L1 完成后延迟多久触发 L2（秒） | | l2MinIntervalSeconds | number | 300 | 同一 session 两次 L2 的最小间隔（秒） | | l2MaxIntervalSeconds | number | 1800 | 活跃 session 的 L2 最大轮询间隔（秒） | | sessionActiveWindowHours | number | 24 | 超过此时间不活跃的 session 停止 L2 轮询 |

recall — 记忆召回

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | enabled | boolean | true | 是否启用对话前自动召回 | | maxResults | number | 5 | 召回最大结果数 | | scoreThreshold | number | 0.3 | 最低分数阈值 | | strategy | string | "hybrid" | 搜索策略：keyword（关键词）、embedding（向量）、hybrid（混合 RRF 融合，推荐） |

embedding — 向量搜索

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | enabled | boolean | true | 是否启用向量搜索 | | provider | string | "local" | Embedding 提供者：local（node-llama-cpp 本地模型）或 openai（OpenAI 兼容 API） | | baseUrl | string | "https://api.openai.com/v1" | API Base URL（仅 openai provider） | | apiKey | string | — | API Key（仅 openai provider，留空自动 fallback 到 local） | | model | string | (自动) | 模型名称（local 留空自动选择；openai 默认 text-embedding-3-large） | | dimensions | number | (自动) | 向量维度（local = 768, openai = 3072） | | conflictRecallTopK | number | 5 | 冲突检测时召回 Top-K 数 | | modelCacheDir | string | — | 本地模型缓存目录（仅 local provider） |

persona — 场景归纳与用户画像 (L2/L3)

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | triggerEveryN | number | 50 | 每 N 条新记忆触发一次画像生成 | | maxScenes | number | 20 | 最大场景块数量 | | backupCount | number | 3 | 画像备份保留数量 | | sceneBackupCount | number | 10 | 场景块备份保留数量 | | model | string | (默认) | L2/L3 使用的 LLM 模型（格式：provider/model） |

🔧 Agent 工具

插件注册了两个 Agent 可调用的工具：

tdai_memory_search

搜索用户的 L1 结构化长期记忆。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | query | string | ✅ | 搜索查询 | | limit | number | — | 返回结果上限（默认 5，最大 20） | | type | string | — | 按记忆类型过滤：persona / episodic / instruction | | scene | string | — | 按场景名过滤 |

tdai_conversation_search

搜索 L0 原始对话历史。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | query | string | ✅ | 搜索查询 | | limit | number | — | 返回结果上限（默认 5，最大 20） | | session_key | string | — | 按 session 过滤 |

📁 数据与日志

• 数据目录：~/.openclaw/state/memory-tdai/（自动创建）
• Gateway 日志：插件运行日志通过 [memory-tdai] 前缀标记，可在 Gateway 日志中搜索查看
• 配置文件：~/.openclaw/openclaw.json

📄 License

MIT