v1.0.0

[1.0.0] - 2026-06-11

正式版发布：从 OpenClaw 专属插件演进为面向所有 Agent 的通用记忆服务。完整的 Gateway 独立服务 + v2 HTTP API + 官方 TypeScript / Python SDK，任何 Agent 框架均可接入完整的多层记忆与上下文压缩能力。

⚠️ Breaking Changes

• 客户端/服务端架构拆分：记忆引擎从 OpenClaw 嵌入式插件拆分为独立 Gateway 服务进程，部署方式与接入方式发生变化。
• 配置结构变更：插件配置结构扁平化重构，原 gateway 字段迁移为 server 嵌套。
• 插件入口模式变更：支持 local（进程内本地运行，默认）和 client（连接外部 Memory Gateway）两种接入模式。

🚀 独立 Gateway 服务（v2 API）

记忆能力不再绑定 OpenClaw 宿主，以独立服务形式运行，通过 v2 HTTP API 为任意 Agent 提供记忆读写与管线管理：

• 完整 v2 API：14 条标准路由覆盖记忆 CRUD、原子更新、场景索引、管线状态查询等全部操作。
• 管线状态查询（/v2/pipeline/status）：实时获取 L1/L2/L3 各阶段运行状态与进度。
• 实例生命周期管理（/v2/instance/destroy）：支持外部系统主动创建/销毁记忆实例。
• 可选 Bearer 鉴权 + CORS 白名单：保护对外暴露的 API 安全。
• 请求体校验：强制 1 MiB 上限，防止异常请求。

🚀 官方 SDK

• TypeScript SDK 1.0.0（@tencentdb-agent-memory/memory-sdk-ts）：类型安全，覆盖全部 v2 API，npm 安装即用。
• Python SDK（tencentdb-agent-memory-sdk-python）：pip wheel 安装，同步/异步双模式，覆盖全部 v2 API。

🚀 通用 Agent 框架适配

• OpenClaw 插件适配：支持 local（进程内本地运行，默认）和 client（连接外部 Memory Gateway）两种接入模式。local 模式保持原有体验。
• Hermes Agent 适配：memory_tencentdb_v2 adapter，支持 Hermes 框架多租户场景。
• 通用接入：任何能发 HTTP 请求的 Agent（LangChain、AutoGPT、自研框架等）均可通过 SDK 或裸 API 接入。

🚀 可观测性

• OpenTelemetry 全链路 Trace：支持 OTLP 协议上报，可对接 Jaeger / Grafana Tempo 等后端。
• Langfuse 集成：仅转发 LLM 相关 span，适合评估记忆提取质量。
• 管线评测指标：L1 提取率、去重决策分布、各阶段 token 消耗、recall 延迟等。

🚀 Offload Server V2

