TencentDB-Agent-Memory/CHANGELOG.md

Changelog

本文件记录 @tencentdb-agent-memory/memory-tencentdb 插件的所有显著变更，格式遵循 Keep a Changelog，版本号遵循 Semantic Versioning。

---

[Unreleased]

🐛 修复

• Hermes Docker 镜像 config.yaml 缺少 api_key 字段：Dockerfile.hermes 的 CMD 脚本将 API Key 写入了 .env 的 OPENAI_API_KEY，但未写入 config.yaml 的 model.api_key，导致 provider: custom 时 Hermes 无法找到认证凭据（报 401 Authentication Fails）。现修复为在 config.yaml 的 model 段同步写入 api_key: "${MODEL_API_KEY}"。

---

[0.3.5] - 2026-05-15

🐛 修复

• 兼容 OpenClaw v2026.5.7 zod v4 子路径：显式声明 zod@^4.4.3 依赖，解决 @ai-sdk/provider-utils@4.x 需要 zod/v4 子路径导出但宿主环境可能 hoist zod@3.x 引发 Cannot find module zod/v4 的运行时错误。

✨ 改进

• L1→L2 延迟从 90s 降至 10s：l2DelayAfterL1Seconds 默认值 90→10，冷启动用户不再需要等待 ~90s 才能看到 L2 场景提取结果，体感更及时。

📖 文档

• README 新增 Docker Quick Start 章节，说明模型 URL/Name 环境变量配置方式。

---

[0.3.4] - 2026-05-12

🐛 修复

• 兼容 OpenClaw v2026.4.7 以下版本 L1 抽取空输出：旧宿主不支持 systemPromptOverride，通过 extraSystemPrompt 回退注入系统提示，确保 LLM 按数据提取助手身份工作。
• TCVDB hybrid 召回冗余双重 HTTP 调用：auto-recall 对 TCVDB 发两次相同的 hybridSearch 请求（且 keyword 路径将 FTS5 OR 表达式错误传入 BM25 编码器）。新增 nativeHybridSearch 短路，TCVDB 单次调用即可完成 dense + sparse + RRF，recall 耗时减半（~50-120ms）。
• L2 parser 对齐 Go 后端：增加 mermaid fallback，修复 first{...last} JSON 提取逻辑。

✨ 改进

• VDB HTTP 请求级计时：tcvdb-client 每次请求打一条 info 计时日志（/document/hybridSearch 85ms），retry/失败细节保持 debug 级别。
• 启动路径误导性日志降级为 DEBUG：store manifest 不一致、sqlite schema migration、profile-sync MD5 mismatch 等正常场景不再打 warn/info，避免 AI 误判。
• L1 提取调试日志：新增 [l1-debug] 系列（RESOLVE / INVOKE / RESULT / EMPTY_DUMP / ENTRY / NO_JSON），方便定位 LLM 调用链问题。

🔧 兼容性适配

• OC 2026.4.23 Zod schema 兼容 patch 脚本（scripts/bugfix-20260423/）：一键修复 allowConversationAccess 被 .strict() 拒绝的问题，含轻量版脚本、全自动脚本、手动 SOP 文档。
• Offload 日志去掉 Backend 前缀，默认超时为 120s。

📦 新功能

• Offload Local Mode：支持本地模式运行 offload（不依赖远端后端）。
• Docker 一体化镜像（Dockerfile.hermes）：单容器捆绑 Hermes Agent + memory_tencentdb 插件 + TDAI Memory Gateway，统一 MODEL_* 环境变量驱动。

✅ 测试

• 修复 fault-injection FI-05 mock config 缺 embedding 字段
• 修复 cli.test dependencies 断言适配新增依赖
• 跳过 patch-effectiveness 已删除的 install-plugin.sh 测试

---

[0.3.3] - 2026-05-08

🐛 修复

• 加固 hook-policy 版本决策逻辑：仅当宿主版本为严格 x.y.z 语义化版本、且 >= 2026.4.24 时才自动写入 hooks.allowConversationAccess；无法解析（如 unknown、beta、snapshot 等非标准版本）时一律跳过，避免对旧版本或非预期版本误写配置导致启动失败。
• hook-policy 关键路径补充 debug 日志（原始版本串、解析后版本、最小要求版本、是否 patch 的决策），方便线上排查。

✅ 测试

• 新增 src/utils/ensure-hook-policy.test.ts，覆盖标准版本、预发布、unknown、边界值等决策 case。

