TencentCloud/TencentDB-Agent-Memory 来源：https://github.com/TencentCloud/TencentDB-Agent-Memory ### 智能体记忆，人类创新。 npm (https://www.npmjs.com/package/@tencentdb-agent-memory/memory-tencentdb) 许可协议: MIT Node (https://nodejs.org/) OpenClaw (https://github.com/openclaw/openclaw) Hermes (https://hermes-agent.nousresearch.com/docs/) Discord (https://discord.gg/kDtHb5RW2) 亮点 · 概述 · 核心技术 · 功能 · 快速开始 English · 简体中文 — ## ✨ 亮点 > TencentDB Agent Memory = 符号化短期记忆 + 分层长期记忆。 > > - 符号化短期记忆 将繁重的工具日志卸载并浓缩为紧凑的 Mermaid 符号，减少 Token 消耗并提升任务成功率。 > - 分层长期记忆 将碎片化对话提炼为结构化的人物画像和场景，而非扁平的向量堆叠。与 OpenClaw 集成后，Token 消耗最多降低 61.38%，通过率相对提高 51.52%，人物画像记忆准确率从 48% 提升至 76%。 | 记忆能力 | 基准测试 | OpenClaw 成功率 | 使用插件 | 相对变化 | OpenClaw Token 数 | 使用插件 Token 数 | 相对变化 | | :— | :— | :—: | :—: | :—: | :—: | :—: | :—: | | 短期 | WideSearch | 33% | 50% | +51.52% | 221.31M | 85.64M | -61.38% | | 短期 | SWE-bench | 58.4% | 64.2% | +9.93% | 3474.1M | 2375.4M | -33.09% | | 短期 | AA-LCR | 44.0% | 47.5% | +7.95% | 112.0M | 77.3M | -30.98% | | 长期 | PersonaMem | 48% | 76% | +59% | — | — | — | > 这些结果是在连续长周期会话中测量的，而非孤立轮次。例如，SWE-bench 每轮会话连续运行 50 个任务，以模拟真实长期智能体的上下文累积压力。 — ## 概述 记忆不是将所有内容都堆积在 AI 中——而是让人不必重复解释。 实践中，我们不断向智能体重复解释相同的 SOP、项目背景、工具约定和输出格式。这些信息不应需要重复，也不应不加区分地全部塞入上下文。TencentDB Agent Memory 帮助智能体学习你的工作流程、保留任务上下文并复用过往经验。我们摒弃了暴力历史累积和不可逆的有损摘要。相反，我们将记忆设计为分层系统：符号记忆 用于处理任务内的信息过载，记忆分层 用于跨会话的经验复用。 > 让智能体记住该记住的，让人专注于判断、创造和真正重要的工作。 — ## 核心技术：摒弃扁平存储，拥抱分层与符号化 我们的架构基于两大支柱：记忆分层 和 符号记忆。两者共同确保智能体不仅仅“记住更多”，而是“推理得更好”。 ### 1. 记忆分层：异构存储的渐进式揭示 传统记忆系统将数据切碎后倒入扁平向量存储中。回忆退化为在碎片化片段中盲目搜索，缺乏宏观指导。无论是长期知识、短期任务，还是未来的技能能力，记忆都不应是扁平的——其形成和回忆都必须是分层的。 TencentDB Agent Memory 采用 分层 作为统一架构范式： * 短期上下文分层。 底层归档原始工具输出（refs/*.md）；中间层提取步骤级摘要（jsonl）；顶层将状态浓缩为轻量级 Mermaid 画布。智能体只需关注上下文中的顶层结构，在发生错误时通过 node_id 下钻至底层。 * 长期个性化分层。 取代扁平日志，我们构建语义金字塔：L0 对话（原始对话）→ L1 原子（原子事实）→ L2 场景（场景块）→ L3 画像（用户画像）。画像层承载日常偏好；仅在需要细节时系统才下钻至原子层。 * 技能生成分层。 分层也适用于动作。中间层从底层执行轨迹（对话）中推导出通用解决方案模式（场景），顶层提炼出可复用的技能或标准 SOP（画像）。 异构存储与渐进式揭示。 双存储策略支撑此架构。底层（事实、日志、轨迹）持久化到数据库中以实现鲁棒的全文本检索；顶层（画像、场景、画布）存储为人类可读的 Markdown 文件，兼具高信息密度和白盒可检查性。 底层保存证据；顶层保存结构。 全程可追溯与无损恢复。 压缩通常牺牲可追溯性。TencentDB Agent Memory 通过维护从高层抽象到真实证据的确定性路径来避免不可逆压缩。无论是卸载的错误日志还是提炼的用户偏好，系统都保证完整的下钻路径：“顶层符号（画像/画布）→ 中层索引（场景/jsonl）→ 底层原始文本（L0 对话/refs）”。 ### 2. 符号记忆：最小符号中的最大语义（Mermaid 画布） 在长任务中，最大的 Token 消耗者是冗长的中间日志（搜索结果、代码、错误轨迹）。为此，我们结合 上下文卸载 与 符号记忆： * Mermaid 符号图。 我们用高密度 Mermaid 语法编码任务状态转换——精确到 LLM 可解析，简洁到人类可阅读。 * 历史卸载。 完整的工具日志被卸载到外部文件；上下文中只保留轻量级 Mermaid 任务图。 * node_id 追踪。 智能体基于符号图推演；若要验证某个细节，可通过 node_id 进行 grep 搜索后立即获取完整原始文本——既降低 Token 成本又保留全程可追溯性。 mermaid graph LR Log["Verbose Logs(hundreds of thousands of tokens)"] -->|"1. Offload full text"| FS[("External FS(refs/*.md)")] Log -->|"2. Extract relations"| MMD["Mermaid Canvas(with node_id)"] MMD -->|"3. Light injection"| Agent(("Agent Context(a few hundred tokens)")) Agent -. "4. Recall via node_id" .-> FS style Log fill:#f1f5f9,stroke:#94a3b8,stroke-dasharray: 5 5,color:#475569 style FS fill:#f8fafc,stroke:#cbd5e1,stroke-width:2px,color:#334155 style MMD fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a style Agent fill:#fffbeb,stroke:#f59e0b,stroke-width:2px,color:#92400e — ## 快速开始 ## 🎬 演示 OpenClaw × Agent Memory Hermes × Agent Memory — ### 1. OpenClaw ### 1.1 安装插件 bash openclaw plugins install @tencentdb-agent-memory/memory-tencentdb openclaw gateway restart > 请使用原生 OpenClaw 命令升级插件。通过此方式可避免因语义版本范围导致插件被禁用。 > bash > openclaw plugins update @tencentdb-agent-memory/memory-tencentdb > ### 1.2 零配置启用 默认使用本地 SQLite + sqlite-vec 后端。 jsonc // ~/.openclaw/openclaw.json { "memory-tencentdb": { "enabled": true } } 启用后，TencentDB Agent Memory 会自动处理对话捕获、记忆提取、场景聚合、画像生成以及下一次轮次前的回忆。 ### 1.3 启用短期压缩（可选，需版本 ≥ 0.3.4） jsonc { "memory-tencentdb": { "config": { "offload": { "enabled": true } } } } #### 步骤 1 — 在插件配置中注册槽位 添加 slots 字段以让 OpenClaw 将上下文卸载请求路由到此插件： jsonc { "plugins": { "slots": { "contextEngine": "memory-tencentdb" } } } #### 步骤 2 — 应用运行时补丁 为获得最佳效果，请运行以下补丁脚本。它会挂载 after-tool-call 消息，以便正确卸载和恢复： bash bash scripts/openclaw-after-tool-call-messages.patch.sh > 💡 该补丁仅需在每个 OpenClaw 安装中应用一次。升级 OpenClaw 后，重新运行脚本即可重新应用。 ### 2. Hermes 除 OpenClaw 外，此插件也支持 Hermes (https://github.com/NousResearch/hermes-agent) 智能体。根据部署场景选择安装路径： | 你想要 … | 使用 | |—|—| | 一键启动带记忆的 Hermes（全新部署） | 2.A Docker（如下） | | 为现有 Hermes 安装添加记忆 | 2.B 挂接到现有 Hermes（下一节） | #### 2.A Docker（全新部署，需版本 ≥ 0.3.4） Docker 镜像捆绑了 hermes-agent 和 memory_tencentdb 提供者。网关监听在 :8420： bash # ============ 配置参数 ============ # MODEL_API_KEY LLM API 密钥（必需）— 替换为你自己的凭据 # MODEL_BASE_URL LLM 端点，默认为腾讯云大模型知识引擎（LKE） # MODEL_NAME 模型名称，默认为 DeepSeek-V3.2 # MODEL_PROVIDER 提供者类型："custom" 适用于任何 OpenAI-compatible 端点 MODEL_API_KEY="your-api-key" MODEL_BASE_URL="https://api.lkeap.cloud.tencent.com/v1" MODEL_NAME="deepseek-v3.2" MODEL_PROVIDER="custom" # ============ docker run 参数 ============ # -d 以后台模式运行容器 # --name hermes-memory 容器名称，后续用于 docker exec / logs / stop # --restart unless-stopped 崩溃或主机重启后自动重启 # -p 8420:8420 主机端口 ↔ 容器端口（Hermes 网关） # -e MODEL_* 将上述配置参数作为环境变量注入 # -v hermes_data:/opt/data 将记忆数据持久化到命名卷（重启后保留） # 进入 Docker 构建目录（已克隆仓库并位于仓库根目录） cd docker/opensource # 构建 docker build -f Dockerfile.hermes -t hermes-memory . # 运行 docker run -d \ --name hermes-memory \ --restart unless-stopped \ -p 8420:8420 \ -e MODEL_API_KEY="your-api-key" \ -e MODEL_BASE_URL="https://api.lkeap.cloud.tencent.com/v1" \ -e MODEL_NAME="deepseek-v3.2" \ -e MODEL_PROVIDER="custom" \ -v hermes_data:/opt/data \ hermes-memory # 验证网关 curl http://localhost:8420/health # 进入 Hermes 交互式 shell docker exec -it hermes-memory hermes > 镜像默认搭载腾讯云 DeepSeek-V3.2。如果你使用此模型，可省略 MODEL_BASE_URL / MODEL_NAME / MODEL_PROVIDER，仅传入 MODEL_API_KEY。 #### 2.B 挂接到现有 Hermes（无需 Docker） 如果你已在主机上安装 hermes-agent，且只想添加记忆能力，无需 Docker 镜像。 1. 将插件包下载到统一目录： bash mkdir -p ~/.memory-tencentdb TEMP_DIR=$(mktemp -d) cd "$TEMP_DIR" npm init -y --silent npm install @tencentdb-agent-memory/memory-tencentdb@latest --omit=dev cp -r node_modules/@tencentdb-agent-memory/memory-tencentdb \ ~/.memory-tencentdb/tdai-memory-openclaw-plugin rm -rf "$TEMP_DIR" 2. 安装网关依赖： bash cd ~/.memory-tencentdb/tdai-memory-openclaw-plugin npm install --omit=dev npm install tsx 3. 链接到 Hermes 插件目录： bash rm -rf ~/.hermes/hermes-agent/plugins/memory/memory_tencentdb ln -sf ~/.memory-tencentdb/tdai-memory-openclaw-plugin/hermes-plugin/memory/memory_tencentdb \ ~/.hermes/hermes-agent/plugins/memory/memory_tencentdb > 目录必须命名为 memory_tencentdb（下划线）—— Hermes 使用此名称作为提供者键。memory-tencentdb（带连字符）仅为配置层面的别名，不能用作目录名。 4. 在 ~/.hermes/config.yaml 中声明提供者： yaml memory: provider: memory_tencentdb 5. 配置网关环境变量 编辑 ~/.hermes/.env，添加： bash MEMORY_TENCENTDB_GATEWAY_CMD="sh -c 'cd ~/.memory-tencentdb/tdai-memory-openclaw-plugin && exec npx tsx src/gateway/server.ts'" MEMORY_TENCENTDB_GATEWAY_HOST="127.0.0.1" MEMORY_TENCENTDB_GATEWAY_PORT="8420" 根据需要添加 LLM 凭据（网关实际读取 TDAI_LLM_* 变量）： bash TDAI_LLM_API_KEY="sk-your-api-key-here" TDAI_LLM_BASE_URL="https://api.openai.com/v1" TDAI_LLM_MODEL="gpt-4o" 或者使用位于 ~/.memory-tencentdb/memory-tdai/tdai-gateway.json 的网关配置文件： json { "llm": { "baseUrl": "https://your-api-endpoint/v1", "apiKey": "your-api-key", "model": "your-model-name" } } 6. 启动网关（选择以下两种方法之一）： - 对话时自动发现（推荐，零配置）：无需手动启动网关——只需开始与 Hermes 对话。提供者会在首次对话时自动检测 ~/.memory-tencentdb/tdai-memory-openclaw-plugin/src/gateway/server.ts 并通过 Popen() 启动。首次对话可能会有轻微延迟。 - 手动运行：提前启动独立网关进程： bash cd ~/.memory-tencentdb/tdai-memory-openclaw-plugin npx tsx src/gateway/server.ts 7. 验证： bash curl http://127.0.0.1:8420/health # 应返回 {"status":"ok"} 或 {"status":"degraded"} > 完整的提供者参考（环境变量、故障排查、LLM 工具模式、监督者行为）请见 hermes-plugin/memory/memory_tencentdb/README.md。在调整监督者 / 断路器默认值前请先阅读。 — ## 🔒 网关安全（可选） Hermes 网关监听在 :8420 上，暴露了捕获 / 搜索 / 回顾 HTTP 端点。两个可选开关可将其从“开放的本地 sidecar”转变为“已认证的网络服务”。 两者默认关闭，因此现有部署保持不变。 | 字段 | 环境变量 | 默认值 | 描述 | | :— | :— | :— | :— | | server.apiKey | TDAI_GATEWAY_API_KEY | (未设置) | 设置后，除 GET /health 外的所有路由都需要 Authorization: Bearer <key>；缺失或错误的 Token 会返回 HTTP 401。比较使用常量时间。 | | server.corsOrigins | TDAI_CORS_ORIGINS（逗号分隔） | [] | CORS 白名单。空列表不发送 Access-Control-Allow-* 头——浏览器将阻止所有跨域请求。仅本地开发时使用 ["*"]。 | 当 apiKey 未设置时，网关会在启动时打印 WARN。如果它绑定到非回环主机（例如 0.0.0.0）且没有 apiKey，则会发出更响亮的警告。 客户端使用 Bearer Token 调用受保护路由： bash curl -H "Authorization: Bearer $TDAI_GATEWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query":"...","session_key":"..."}' \ http://127.0.0.1:8420/recall GET /health 保持开放，无需 Token，以便编排器探测（docker healthcheck、kubectl liveness）继续工作。 ### Hermes 插件端 Hermes memory_tencentdb 插件是网关的客户端。要使其与启用了认证的网关通信，请设置： bash export MEMORY_TENCENTDB_GATEWAY_API_KEY="" 插件随后会在发送给网关的每个请求上附加 Authorization: Bearer <key>。如果变量未设置，插件不发送 auth 头——这与网关的旧默认行为一致，对于未选择启用 TDAI_GATEWAY_API_KEY 的网关也没问题。 注意：插件仅处理客户端部分。网关是否实际强制 Bearer 检查由网关端决定（TDAI_GATEWAY_API_KEY / server.apiKey）。请在两端配置相同的密钥——插件不会自动传播密钥，因为网关可能由 Docker、systemd 或其他不受插件控制的方式启动。 如果 MEMORY_TENCENTDB_GATEWAY_API_KEY 未设置，插件还会回退查看 TDAI_GATEWAY_API_KEY——当两个进程共享一个 env 文件时很方便。