OpenClaw 安装插件后还要单独起 Gateway 吗？

OpenClaw 路径下插件会随 gateway restart 加载，一般无需手动起独立进程。Hermes 或自研 Agent 走 Python/Node SDK 时，才需要监听 8420 端口的 Memory Gateway。

TencentDB Agent Memory 使用教程（2026 最新版）| AI Agent 分层记忆

Q: TencentDB Agent Memory 必须接腾讯云吗？

不必。OpenClaw 插件默认使用本地 SQLite + sqlite-vec，零外部 API 即可运行。只有团队级托管、向量库扩容或合规上云时，才需要开通腾讯云 Memory 实例并通过 Python SDK 接入。

Q: 和 LangChain / Mem0 等向量记忆有什么区别？

TencentDB Agent Memory 强调分层（L0–L3）与符号化短期压缩（Mermaid 画布 + refs 卸载），不是把所有历史切片平铺进向量库。召回时先读 Persona/场景，再按需下钻原子事实与原文。

Q: 在 Mac 上跑有什么版本要求？

npm 插件要求 Node.js ≥ 22.16；Docker 方案需本机安装 Docker Desktop。Apple Silicon Mac 可原生运行 Gateway，适合与本地 MLX/Ollama 推理同机部署。

最后更新于 2026 年 8 月 5 日。安装命令与配置字段核实自 TencentDB-Agent-Memory 官方仓库、npm 插件文档与腾讯云 Memory 接入准备。

如果你用 OpenClaw、Hermes 或自研框架搭过 AI Agent，大概率遇到过这类崩溃：第三轮对话它忘了你指定的 Swift 代码风格；跑完 20 步工具调用后上下文爆掉，开始胡编路径；换个会话又要重新解释项目背景。

传统做法是「把历史全塞进向量库」或「暴力摘要」。腾讯在 2026 年开源的 TencentDB Agent Memory（MIT）换了一条路：符号化短期记忆 + 四层长期记忆（L0–L3），默认本地 SQLite + sqlite-vec，零云依赖即可跑通。本文面向 iOS / Flutter / AI 开发者，按「先懂原理 → 再装插件 → 再决定本地还是上云」的顺序写，并说明何时该把 Gateway 放到 云端 Mac 上 7×24 挂着。

引言：Agent 为什么总「失忆」

长程 Agent 的失败往往不是模型不够聪明，而是上下文管理失败。一次 Wide Search 或 SWE-bench 式任务里，工具返回的 JSON、网页正文、编译日志轻松堆到几十万 token。你若把这些原文全留在窗口里，费用和延迟都会失控；若粗暴删掉，Agent 又会在下一步重复搜索或改错文件。

TencentDB Agent Memory 要解决的正是这对矛盾：让 Agent 记得该记的，同时把证据链完整保留在可下钻的底层。官方在 OpenClaw 插件场景的公开 benchmark 里，短期记忆任务最高可节省约 61% Token，PersonaMem 长期记忆准确率从 48% 提升到 76%——数字会随模型与任务变化，但方向很明确：分层 + 卸载比平铺向量更省、也更稳。

对 Kvmkit 读者来说，这套系统通常出现在两类工作流：① 在 Mac 上给 Cursor / Claude Code 接 OpenClaw 插件做项目级记忆；② Windows 写 Flutter，云端 Mac 跑 Gateway + 本地 MLX 推理，把「记忆服务」和「Xcode 构建」放在同一台稳定节点。

核心概念：分层记忆与符号化短期压缩

项目拒绝「所有记忆切片平铺成向量」的设计。长期侧是语义金字塔，短期侧是 Mermaid 任务画布——两者都支持渐进式披露：上下文里只放高层结构，需要考证时再按索引下钻。

长期记忆四层（L0 → L3）

L0 Conversation：原始对话与工具轨迹，作为不可丢失的证据底稿；
L1 Atom：从对话抽出的结构化事实（日期、偏好、技术栈）；
L2 Scenario：把多条 Atom 归纳成场景块（例如「iOS CI 签名流程」）；
L3 Persona：跨场景的用户画像，写入可读的 persona.md，供下一轮对话前召回。

召回时默认先读 Persona / Scenario，再按需检索 Atom 或 L0 原文——类似人先想起「这个同事喜欢用 SwiftUI」，再翻聊天记录核对细节。

短期记忆：Mermaid 卸载