[0.3.2] - 2026-05-08

🐛 修复

• 兼容 OpenClaw v2026.4.23 前的版本，防止写入的 hook 配置导致无法启动
• 修改 allowConversationAccess 到 2026.4.24+ 添加。

[0.3.1-beta.1] - 2026-05-07

🐛 修复

• 兼容 OpenClaw v2026.4.23+ hook 权限策略：该版本引入 allowConversationAccess 安全门控（openclaw#70786），导致非 bundled 插件的 agent_end hook 被静默拦截，整个 capture pipeline 失效。新增 ensurePluginHookPolicy() 自动检测并补全配置，优先通过 SDK 触发 gateway 自动重启，fallback 手动写入配置文件。
• 兼容 OpenClaw 2026.5.3+ 安装校验：新增 tsdown 构建配置生成 dist/index.mjs，满足新版安装时对编译产物的强制校验（不再允许纯 TypeScript 入口）。
• 声明 activation.onStartup：确保 gateway 在启动时加载本插件。
• 声明 contracts.tools：注册 tdai_memory_search、tdai_conversation_search 工具名，满足 tool registration contract 要求。

---

[0.3.0] - 2026-05-06

🚀 新功能

运维管理工具（CTL）

• 新增 memory-tencentdb-ctl 命令行管理工具，支持 standalone 与 hermes 两种运行模式
• 新增 install-memory-tencentdb 一键安装脚本
• CTL 新增 config vdb-off 命令，支持将 Gateway 存储从 VDB 回退到 SQLite
• Gateway 安装脚本支持将环境变量写入 ~/.hermes/.env（systemd 场景）

Offload 增强

• Offload 启动时自动应用 after_tool_call patch，patch 失败时自动禁用 offload
• 新增 setup-offload.sh 一键启用/禁用 offload 脚本，支持 --backend-api-key 参数
• L0 捕获过滤：排除 offload 注入的 MMD 上下文块，避免将压缩中间产物误存为记忆

Gateway 自愈与稳定性

• Hermes 插件新增 watchdog + lazy probe 机制，Gateway 异常时自动恢复
• Gateway YAML 配置解析支持任意深度嵌套

✨ 改进

• 数据目录与安装目录统一整合至 ~/.memory-tencentdb/
• 引入 $HERMES_HOME 环境变量约定，移除硬编码 ~/.hermes 路径
• CTL hermes 配置编辑改为缩进感知，保持原始文件格式
• 运维脚本保留在 tarball 中但不再注册为 bin 命令（减少全局命令污染）
• init/destroy 生命周期日志降级为 debug 级别
• patch 脚本兼容 pnpm 安装环境，使用 Node.js 动态解析 openclaw 安装路径

🐛 修复

Core 稳定性

• 修复 ensureSchedulerStarted 并发调用下的竞态问题
• 修复 /session/end 错误销毁全局 scheduler 的问题（改为按 session_key 作用域）
• 修复关闭 store 时未等待后台 fire-and-forget 任务完成的问题
• 修复 disable_offload 未正确删除 slots.contextEngine 配置的问题

Offload

• 修复 slot 占用检测逻辑：仅在 ok=false（slot 被占用）时拒绝，API 异常不再误判为冲突
• 修复 registerContextEngine 抛异常时未禁用 offload 的问题
• 修复 slot 被占用时未完全禁用所有 offload 功能的问题

L3 压缩

• 修复 aggressive/emergency 压缩在用户消息位于队首时卡死的问题
• 修复消息被大量 offload 后压缩停滞的问题

迁移工具

• 修复源数据目录或 SQLite 不存在时迁移脚本崩溃的问题（改为优雅跳过）
• 修复源数据为空时 config/manifest 未写入的问题

脚本与运维

• 修复 set -e 环境下 ((VAR++)) 在 VAR=0 时导致脚本退出的问题
• 修复 patch 脚本误报 FAILED 计数的问题（跳过无 after_tool_call 上下文的候选项）
• 修复 Hermes 退出时未终止 Gateway 子进程的问题

♻️ 重构

• 统一 patch 检测逻辑：始终委托给 patch 脚本并通过退出码判定结果

---

[0.3.0-beta.1] - 2026-04-23

🚀 新功能

短期记忆压缩（Context Offload）

• 新增 Offload 模块，支持长对话场景下的上下文压缩与记忆卸载

