TencentDB-Agent-Memory/README_CN.md

English

TencentDB Agent Memory

没有记忆的AI，只是工具；有记忆的AI，才是资产。

TencentDB Agent Memory是腾讯云数据库团队自研的 Agent 记忆系统，为 OpenClaw 补上长期连续的记忆。通过四层渐进式记忆金字塔架构，自动完成记忆写入、分层提炼、按需召回与注入，让 Agent 从“只能聊天对话”进化为“持续学习、更懂你、跨会话不断线的长期可依赖 AI 助理”。

评测

基于 PersonaMem（UPenn，COLM 2025）评测集，589 道题，20 个角色。

题型	OpenClaw 原生记忆	TencentDB Agent Memory
召回更新原因	70.97%	88.89%
偏好演变跟踪	66.67%	83.45%
个性化推荐	46.67%	76.36%
场景泛化	31.58%	78.95%
召回用户事实	29.63%	79.07%
召回事实	25.00%	76.47%
创意建议	24.00%	45.16%
总计	47.85%	76.10%

主要特点

• OpenClaw 原生插件，包名 @tencentdb-agent-memory/memory-tencentdb，一行命令即可安装
• 四层记忆链路：L0 原始对话 → L1 结构化记忆 → L2 场景归纳 → L3 用户画像
• 混合召回：支持 keyword、embedding、hybrid 三种策略
• 两类检索工具：tdai_memory_search（查结构化记忆）和 tdai_conversation_search（查原始对话）
• 本地优先存储：JSONL + SQLite，数据在本地可直接查看和排查
• 工程化能力：去重、checkpoint、备份、定时清理、指标日志
• MIT 许可证

快速开始

环境要求

• Node.js >= 22.16.0
• OpenClaw >= 2026.3.13

安装

openclaw plugins install @tencentdb-agent-memory/memory-tencentdb

安装完成后，插件接入 OpenClaw 对话生命周期，自动执行对话捕获、记忆召回和 L1/L2/L3 后续处理。

从源码开发

本项目无需编译。Node.js 22.16+ 原生支持 TypeScript 类型剥离，OpenClaw 直接加载 .ts 源码运行。

git clone https://github.com/TencentCloud/TencentDB-Agent-Memory.git
cd TencentDB-Agent-Memory
npm install
openclaw plugins install --link .

install --link 会将当前目录作为本地插件注册到 OpenClaw，修改源码后重启 Gateway 即可生效。

可选：开启 embedding 召回

如果需要向量检索或混合召回，补充 embedding 配置即可。当前支持兼容 OpenAI API 的远程 embedding 服务。

{
  "plugins": {
    "entries": {
      "memory-tencentdb": {
        "enabled": true,
        "config": {
          "embedding": { // 需配置自定义Embedding模型信息，非LLM模型
            "enabled": true, // 是否启用向量搜索
            "provider": "openai", // 暂只支持OpenAI兼容的协议
            "baseUrl": "https://xxx", // API Base URL
            "apiKey": "xxx", // API Key
            "model": "text-embedding-3-large", // 模型名称
            "dimensions": 1024 // 向量维度（需与所选模型匹配）
          }
        }
      }
    }
  }
}

架构

        ┌─────────────────┐
        │  L3 用户画像     │  偏好与行为模式
        ├─────────────────┤
        │  L2 场景归纳     │  跨会话的任务 / 场景块
        ├─────────────────┤
        │  L1 结构化记忆   │  事实、约束、偏好、决策
        ├─────────────────┤
        │  L0 原始对话     │  完整对话记录
        └─────────────────┘

各层各有侧重：

• L0 保留原始对话，用于回溯和精确检索
• L1 抽取高价值信息，直接用于召回
• L2 将零散记忆整理成场景块，跨会话聚合
• L3 维护用户画像，用于长期偏好建模

生命周期

阶段	触发时机	动作
Recall	before_prompt_build	召回相关记忆，注入上下文
L0	agent_end	写入原始对话
L1	调度触发	提取结构化记忆，去重，持久化
L2	L1 完成后	更新场景块
L3	达到阈值	生成或刷新用户画像
Shutdown	gateway_stop	清理资源

插件还注册了两个 tool 供 Agent 主动调用：

• tdai_memory_search：查 L1 结构化记忆。适合"用户偏好什么""之前确认过哪些约束"类问题。
• tdai_conversation_search：查 L0 原始对话。适合需要原始措辞的场景。

检索实现

三种召回策略：

策略	实现
keyword	FTS5 全文检索，中文分词基于 jieba
embedding	sqlite-vec 向量相似度检索
hybrid	融合关键词与向量结果

底层存储统一用 SQLite。

配置

按能力分组：

配置组	作用
capture	L0 对话捕获、排除规则、保留时间
extraction	L1 提取、去重、单次上限
persona	L2/L3 触发频率、场景上限、备份数量
pipeline	L1/L2/L3 调度节奏
recall	自动召回开关、结果数、阈值、策略
embedding	向量检索服务配置
report	指标日志

最小配置只需要安装插件。如果需要更好的召回效果，再加 embedding 和调度参数。

数据目录

<pluginDataDir>/
├── conversations/   # L0 原始对话
├── records/         # L1 结构化记忆
├── scene_blocks/    # L2 场景块
├── .metadata/       # checkpoint、索引、元数据
└── .backup/         # 备份

仓库范围

当前仓库是 OpenClaw 插件的核心实现。

包含：插件入口与生命周期钩子、四层记忆链路、检索工具与自动召回、JSONL + SQLite 本地存储、checkpoint / 备份 / 清理 / 日志。

代码结构

TencentDB-Agent-Memory/
├── index.ts                  # 插件注册、工具注册、生命周期接入
├── openclaw.plugin.json
├── package.json
├── CHANGELOG.md
└── src/
    ├── hooks/                # 自动召回与自动捕获
    ├── conversation/         # L0 对话管理
    ├── record/               # L1 提取与持久化
    ├── scene/                # L2 场景归纳
    ├── persona/              # L3 用户画像
    ├── store/                # SQLite / FTS / 向量检索
    ├── tools/                # 检索工具注册
    ├── prompts/              # prompt 模板
    ├── report/               # 指标上报
    └── utils/

许可证

MIT。详见 LICENSE。