🏷️ AI工程 · Agent Memory · 教程

为什么你的AI Agent总是"失忆"

用过AI Agent的人都有这种体验：刚说完的事转头就忘，每次都要从头解释项目背景、工具习惯、输出格式。不是模型能力不够，是它根本没地方存。

Token 上下文不是记忆。 把一切塞进上下文窗口，成本爆炸不说，长任务里几十万 Token 的工具日志会把真正有用的信息挤出去。

TencentDB Agent Memory 解决的就是这个问题——不是存更多，而是存得更聪明。

L0-L3：四层记忆金字塔

传统向量记忆把所有东西切片平铺，召回像在一堆便利贴里翻找。TencentDB 的设计完全不同：

L0 — Conversation（原始对话）：完整的对话记录，底层证据。

L1 — Atom（结构化事实）：从对话中提取独立的事实单元。“用户偏好 card-title 主题”、“DeepSeek API key 在 .env 里”——每条都是可检索的原子。

L2 — Scenario（场景块）：相关 Atom 聚合成场景。"公众号文章发布流程"包含主题选择、配图生成、草稿推送等多个 L1 事实。

L3 — Persona（用户画像）：最高层，长期稳定的用户特征。技术背景、效率偏好、署名规则——这些不需要每次重新解释。

平时靠 L3 把握整体偏好，需要细节时下钻到 L1。低层保留证据，高层保留结构。没有任何信息是"不可逆"的黑盒压缩。

符号化记忆：用 Mermaid 解决 Token 爆炸

这是 TencentDB 最独特的设计。长任务里最占 Token 的不是对话，是工具调用的海量日志。

TencentDB 的做法：

• 完整日志卸载到外部文件（refs/*.md）

• 中层提取步骤摘要（JSONL）

• 高层浓缩为Mermaid 符号图谱——几百 Token 就能表达整个任务的拓扑结构

• 需要细节时，按 node_id 直接 grep 原文

这一设计在实际 Benchmark 中的效果：

指标	原生	+TencentDB	提升
Token 消耗（WideSearch）	221M	85M	-61%
任务成功率	33%	50%	+52%
PersonaMem 准确率	48%	76%	+59%
SWE-bench 通过率	58.4%	64.2%	+10%

Hermes 部署：五步走

Step 1：安装插件

hermes plugins install memory_tencentdbhermes plugins enable memory_tencentdb

Step 2：配置环境变量

在 ~/Library/LaunchAgents/ai.hermes.gateway.plist 的 EnvironmentVariables 中添加：

<key>MEMORY_TENCENTDB_GATEWAY_CMD</key><string>sh -c 'cd /path/to/plugin && exec node dist/src/gateway/server.js'</string><key>MEMORY_TENCENTDB_LLM_API_KEY</key><string>sk-your-api-key</string><key>MEMORY_TENCENTDB_LLM_BASE_URL</key><string>https://api.deepseek.com/v1</string><key>MEMORY_TENCENTDB_LLM_MODEL</key><string>deepseek-chat</string>

Gateway 默认监听 127.0.0.1:8420，LLM 配置支持任何 OpenAI 兼容 API（DeepSeek 完全可用）。

Step 3：重启 Gateway

launchctl unload ~/Library/LaunchAgents/ai.hermes.gateway.plistlaunchctl load ~/Library/LaunchAgents/ai.hermes.gateway.plist

Step 4：验证

curl http://127.0.0.1:8420/health# {"status":"ok","version":"0.1.0","uptime":79,...}

Step 5：新 Session 生效

插件工具（memory_tencentdb_memory_search、memory_tencentdb_conversation_search）在 session 初始化时注册，必须新开 session 才能注入。

故障排查实录

部署过程踩了五个坑，每个都是真实的。

坑一：插件安装了但未启用

hermes plugins list → "not enabled"

现象：config.yaml 里配了 provider: memory_tencentdb，但工具始终不可用，报 “Gateway is not connected”。

原因：Hermes 插件系统分两步——install 放文件 + enable 激活。只安装没激活，插件从未加载。

修复：hermes plugins enable memory_tencentdb

坑二：GATEWAY_CMD 缺失

现象：插件启用了，但 Gateway Node.js 进程从未启动，端口 8420 始终空闲。

原因：MEMORY_TENCENTDB_GATEWAY_CMD 环境变量未配置，supervisor.py 不知道用什么命令启动 Node 进程。

修复：在 plist 中配置：

cd /plugin/path && node dist/src/gateway/server.js

坑三：&& 被 shlex.split 拆分

现象：Gateway 日志报 getcwd: cannot access parent directories，进程瞬间退出。

原因：supervisor.py 使用 shlex.split() 将命令字符串拆成参数列表。cd /path && node server.js 被拆成 ['cd', '/path', '&&', 'node', 'server.js']——cd 是在独立进程中执行，&& 被当成普通参数，node 从未启动。

修复：用 sh -c 包装：

sh -c 'cd /plugin/path && exec node dist/src/gateway/server.js'

这是最隐蔽的坑——命令看起来完全正确，但 shell 和 subprocess 的语义差异导致静默失败。

坑四：LLM_API_KEY 缺失

现象：Gateway 启动了但 embedding 和 LLM 调用全部失败。

原因：Gateway 内部的记忆提取、向量化、Persona 合成都需要 LLM。MEMORY_TENCENTDB_LLM_API_KEY 标记为 required，不能等于空跑。

修复：复用现有 DeepSeek API key。任何 OpenAI 兼容的 API 都行：

LLM_BASE_URL=https://api.deepseek.com/v1LLM_MODEL=deepseek-chat

坑五：Session 不重启工具不注入

现象：Gateway 健康检查返回 ok，但 memory_tencentdb_memory_search 工具仍不可用。

原因：Hermes 在 session 初始化时注册工具列表。Gateway 后启动不会触发工具热加载。

修复：新开 session 即可。这不是 bug，是设计行为。

架构全景

┌────────────────────────────────────────┐│           Hermes Agent                 ││  ┌──────────────────────────────────┐  ││  │  MemoryTencentdbProvider         │  ││  │  ├─ supervisor.py (进程管理)      │  ││  │  ├─ client.py    (HTTP 客户端)   │  ││  │  └─ watchdog     (健康监控)      │  ││  └──────────┬───────────────────────┘  │└─────────────┼──────────────────────────┘              │ HTTP (127.0.0.1:8420)┌─────────────▼──────────────────────────┐│     TencentDB Gateway (Node.js)        ││  ┌──────────────────────────────────┐  ││  │  四层记忆引擎                     │  ││  │  L0 → L1 → L2 → L3              │  ││  │  + Mermaid 符号化                │  ││  │  + SQLite 向量检索               │  ││  └──────────────────────────────────┘  ││  数据目录: ~/.memory-tencentdb/        │└────────────────────────────────────────┘

双引擎：Hindsight + TencentDB

我当前的记忆架构是双引擎模式：

• Hindsight — 长期结构化知识，标签分类检索，31 条记忆 + 323 条语义链接

• TencentDB — 刚激活，四层金字塔，负责对话捕获 + 自动提取 + 画像合成

两者互补：Hindsight 管"技术知识库"，TencentDB 管"你是谁"。一个存事实，一个懂人。

结语

部署 TencentDB 花了两小时排查，根因全是配置细节。但一旦跑通，这是目前开源 Agent 记忆方案里设计最精良的一个——分层不是噱头，符号化不是炫技，Benchmark 数据是实打实的。

AI 的记忆不应该是一堆便利贴，而应该是一座有索引的图书馆。