架构重构：Core + Gateway 多框架支持

• 重构为 TdaiCore 宿主无关的核心层 + 适配器模式，解耦 OpenClaw 框架依赖
• 新增 HostAdapter / LLMRunner / LLMRunnerFactory 抽象接口，支持不同宿主的 LLM 调用
• 新增 Hermes Gateway 适配器（memory_tencentdb Hermes Plugin），支持通过 Hermes 框架独立运行
• TdaiCore 提供统一的 handleBeforeRecall() / handleTurnCommitted() / searchMemories() 等 API
• Gateway 零配置自动发现：Hermes 插件自动检测配置和数据目录
• 数据目录所有权从插件移至 Gateway 层管理

Recall 注入优化（Cache 友好）

• L1 召回记忆从 appendSystemContext 移到 prependContext（用户消息前缀），避免每轮系统提示词变化导致 prompt cache bust
• Persona / Scene Navigation / Tools Guide 保持在 appendSystemContext（稳定内容，连续多轮 cache 命中）
• 注册 before_message_write 钩子，在 user message 持久化到 JSONL 前 strip <relevant-memories> 标签，防止历史消息中累积旧的召回内容

分场景 Embedding 超时

• 新增 embedding.recallTimeoutMs（recall 路径）和 embedding.captureTimeoutMs（capture 路径）配置
• recall 超时时 hybrid 策略自动降级为纯关键词搜索；capture 超时时 L1 dedup 降级为 FTS
• 向前兼容：不配置时 fallback 到全局 embedding.timeoutMs

✨ 改进

• CleanContextRunner 通过 systemPromptOverride 替换 OpenClaw 默认系统提示词，每次 L1/L2/L3 调用节省 ~4500 input tokens
• L2（场景提取）和 L3（画像生成）prompt 拆分为 systemPrompt + userPrompt，角色划分更清晰
• Pipeline 默认参数调整：l1IdleTimeoutSeconds 60→600s，l2MinIntervalSeconds 300→900s，l2MaxIntervalSeconds 1800→3600s

🐛 修复

• 修复 pullProfilesToLocal 并发竞争导致 ENOTEMPTY 错误（乐观无锁修法：rename 竞争失败时静默使用对方结果）
• 修复 originalUserMessageCount 数据链路断裂导致 L0 recorder 无法定位被污染的 user message
• 修复 RecallResult 类型定义缺少 prependContext 字段（types.ts 与 auto-recall.ts 不一致）

---

[0.2.2] - 2026-04-17

🐛 修复

• 修复因未声明 undici 依赖导致 TCVDB 客户端加载失败的问题（开发环境之前依赖 monorepo 根 node_modules 的传递解析）
• 将插件注册阶段的大量 INFO 日志降级为 DEBUG，避免 CLI 模式下输出过多无关日志

[0.2.1] - 2026-04-16 (deprecated)

NOTE: 此版本由于存在 undici 依赖导致插件启动失败的问题，已废弃 相关问题在 0.2.2 及以后版本中已修复

🚀 新功能

• TCVDB 新增 HTTPS 连接支持，可通过插件配置 caPemPath 或迁移脚本参数 --tcvdb-ca-pem 指定自定义 CA 证书 PEM 文件
• read-local-memory 脚本新增 L2 单文件查询，并将 L0 / L1 查询切换为直接从 vectors.db 读取，支持 SQL 层过滤、排序与分页

✨ 改进

• TCVDB 的 L0 / L1 向量索引默认调整为 DISK_FLAT，并在不支持该索引类型的实例上自动回退到 HNSW
• 默认服务端 embedding 模型调整为 bge-large-zh
• TCVDB 所有读接口统一启用 readConsistency: "strongConsistency"，消除 read-after-write 不一致
• 健康检测脚本 VDB 连接支持 HTTPS 自签证书

🐛 修复

• 修复 L3 persona sync 因未拉取远端 baseline 导致版本冲突跳过写入的问题
• 修复 memories_since_last_persona 被 L0 和 L1 双重计数导致 persona 触发阈值膨胀的问题
• 移除 CheckpointManager 中已被 captureAtomically() 替代的废弃方法

---

[0.2.0] - 2026-04-15

🚀 新功能

腾讯云向量数据库（TCVDB）存储后端