• L1 / L1.5 / L2 异步执行器：独立的 Offload 处理管线，支持大规模会话并发。
• L3 压缩处理器：Mermaid 符号化 + 上下文预算控制，智能上下文压缩。
• MMD 注入：支持多模态数据注入 Offload 流程。
• Gateway 集成 /v2/offload/* 路由：统一 Offload API 入口。

📦 部署方式

方式	说明
Docker 容器	docker pull agentmemory/hermes-memory:1.0.0
源码直接运行	node --import tsx/esm src/gateway/server.ts
OpenClaw 插件	通过 install-openclaw-plugin-v2.sh 安装
Hermes 插件	内置 memory_tencentdb_v2 Python 插件

⬆️ 从 0.x 升级说明

v1.0.0 与 0.x 是并行维护的两条版本线：

• 0.x（main 分支）：OpenClaw 嵌入式插件，适合轻量单机场景
• 1.x（feat/server 分支）：独立 Memory 服务，适合多 Agent / 多框架 / 服务化部署

两者核心记忆引擎相同（L0→L3 分层 + BM25/向量混合检索 + Mermaid 符号化短期记忆），数据格式兼容。

🐛 修复（v1.0.0-beta.2 → v1.0.0）

• Hermes 插件 install_hermes_tdai_gateway.sh 完善：支持 root 自动切换用户、旧路径自动迁移、幂等检测以跳过重复安装
• Gateway 配置优化：默认端口 8420，同步写入 /etc/profile.d/ 和 ~/.hermes/.env 两份环境变量
• SDK 文档补全：TypeScript / Python SDK README 与接入示例
• OpenClaw plugin.json 配置调整：移除 deprecated 字段，适配 OpenClaw 最新版本

📖 文档

• SDK 接入指南（TypeScript / Python 示例）。
• Gateway 独立部署文档。
• OpenClaw / Hermes 插件安装说明。
• Docker 部署与配置参考。

---

Full Changelog: https://github.com/Tencent/TencentDB-Agent-Memory/commits/feat/server

v1.0.0-beta.1

[1.0.0-beta.1] - 2026-05-29

🚀 全新架构：独立 Memory 服务

v1.0.0-beta.1 是 TencentDB Agent Memory 的全新里程碑版本，从 OpenClaw 嵌入式插件演进为独立可部署的 Memory 服务。

核心变化：

• 独立部署：不再依赖 OpenClaw 宿主，支持 Docker / Node.js 直接部署
• HTTP v2 API：完整的 RESTful 接口，任何语言/框架的 Agent 都可通过 HTTP 接入
• 多框架适配：同时支持 OpenClaw 插件模式 + Hermes 插件模式 + 独立服务模式
• 官方 SDK：提供 TypeScript SDK 与 Python SDK

✨ 新功能

v2 REST API（Gateway）

• L0 Conversation：add / query / search / delete
• L1 Atomic：update / query / search / delete
• L2 Scenario：ls / read / write / rm
• L3 Core（Persona）：read / write
• 所有路由前缀 /v2/，认证方式 Authorization: Bearer + x-tdai-service-id

Standalone 本地模式

• 零外部依赖：仅需 LLM API Key 即可运行
• 默认 SQLite + BM25 存储，开箱即用
• 支持 Docker 一键部署（agentmemory/hermes-memory:1.0.0-beta / agentmemory/openclaw-memory:1.0.0-beta）

SDK

• TypeScript SDK（@tencentdb-agent-memory/memory-sdk-ts）：完整覆盖 L0–L3 全部接口
• Python SDK（tencentdb-agent-memory-sdk-python）：同步 + 异步双客户端

Pipeline 服务化

• PipelineWorker：异步消费 L1 提取 / L2 场景生成 / L3 画像更新
• TimerScanner：定时扫描 idle session 触发 pipeline
• StorePool：多实例存储池管理
• Redis HA 配置支持（service 模式）

可观测性

• OpenTelemetry trace/metric/log 集成
• Langfuse span processor
• ClickHouse + Kafka 可选上报

📦 部署方式

方式	说明
Docker 容器	docker pull agentmemory/hermes-memory:1.0.0-beta
源码直接运行	node --import tsx/esm src/gateway/server.ts
OpenClaw 插件	通过 install-openclaw-plugin-v2.sh 安装
Hermes 插件	内置 memory_tencentdb_v2 Python 插件

⬆️ 从 0.x 升级说明

v1.0.0-beta.1 与 0.x 是并行维护的两条版本线：

• 0.x（main 分支）：OpenClaw 嵌入式插件，适合轻量单机场景
• 1.x（feat/server 分支）：独立 Memory 服务，适合多 Agent / 多框架 / 服务化部署

两者核心记忆引擎相同（L0→L3 分层 + BM25/向量混合检索 + Mermaid 符号化短期记忆），数据格式兼容。

v0.3.6

[0.3.6] - 2026-05-28

🚀 新功能

• Recall 上下文预算控制 (#71 / #70)：新增 recall.maxCharsPerMemory 与 recall.maxTotalRecallChars 配置，按分数顺序裁剪超长条目并丢弃溢出部分，避免长会话因记忆膨胀挤占上下文。
• L1 / L2 / L3 提示词按用户输入语言自适应 (#38)：l1-extraction、l1-dedup、scene-extraction、persona-generation 四个 prompt 的自由文本字段现在跟随用户消息语言书写，无需配置 locale。
• Embedding sendDimensions 可选关闭：新增 embedding.sendDimensions 配置项，设为 false 时省略请求体中的 dimensions 字段，可对接 BGE-M3 等固定维度模型。
• Gateway 可选 Bearer 鉴权 + CORS 白名单：新增 server.apiKey / TDAI_GATEWAY_API_KEY 与 server.corsOrigins / TDAI_CORS_ORIGINS，启用后非 /health 路由需携带 Bearer token，constant-time 比较防时序攻击。Hermes Python 客户端同步支持 MEMORY_TENCENTDB_GATEWAY_API_KEY。
• Offload collect 模式：新增 offload.mode: "collect"，仅执行数据采集而不触发 L3 压缩，适用于纯数据积累或调试场景。

🐛 修复

• L2 LLM 失败导致 scene_blocks/ 被清空 (#88)：LLM 抛错时自动从最新备份恢复 scene_blocks/，fail-soft 设计。
• 场景文件名含空格导致 Persona Scene Navigation 引用失效：新增 filename-normalizer.ts，在 SceneExtractor.extract 中自动归一化文件名。
• api.runtime.state 为 undefined 导致注册崩溃 (#78 / #85 / #79)：加可选链 + fallback，支持 runtimeState.resolveStateDir() → OPENCLAW_STATE_DIR → ~/.openclaw 三级降级。
• contextEngine slot ID 与插件名不一致：改为 memory-tencentdb，避免 openclaw doctor --fix 重置 slot。
• L1.5 settle 永不返回导致 L2 卡死：增加 60s 超时，未配置 Context Engine slot 时自动 force-settle。
• Standalone 文本任务仍暴露工具 (#58 / #59)：enableTools=false 时彻底不传工具列表。
• L2 cold-start skip 误更新 l2LastRunTime：仅在确实运行过时更新时间戳。
• sanitizeText 误删 emoji / CJK / Math Bold 等非 BMP 字符 (#30 / #31)：正则加 u flag，只匹配孤立 surrogate。
• Emergency 截断在 MIN_KEEP 拒绝下死锁：新增 _emergencyTruncateOversized，兜底强制删除并配对清理。
• 多轮 aggressive compression 累计耗时：由 6 轮全量 tiktoken 改为单趟精确切点，615 条消息 84s→14s。
• FP-HEAD-DELETE 误删新消息：改用 FP-BOUNDARY-DELETE + BOUNDARY-INCR-SKIP，重放场景 38s→122ms。
• 首次 assemble 慢：增加 fast-token-estimate 前置短路，29s→1.4s。
• Token 计算精度：details 加入 INTERNAL_KEYS；l3TiktokenEncoding 默认改为 cl100k_base。
• Dockerfile.hermes 生成的 config.yaml 缺 api_key (#77 / #81)：同步写入 model.api_key。
• 安装脚本多处问题 (#18 / #19 / #20 / #54 / #55)：支持 HERMES_AGENT_DIR 覆盖、root 不再递归 su、systemd 环境用绝对路径 node。
• Cleaner 安全加固：拒绝无效 cutoff、expired/total > 80% 阻止删除、最小保留护栏。

✨ 改进

• l3TiktokenEncoding 默认改为 cl100k_base，匹配主流国产/开源模型分词器。
• Offload 日志降级：AGGRESSIVE / EMERGENCY 等降到 debug，仅超 10s 输出 WARN。
• Docker 文档补充 cd docker/opensource 前置步骤；新增 question/consultation issue 模板。

⚠️ 配置项变化（向后兼容）

Key	默认值	说明
recall.maxCharsPerMemory	0	0/未设置 = 不裁剪
recall.maxTotalRecallChars	0	0/未设置 = 不裁剪
embedding.sendDimensions	true	false 时不携带 dimensions，适配 BGE-M3 等
l3TiktokenEncoding	cl100k_base（原 o200k_base）	仅在显式依赖 o200k_base 时需手动覆盖

---

Full Changelog: v0.3.5...v0.3.6

v0.3.5

[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 场景提取结果，体感更及时。

v0.3.4

[0.3.4] - 2026-05-12

🚀 新功能

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

✨ 改进

• 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 调用链问题
• Offload 日志去掉 Backend 前缀，默认超时为 120s

🐛 修复

• 兼容 OpenClaw v2026.4.7 以下版本 L1 抽取空输出：旧宿主不支持 systemPromptOverride，通过 extraSystemPrompt 回退注入系统提示
• TCVDB hybrid 召回冗余双重 HTTP 调用：新增 nativeHybridSearch 短路，单次调用完成 dense + sparse + RRF，recall 耗时减半（~50-120ms）
• L2 parser 对齐 Go 后端：增加 mermaid fallback，修复 first{...last} JSON 提取逻辑

🔧 兼容性适配

• OC 2026.4.23 Zod schema 兼容 patch 脚本（scripts/bugfix-20260423/）：一键修复 allowConversationAccess 被 .strict() 拒绝的问题，含轻量版脚本、全自动脚本、手动 SOP 文档

v0.3.3

[0.3.3] - 2026-05-08

🚀 新功能

• 短期记忆压缩（Context Offload）：新增 Offload 模块，支持长对话场景下的上下文压缩与记忆卸载
• 架构重构：Core + 多框架适配：重构为 TdaiCore 宿主无关核心层 + 适配器模式，解耦 OpenClaw 框架依赖；新增 HostAdapter / LLMRunner 抽象接口
• Hermes Gateway 适配：新增 Hermes Gateway 适配器（memory_tencentdb Hermes Plugin），支持通过 Hermes 框架独立运行；Gateway 零配置自动发现
• Offload 自动 patch：Offload 启动时自动应用 after_tool_call patch，patch 失败时自动禁用 offload
• L0 捕获过滤：排除 offload 注入的 MMD 上下文块，避免将压缩中间产物误存为记忆
• Recall 注入优化（Cache 友好）：L1 召回从 appendSystemContext 移到 prependContext，避免每轮系统提示词变化导致 prompt cache bust
• 分场景 Embedding 超时：新增 embedding.recallTimeoutMs / embedding.captureTimeoutMs，recall 超时自动降级为纯关键词搜索
• Gateway 自愈：Hermes 插件新增 watchdog + lazy probe 机制，Gateway 异常时自动恢复
• 运维管理工具：新增 memory-tencentdb-ctl 命令行管理工具，支持 standalone 与 hermes 两种运行模式
• 兼容 OpenClaw v2026.4.23+ hook 权限策略：新增 ensurePluginHookPolicy() 自动检测并补全 allowConversationAccess 配置
• Docker 支持：新增 Hermes + Memory 一体化 Docker 镜像，一行命令启动带记忆能力的 Hermes Agent

✨ 改进

• 数据目录与安装目录统一整合至 ~/.memory-tencentdb/
• 引入 $HERMES_HOME 环境变量，移除硬编码 ~/.hermes 路径
• CleanContextRunner 通过 systemPromptOverride 替换默认系统提示词，每次 L1/L2/L3 调用节省 ~4500 input tokens
• L2 / L3 prompt 拆分为 systemPrompt + userPrompt，角色划分更清晰
• Pipeline 默认参数调整：l1IdleTimeoutSeconds 60→600s，l2MinIntervalSeconds 300→900s，l2MaxIntervalSeconds 1800→3600s
• 运维脚本保留在 tarball 中但不再注册为 bin 命令，减少全局命令污染
• init/destroy 生命周期日志降级为 debug 级别
• 新增 tsdown 构建配置生成 dist/index.mjs，满足新版 OpenClaw 安装校验
• 声明 activation.onStartup 确保 gateway 启动时加载插件
• 声明 contracts.tools 注册工具名，满足 tool registration contract 要求

🐛 修复

• 修复 ensureSchedulerStarted 并发调用下的竞态问题
• 修复 /session/end 错误销毁全局 scheduler（改为按 session_key 作用域）
• 修复关闭 store 时未等待后台 fire-and-forget 任务完成的问题
• 修复 disable_offload 未正确删除 slots.contextEngine 配置的问题
• 修复 slot 占用检测逻辑：仅在 ok=false 时拒绝，API 异常不再误判为冲突
• 修复 aggressive/emergency 压缩在用户消息位于队首时卡死的问题
• 修复消息被大量 offload 后压缩停滞的问题
• 修复 pullProfilesToLocal 并发竞争导致 ENOTEMPTY 错误
• 修复 originalUserMessageCount 数据链路断裂导致 L0 recorder 无法定位被污染的 user message
• 修复 RecallResult 类型定义缺少 prependContext 字段
• 修复 set -e 环境下 ((VAR++)) 在 VAR=0 时导致脚本退出的问题
• 修复 Hermes 退出时未终止 Gateway 子进程的问题
• 加固 hook-policy 版本决策逻辑，非标准版本一律跳过，避免误写配置

♻️ 重构

• 统一 patch 检测逻辑：始终委托给 patch 脚本并通过退出码判定结果
• TdaiCore 提供统一 API：handleBeforeRecall() / handleTurnCommitted() / searchMemories()
• 数据目录所有权从插件移至 Gateway 层管理

v0.2.2

[0.2.2] - 2026-04-17

🚀 新功能

• 新增腾讯云向量数据库（TCVDB）存储后端，支持向量 + BM25 混合召回
• 支持 SQLite ↔ TCVDB 索引同步，L2 场景 / L3 画像本地缓存与向量数据库双向同步
• 新增本地 BM25 关键字检索，替代外部 HTTP sidecar，消除外部依赖
• TCVDB 新增 HTTPS 连接支持，可通过 caPemPath 配置自定义 CA 证书
• tdai_memory_search + tdai_conversation_search 增加每轮合计最多 3 次调用限制

✨ 改进

• TCVDB L0/L1 向量索引默认使用 DISK_FLAT，不支持时自动回退到 HNSW
• 默认服务端 embedding 模型调整为 bge-large-zh
• TCVDB 所有读接口统一启用强一致性读，消除 read-after-write 不一致
• 新增插件配置项：storeBackend、tcvdb、bm25、embedding.timeoutMs
• 插件注册阶段日志从 INFO 降级为 DEBUG，减少无关输出

🐛 修复

• 修复因未声明 undici 依赖导致 TCVDB 客户端加载失败
• 修复 L3 persona sync 因未拉取远端 baseline 导致版本冲突跳过写入
• 修复 memories_since_last_persona 被 L0 和 L1 双重计数导致触发阈值膨胀
• 修复 L3 启动时重复拉取 profile
• 修复 L2 场景合并（MERGE）无法删除旧文件，改用 [DELETED] 标记软删除
• 修复 L2 抽取产生孤立 BATCH/ARCHIVE 文件，统一 maxScenes 上限为 15
• 处理 createCollection 并发竞态（错误码 15202）
• 过滤 skill wrapper 噪声标记（¥¥[...]¥¥）
• 移除 CheckpointManager 中已废弃方法

♻️ 重构

• Pipeline checkpoint 游标语义从 timestamp 改为 update_at
• Runner 改用 api.runtime.agent.runEmbeddedPiAgent，避免跨环境导入失败

v0.1.4

[0.1.4] - 2026-04-10

🚀 Features

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