工具日志卸载到 refs/*.md，上下文只保留带 node_id 的 Mermaid 图谱。Agent 推理看轻量符号；若发现某节点可疑，用 node_id grep 回完整原文，实现100% 可追溯而不必把日志全文塞回窗口。

TencentDB Agent Memory 四层长期记忆与符号化短期压缩架构示意图 — L0–L3 语义金字塔 + Mermaid 短期画布：高层进上下文，底层可按 node_id 下钻

若你同时在搭 MCP 工具链，可把记忆插件与 GitHub MCP Server 全平台部署放在同一套 OpenClaw 配置里：工具负责「能做什么」，Memory 负责「做过什么、用户是谁」。

实操：OpenClaw 插件与 Gateway 部署

最快路径是 OpenClaw 插件（要求 Node.js ≥ 22.16）。以下命令在 macOS / Linux 终端执行；Windows 建议 WSL2 或直接把 Gateway 放到云端 Mac。

方案 A：OpenClaw 零配置（推荐入门）

# 安装插件
openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
openclaw gateway restart

在 ~/.openclaw/openclaw.json 启用：

{
  "memory-tencentdb": {
    "enabled": true
  }
}

默认后端为本地 SQLite，插件会自动完成对话录制、记忆提取、场景归纳、画像生成与下轮召回。升级请用 openclaw plugins update @tencentdb-agent-memory/memory-tencentdb，避免语义化版本范围导致插件被禁用。

启用短期压缩（≥ 0.3.4）

在配置中打开 offload，并注册 contextEngine slot：

{
  "memory-tencentdb": {
    "config": {
      "offload": { "enabled": true }
    }
  },
  "plugins": {
    "slots": {
      "contextEngine": "memory-tencentdb"
    }
  }
}

按仓库说明执行 scripts/openclaw-after-tool-call-messages.patch.sh（OpenClaw 升级后建议重跑）。这样工具调用结果才能被正确卸载与回溯——这也是很多「装了插件但没降 Token」的根因。

方案 B：Hermes Docker 一体化

若你用 Hermes Agent，可一条命令起带记忆的容器（Gateway 监听 8420）：

cd TencentDB-Agent-Memory/docker/opensource
docker build -f Dockerfile.hermes -t hermes-memory .
docker run -d --name hermes-memory -p 8420:8420 \
  -e MODEL_API_KEY="your-api-key" \
  -v hermes_data:/opt/data hermes-memory
curl http://localhost:8420/health

健康检查返回 {"status":"ok"} 或 degraded 即可继续。镜像内置 DeepSeek-V3.2 默认接入地址，若用该模型可只传 API Key。

方案 C：自研 Agent + Python SDK（上云）

团队要把记忆放到腾讯云托管实例时，在控制台新建 Memory 后安装 SDK：

pip install tencentdb-agent-memory-sdk

用异步客户端写入会话、检索原子记忆（字段以控制台为准）。这条路径适合已有 Python 编排、需要多 Agent 共享团队记忆库的场景，但个人试用不必走云。

验收清单

连续 3 轮对话后，检查是否生成 persona.md 或场景文件；
开启 offload 后，对比同一 SWE 任务前后 Token 曲线；
故意让 Agent 引用旧工具结果，确认能通过 node_id 找回 refs/ 原文；
若出现 Tool Calls 死循环，结合 Kimi K3 Tool Calls 止损教程排查消息链，而不是怪记忆插件本身。

与云端 Mac / Apple Silicon 的关联

Memory Gateway 是常驻服务：要监听端口、读写本地 SQLite、在后台跑提取与召回。笔记本合盖休眠、Windows 更新重启，都会让 Agent「突然失忆」。对 iOS 团队更现实的架构是：

本地：Cursor / Xcode 写代码；
云端 Mac mini：OpenClaw Gateway + TencentDB Memory + Ollama/MLX 推理同机；
远程：SSH 或屏幕共享调试，数据卷持久化在云端磁盘。

Apple Silicon 的优势在于统一内存与原生 Unix：Node 22、Docker Desktop、Homebrew 安装路径清晰，长时间跑 Gateway 功耗远低于台式独显。M4 Mac mini 待机约数瓦，适合作为「团队共享记忆节点」。若你已在看本地显卡跑小模型的方案，可以把大模型推理放 Windows，而把需要 7×24 在线的记忆与 macOS 工具链迁到 Kvmkit 云端 Mac——避免家用机睡眠中断 Agent 会话。

成本、性能与风险对比

方案	月成本粗算	适合场景	主要风险
本地 SQLite 插件	¥0（仅 LLM API）	个人 OpenClaw 试用	本机休眠即断连；备份需自己做
自架 Docker Gateway	电费 + API	小团队内网 Hermes	需维护镜像升级与磁盘容量
腾讯云 Memory 托管	按实例规格	多 Agent 团队共享	合规与数据驻留要求
Kvmkit 云端 Mac	按小时 / 包月	Gateway + Xcode + MLX 同机	需规划网络与密钥管理

决策上可以简单记：Prototype 阶段用本地 SQLite 零成本验证；一旦记忆数据变成团队资产，就迁到常驻云端 Mac 或腾讯云实例。别在笔记本上跑两周生产 Agent 再迁移——L0 对话与 refs 的迁移成本会被低估。

常见问题

TencentDB Agent Memory 必须接腾讯云吗？

不必。OpenClaw 插件默认本地 SQLite，无需外部 Memory API。只有团队托管、向量扩容或合规上云时才需要控制台实例 + Python SDK。

和 LangChain / Mem0 等向量记忆有什么区别？

本项目强调 L0–L3 分层与 Mermaid 短期卸载，不是把所有历史平铺进向量库。召回路径是 Persona → Scenario → Atom → 原文，可审计、可下钻。

OpenClaw 安装后还要单独起 Gateway 吗？

OpenClaw 路径下随 gateway restart 即可。Hermes 或自研 Python Agent 需确保 8420 端口 Gateway 健康，可 Docker 或 npx tsx 手动启动。

在 Mac 上跑有什么版本要求？

npm 插件需 Node.js ≥ 22.16；短期压缩需插件 ≥ 0.3.4。Apple Silicon 可原生运行，适合与 MLX/Ollama 同机部署。

总结

TencentDB Agent Memory 用 L0–L3 分层 + Mermaid 卸载解决长程 Agent 的上下文膨胀，默认本地可跑。
OpenClaw 插件是最快上手路径；Hermes 用 Docker；企业自研走 Python SDK 上云。
需要 7×24 记忆与 macOS 工具链同机 时，云端 Mac mini 比家用笔记本更稳。

Agent 记忆不是「多塞几条向量」就能搞定。先把分层模型跑通，再决定数据留在本机 SQLite 还是迁到团队节点——这一步做对了，后面接 iOS CI、MCP 工具或更大模型都会轻松很多。