@tencentdb-agent-memory/memory-tencentdb

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）：对话开始前自动注入相关记忆和用户画像到上下文
• 关键词+向量混合搜索：用户配置 embedding 后，支持 hybrid（关键词 + 向量 RRF 融合）搜索策略
• 语义搜索工具：Agent 可调用 tdai_memory_search（L1 记忆搜索）和 tdai_conversation_search（L0 对话搜索）
• 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 时由宿主按需安装 | | sqlite-vec | 0.1.7-alpha.2 | SQLite 向量搜索扩展，提供 KNN 近邻查询 |

默认场景下无需安装 node-llama-cpp。如需启用本地 embedding，再在宿主环境手动安装该包。

📦 安装

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

# 更新插件
openclaw plugins update memory-tencentdb

# 卸载插件
openclaw plugins uninstall memory-tencentdb

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

openclaw gateway restart

⚙️ 配置

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

最小配置

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

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

⚠️ 重要：allowPromptInjection 必须为 true

本插件通过 before_prompt_build hook 在对话开始前将召回的记忆注入系统上下文。 OpenClaw v2026.4.5+ 新增了 allowPromptInjection 安全控制，当该选项设为 false 时， before_prompt_build hook 将被完全阻止注册，导致记忆召回静默失效（不会报错，仅有 warn 日志）。

请确保 openclaw.json 中不要将该插件的 allowPromptInjection 设为 false：

// ❌ 错误配置 — 会导致记忆召回完全失效
{
  "plugins": {
    "entries": {
      "memory-tencentdb": {
        "hooks": { "allowPromptInjection": false }
      }
    }
  }
}

完整配置

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

{
  "memory-tencentdb": {
    "capture": {
      "enabled": true,
      "excludeAgents": ["bench-judge-*"],
      "l0l1RetentionDays": 90,
      "allowAggressiveCleanup": false,
      "cleanTime": "03:00"
    },
    "extraction": {
      "enabled": true,
      "enableDedup": true,
      "maxMemoriesPerSession": 20,
      "model": "provider/model-name"
    },
    "persona": {
      "triggerEveryN": 50,
      "maxScenes": 20,
      "backupCount": 3,
      "sceneBackupCount": 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",
      "timeoutMs": 5000
    },
    "embedding": {
      "enabled": true,
      "provider": "none",
      "baseUrl": "https://your-embedding-endpoint/v1",
      "apiKey": "your-api-key",
      "model": "text-embedding-3-small",
      "dimensions": 1536,
      "conflictRecallTopK": 5,
      "maxInputChars": 5000,
      "timeoutMs": 10000
    }
  }
}

配置说明

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 | 20 | 单次 L1 提取每 session 最大记忆条数 | | model | string | (OpenClaw 默认模型) | 提取使用模型（格式：provider/model），未填写时使用 OpenClaw 默认模型 |

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 融合，推荐） | | timeoutMs | number | 5000 | 整体召回超时（毫秒）。超时后跳过记忆注入并输出 warn 日志，避免阻塞用户对话 |

embedding — 向量搜索

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | enabled | boolean | true | 是否启用向量搜索（若 provider="none"，则实际会被禁用） | | provider | string | "none" | Embedding 服务提供者：none 表示禁用向量；其他值（如 openai、deepseek）按 OpenAI 兼容远端服务处理 | | baseUrl | string | — | API Base URL（远端模式必填）：填写对应 provider 的 API 地址 | | apiKey | string | — | API Key（远端模式必填） | | model | string | — | 模型名称（远端模式必填） | | dimensions | number | — | 向量维度（远端模式必填，需与模型匹配） | | conflictRecallTopK | number | 5 | 冲突检测时召回 Top-K 数 | | maxInputChars | number | 5000 | Embedding 输入文本最大字符数，超出时截断并打印警告日志（适合大多数模型的 token 上限） | | timeoutMs | number | 10000 | 单次 embedding API 调用超时（毫秒）。超时后该次 embedding 请求中止，不重试 |

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

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

report — 指标上报

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | enabled | boolean | false | 是否启用指标上报（通过 Gateway 日志输出结构化 METRIC JSON） | | type | string | "local" | 上报方式：local 表示通过 logger 输出结构化 JSON 日志 |

🔧 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