• 新增腾讯云向量数据库存储后端，支持向量 + BM25 混合召回
• 支持 SQLite 与 TCVDB 之间的索引结构同步
• L2 场景 / L3 画像支持在本地缓存与向量数据库之间双向同步
• 插件配置（manifest）暴露 storeBackend、tcvdb、bm25、embedding.timeoutMs 等配置项

本地 BM25 关键字检索

• 使用本地 tcvdb-text 编码器替代原有的 BM25 HTTP sidecar 服务，消除外部依赖

Seed 数据导入工具

• 新增 CLI seed 命令，支持从外部数据批量导入记忆
• 提取共享的 pipeline-factory，供 seed 和正常运行时复用
• 支持 ISO 8601 时间戳格式（移除 JSONL 支持）

数据迁移与运维工具

• 新增 SQLite → 腾讯云向量数据库迁移脚本，支持 --help / -h 展示完整参数说明和使用示例
• 新增 VDB 数据导出脚本（含预编译 JS 和 CLI 启动器）
• 新增本地 Memory 数据查询脚本
• 注册全部 CLI bin 入口：migrate-sqlite-to-tcvdb、export-tencent-vdb、read-local-memory

记忆搜索工具调用限制

• tdai_memory_search + tdai_conversation_search 增加每轮合计最多 3 次的调用次数限制，通过 tool description 和召回引导提示词约束模型行为，防止陷入无效重复搜索

🐛 修复

• 修复 L2 场景合并（MERGE）无法删除旧文件的问题：OpenClaw 4.1+ 的 write 工具拒绝空白内容，改用 [DELETED] 标记实现软删除，SceneExtractor cleanup 阶段同步识别并清理
• 修复 L2 抽取产生孤立 BATCH/ARCHIVE 文件的问题，统一 maxScenes 上限为 15
• 修复 L3 启动时重复拉取 profile 的问题
• 过滤 skill wrapper 噪声标记（¥¥[...]¥¥）
• 处理 createCollection 并发竞态（错误码 15202）

♻️ 重构

• Pipeline checkpoint 游标语义从 timestamp 改为 update_at
• Runner 改用 api.runtime.agent.runEmbeddedPiAgent，避免跨环境导入失败
• 统一脚本构建流程：新增 build:scripts 一键编译命令，prepack 钩子确保 npm pack 前自动编译全部脚本产物

📚 文档

• 新增 AI Agent 长期记忆插件设计与实现技术文档
• 新增项目指南、研发系统分层架构文档
• 新增 VDB 存储设计文档及迁移指南

---

预发布版本

[0.2.0-beta.1] - 2026-04-14

此版本的内容已合并至 [0.2.0] 正式版。

[0.1.4] - 2026-04-10

🚀 Features

• (auto-recall) Add recall hint text before memories

[0.1.3] - 2026-04-09

🚀 功能

• (memory-tdai) 用 reporter 抽象替换 emitMetric
• (L3) L3 使用读写工具，防止模型输出 CoT
• (memory) 添加 embedding 截断、召回超时，以及从 L0 捕获中剔除代码块
• (config) Embedding 超时支持配置
• (report) 在 schema 中暴露 report 配置项，默认值改为 false

🐛 修复

• (capture) 跳过心跳/定时任务/自动化/调度类消息
• (recall) 召回完成时清除超时定时器，避免误报超时警告

💼 Other

• 重命名包名为 memory-tencentdb
• (deps) 将 node-llama-cpp 改为可选依赖

⚡ 性能

• (auto-capture) 将 L0 向量嵌入移至后台以降低延迟

📚 文档

• 添加 allowPromptInjection 配置警告说明

[0.1.2] — 2026-03-26

更新内容

1. 优化对话捕获与记忆抽取过滤机制

[0.1.1] — 2026-03-25

更新内容

1. 兼容 openclaw 2026.3.23 更新

[0.1.0] — 2026-03-25

首个正式发布版本。本地优先的四层记忆系统（L0→L1→L2→L3），基于 SQLite + LLM 实现对话捕获、记忆提取、场景归纳与用户画像。

更新内容

1. 关键字检索增加 FTS5 全文索引，采用 jieba 分词
2. 未配置远程 embedding 服务时，默认不开启 embedding 能力（不自动使用本地 embedding，且封禁主动使用本地 embedding 的配置入口）
3. 优化 L2、L3 生成 prompt 以控制生成内容大小（减少 token 开销）
4. Pipeline 调度器优化文件锁用法
5. 避免全量读取 L0、L1 数据