mirror of
https://github.com/TencentCloud/TencentDB-Agent-Memory
synced 2026-07-10 12:34:27 +00:00
yuanrengu
69a95536ad
The CMD script writes MODEL_API_KEY to .env as OPENAI_API_KEY but does not include it in config.yaml's model section. Hermes with provider: custom reads api_key from model.api_key in config.yaml, not from OPENAI_API_KEY in .env. This causes 401 Authentication Fails when users start a conversation inside the container. Fix: add api_key field to the generated config.yaml model section.
355 lines
16 KiB
Markdown
355 lines
16 KiB
Markdown
# Changelog
|
||
|
||
本文件记录 `@tencentdb-agent-memory/memory-tencentdb` 插件的所有显著变更，格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循 [Semantic Versioning](https://semver.org/)。
|
||
|
||
---
|
||
|
||
## [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](https://github.com/openclaw/openclaw/pull/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 存储设计文档及迁移指南
|
||
|
||
---
|
||
|
||
<details>
|
||
<summary>预发布版本</summary>
|
||
|
||
## [0.2.0-beta.1] - 2026-04-14
|
||
|
||
*此版本的内容已合并至 [0.2.0] 正式版。*
|
||
|
||
</details>
|
||
|
||
## [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 数据
|