@tencentdb-agent-memory/memory-tencentdb

Four-layer memory system plugin for OpenClaw.

为 AI Agent 提供长期记忆能力。通过 L0→L1→L2→L3 四层渐进式管线，自动将对话内容提炼为结构化记忆、场景块和用户画像。支持纯本地 SQLite 和远端腾讯云向量数据库（TCVDB）两种存储后端。

✨ 核心功能

• L0 — 对话录制：自动捕获每轮对话原始消息，IMemoryStore + JSONL 双写
• L1 — 记忆提取：由 LLM 从对话中提取结构化记忆，支持向量去重与冲突检测
• L2 — 场景归纳：基于 L1 记忆自动归纳场景块（Scene Block），由 LLM 增量提取
• L3 — 用户画像：基于场景块自动生成/更新用户画像（Persona）
• 自动召回（Auto-Recall）：对话开始前自动注入相关记忆和用户画像到上下文
• 多后端存储：支持 sqlite（本地 SQLite + sqlite-vec）和 tcvdb（腾讯云向量数据库，服务端 embedding + hybridSearch）
• BM25 稀疏向量：内置 BM25 编码器（tcvdb-text），支持中英文混合搜索
• 关键词+向量混合搜索：hybrid（关键词 + 向量 RRF 融合）搜索策略
• 语义搜索工具：Agent 可调用 tdai_memory_search（L1 记忆搜索）和 tdai_conversation_search（L0 对话搜索）
• Seed CLI：openclaw memory-tdai seed 命令，支持导入历史对话数据（详见 CLI 文档）
• Session 隔离：不同渠道/Agent 的对话独立调度、独立提取
• 本地数据清理：可配置 L0/L1 数据保留天数，定时自动清理过期文件
• Manifest 元数据：数据目录自动生成 .metadata/manifest.json，记录 store 绑定信息和 seed 运行记录
• 支持零配置：支持零配置工作，简单易用

🏗️ 关键原理

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

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

数据目录结构

<pluginDataDir>/
├── conversations/     — L0 每日 JSONL 分片（每行一条消息）
├── records/           — L1 每日 JSONL 分片（提取的记忆）
├── scene_blocks/      — L2 场景块 .md 文件
├── vectors.db         — SQLite + vec0 向量数据库（仅 storeBackend=sqlite）
├── .metadata/
│   ├── manifest.json  — 数据目录元数据（store 绑定、seed 信息）
│   └── checkpoint.json
└── .backup/           — 滚动备份（persona, scene_blocks）

📋 前置依赖

默认场景下无需安装 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 字段下。所有字段均有合理默认值，零配置即可使用。

最小配置

安装启用后即为该状态（默认使用本地 SQLite 后端）：

{
  "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 }
      }
    }
  }
}

TCVDB 后端配置

使用腾讯云向量数据库作为存储后端：

{
  "memory-tencentdb": {
    "storeBackend": "tcvdb",
    "tcvdb": {
      "url": "http://your-vdb-instance:8100",
      "apiKey": "your-api-key",
      "database": "my_memory_db",
      "alias": "生产环境"
    }
  }
}

完整配置

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

{
  "memory-tencentdb": {
    "storeBackend": "sqlite",
    "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": 15,
      "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
    },
    "tcvdb": {
      "url": "http://your-vdb-instance:8100",
      "username": "root",
      "apiKey": "your-api-key",
      "database": "my_memory_db",
      "alias": "生产环境",
      "embeddingModel": "bge-large-zh",
      "timeout": 10000
    },
    "bm25": {
      "enabled": true,
      "language": "zh"
    }
  }
}

配置说明

storeBackend — 存储后端

capture — 对话捕获 (L0)

extraction — 记忆提取 (L1)

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

recall — 记忆召回

embedding — 向量搜索（仅 sqlite 后端）

tcvdb — 腾讯云向量数据库（仅 storeBackend=tcvdb）

bm25 — BM25 稀疏向量编码

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

report — 指标上报

🖥️ CLI 命令

插件提供 openclaw memory-tdai 命令空间，支持以下子命令：

seed — 导入历史对话数据

将历史对话 JSON 文件导入到记忆管线中，完整执行 L0→L1→L2→L3 流程。

openclaw memory-tdai seed --input conversations.json [--output-dir ./output] [--config seed-config.json] [--yes]

详细用法、输入格式和配置覆盖机制请参阅 CLI 文档。

🔧 Agent 工具

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

tdai_memory_search

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

tdai_conversation_search

搜索 L0 原始对话历史。

📁 数据与日志

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

📄 License

MIT