TencentDB Agent Memory on KnightLi Blog

Cómo conectar la memoria del agente TencentDB a OpenClaw: memoria local a largo plazo, compresión de registros y recuperación rastreable

Wed, 15 Jul 2026 22:08:00 +0800

Una vez que una tarea larga de OpenClaw abarca varias rondas de llamadas a herramientas, generalmente surgen dos problemas: el contexto se atasca con registros o las nuevas sesiones requieren una reinterpretación de las convenciones del proyecto. TencentDB Agent Memory proporciona memoria local a largo plazo y compresión de registros a corto plazo para OpenClaw: SQLite + sqlite-vec se utiliza de forma predeterminada para organizar jerárquicamente información a largo plazo; Una vez habilitada la descarga, el resultado completo de la herramienta se guarda en un archivo externo y solo se inyecta en el contexto un estado simbólico optimizado. Almacén oficial del proyecto

Este artículo sólo trata sobre el acceso a OpenClaw. El objetivo clave no es “hacer que el agente recuerde todo”, sino que pueda recuperar datos cuando sea necesario y permitirle rastrear resúmenes de alto nivel hasta la conversación original o el registro de la herramienta.

Confirma dos cosas antes de la instalación.

Actualmente OpenClaw puede iniciar y ejecutar conversaciones básicas con normalidad; Primero resuelva los problemas de modelo, permiso o puerta de enlace y luego agregue el complemento de memoria.
Conoce la ubicación de la copia de seguridad y los límites de acceso a los datos locales. La memoria puede contener contexto del proyecto, registros de tareas y resultados de herramientas y no debe tratarse como una memoria caché temporal y no relacionada.

Al acceder por primera vez, se recomienda habilitar primero solo la memoria a largo plazo y luego habilitar la compresión de registros después de confirmar que la recuperación es correcta. De esta manera, una vez que ocurre un error, se puede determinar claramente si se debe a la extracción, recuperación o configuración de descarga de memoria.

Instalar y habilitar complementos

Instale usando el comando del complemento nativo OpenClaw:

1
2

openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
openclaw gateway restart

Las actualizaciones posteriores también deben utilizar el comando de actualización de complementos de OpenClaw para evitar que los complementos se deshabiliten debido al rango de versión semántica:

`1`	`openclaw plugins update @tencentdb-agent-memory/memory-tencentdb`

Habilitado en ~/.openclaw/openclaw.json:

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

El archivo README oficial indica que el backend predeterminado es SQLite + sqlite-vec local. Cuando está habilitado, el complemento captura conversaciones, extrae recuerdos, agrega escenas, genera personajes y recuerda antes de la siguiente ronda; no requiere llamadas adicionales a API externas para la función de memoria.

Pruebe la memoria a largo plazo con un conjunto de hechos verificables

No se limite a preguntar: “¿Te acuerdas de mí?” Realice una prueba con respuestas y revisabilidad:

1
2
3

第 1 轮：告诉 Agent 当前项目的包管理器、测试命令和一条明确的输出约定。
第 2 轮：让它执行一个与这些约定相关的小任务。
新会话：询问测试命令和输出约定，并要求说明信息来源或不确定项。

Pasar la norma no significa que recitó más contenido, sino que recuperó correctamente los hechos y no agregó información que no existía sin autorización. Si los compromisos del proyecto han cambiado, los recuerdos antiguos deben actualizarse o borrarse en lugar de esperar que el modelo determine automáticamente cuáles están desactualizados.

Habilitar la compresión de registros a corto plazo (descarga)

La salida de herramientas, los resultados de búsqueda y las pilas de errores suelen ser las principales fuentes de sobrecarga de tokens para tareas largas. La función de descarga del proyecto moverá el registro completo a un archivo externo, dejando el diagrama de estado comprimido de Mermaid en contexto. Los requisitos oficiales requieren que las versiones de OpenClaw y del complemento sean al menos 0.3.4.

Abrir en la configuración del complemento:

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

Luego registre la ranura del motor de contexto y deje que OpenClaw entregue la solicitud de descarga de contexto al complemento:

{
  "plugins": {
    "slots": {
      "contextEngine": "memory-tencentdb"
    }
  }
}

Finalmente, ejecute el parche proporcionado por el proyecto para que el mensaje after-tool-call pueda desinstalarse y restaurarse:

`1`	`bash scripts/openclaw-after-tool-call-messages.patch.sh`

Este parche sólo necesita ejecutarse una vez por instalación de OpenClaw; será necesario volver a aplicarlo después de una actualización de OpenClaw.

Cómo funciona la recuperación rastreable

La compresión de registros no debería equivaler a una pérdida de detalles. El enlace a corto plazo de TencentDB Agent Memory es:

完整工具日志 → refs/*.md
              ↓
步骤摘要 → jsonl 索引
              ↓
Mermaid 状态图（带 node_id）→ 注入 Agent 上下文

Cuando el Agente o usted necesitan verificar una conclusión, el resumen correspondiente y el registro original se pueden encontrar en el diagrama de estado de Mermaid en node_id. La memoria a largo plazo sigue una relación de profundización similar: Persona → Scenario → Atom → Conversation. Por lo tanto, al solucionar el problema “por qué el Agente lo recordó incorrectamente”, primero debe volver a la evidencia original en lugar de simplemente modificar el resumen final.

Tres comprobaciones de aceptación que deben realizarse después de la activación.

Recuerdo a largo plazo: recuperar correctamente un hecho de prueba en una nueva sesión y poder admitir elementos inciertos.
Rastreo de registros: ejecute una tarea de llamada de múltiples herramientas y confirme que la salida original aún se puede encontrar a través de node_id después de la compresión.
Protección contra fallas: Deje que una llamada a una herramienta falle deliberadamente y verifique si el mensaje de error, los registros originales y la siguiente ronda de recuperación aún son comprensibles.

Si solo ve el contexto abreviado pero no puede rastrear la información original, la descarga no debe usarse para tareas de producción importantes. La premisa de la compresión es ser recuperable, no reducir el token en sí.

Límites de seguridad para configuración y datos

El uso predeterminado del almacenamiento local no significa que se pueda ignorar la seguridad. Sugerencias:

Incorpore el directorio de datos de la memoria en el simulacro de copia de seguridad y recuperación cifrado.
No coloque claves en conversaciones, registros de herramientas o personas que no deban guardarse a largo plazo.
Después de actualizar OpenClaw o los complementos, utilice una sesión de prueba para confirmar que la extracción, recuperación y descarga de memoria no se degradan.
Revise periódicamente personas, escenarios y compromisos de proyectos antiguos para eliminar información desactualizada o confidencial.

Si desea implementar modelos locales compatibles con Hermes, Docker Gateway u OpenAI al mismo tiempo, puede leer [Descripción general de la implementación local de la memoria del agente TencentDB] (/es/2026/07/15/tencentdb-agent-memory-local-deployment-ollama-guide/).

Preguntas frecuentes

Si aún olvida el acuerdo del proyecto después de habilitarlo, ¿dónde debe verificar primero?

Primero confirme que el complemento esté habilitado, que la puerta de enlace se haya reiniciado y pruebe si realmente abarca una nueva sesión; luego verifique el momento de activación de la extracción de memoria y los permisos del directorio de almacenamiento. No confundas tus pruebas; utilice comandos, rutas o convenciones de salida verificables.

¿Por qué no puedo ver el registro completo después de la descarga?

El registro completo debe guardarse en un registro externo como refs/*.md sin inyectar completamente el contexto. Retroceda a través de node_id y el índice resumido en el diagrama de Sirena; Si el archivo no existe o no se puede leer, primero verifique si la ruta, los permisos y el parche se han aplicado correctamente.

¿Es necesario habilitar la descarga?

No. Sólo la memoria a largo plazo se puede utilizar para tareas breves o en las primeras etapas de depuración. Active la descarga solo si la salida de la herramienta realmente está causando un aumento del contexto y ha verificado que el vínculo de retroceso está intacto.

Resumen

La secuencia segura para acceder a la memoria del agente TencentDB es: primero instalar y habilitar el complemento OpenClaw, probar la recuperación a largo plazo con hechos verificables, luego activar la descarga según sea necesario, registrar el motor de contexto, aplicar parches y finalmente verificar si node_id puede regresar al registro original. El resultado es un sistema de memoria local auditable en lugar de un resumen automático no interpretable.

Tutorial de implementación local de TencentDB Agent Memory: memoria a largo plazo, compresión de registros y recuperación rastreable

Wed, 15 Jul 2026 22:00:00 +0800

本地 Agent 经常遇到两类相反的问题：会话一长，工具日志和上下文迅速挤满 token；会话一断，又要重新解释项目约定、偏好和已完成的工作。TencentDB Agent Memory 尝试把这两件事拆开处理：短期任务把冗长日志卸载并压缩，长期记忆把对话逐层整理为可召回的信息，同时保留回到原始证据的路径。项目官方仓库

它并不是把全部聊天记录塞回提示词，而是使用“原始记录 → 原子事实 → 场景 → Persona”的长期记忆层次；短期侧则把工具输出保留在文件中，以 Mermaid 任务图和 node_id 提供精简上下文与回溯入口。适合本地 Agent、OpenClaw、Hermes 及希望接入 OpenAI 兼容模型端点的场景。

部署前先决定：你要解决哪一类记忆问题

先把目标写清楚，配置会简单很多：

目标	优先启用的能力	先验证什么
跨会话记住项目约定和用户偏好	长期记忆与召回	是否能在下一轮正确找回历史事实
长任务中工具日志太长	短期 offload 与符号记忆	原始日志是否可通过 `node_id` 回溯
本地运行且不想依赖外部记忆 API	SQLite + sqlite-vec 默认后端	数据目录、备份和权限是否可控
用 Ollama 或其他本地模型	OpenAI 兼容 Gateway 配置	容器/宿主机能否访问模型端点

不要一开始就打开全部功能。建议先完成长期记忆的写入与召回，再开启工具日志压缩；这样出现遗漏时，才容易判断是模型、检索、压缩还是网络路径的问题。

方案一：给 OpenClaw 加上本地长期记忆

官方 README 提供的 OpenClaw 路径最短。插件默认使用本地 SQLite + sqlite-vec，不需要外部记忆 API：

1
2

openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
openclaw gateway restart

在 ~/.openclaw/openclaw.json 中启用插件：

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

启用后，插件会负责捕获对话、抽取记忆、聚合场景、生成 Persona，并在下一轮前执行召回。此时先做一个小验证：连续完成几轮有明确事实的对话，重开会话后询问其中一个细节，确认 Agent 返回的是已保存事实，而不是自行猜测。

如果你还没有准备好本地模型服务，可先从 Codex 本地大模型接入 Ollama 的排错顺序检查服务、模型名称和运行环境是否对齐。

按需打开短期日志压缩

长任务中最容易膨胀的是搜索结果、命令输出和错误日志。TencentDB Agent Memory 的 offload 会把完整工具日志写到外部文件，只将带 node_id 的精简 Mermaid 状态图放进上下文；需要细节时，Agent 可以再沿 node_id 找回原始文本。

OpenClaw 的官方示例要求版本不低于 0.3.4。先开启 offload：

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

再注册 context engine 槽位：

{
  "plugins": {
    "slots": {
      "contextEngine": "memory-tencentdb"
    }
  }
}

最后执行项目提供的补丁，使 after-tool-call 消息能够被正确卸载和恢复：

`1`	`bash scripts/openclaw-after-tool-call-messages.patch.sh`

OpenClaw 升级后需要重新应用这个补丁。上线前用一次包含多轮工具调用的任务验证两件事：上下文是否变短，以及失败时能否从 Mermaid 图的 node_id 回到对应原始日志。只有同时满足，压缩才没有牺牲排障能力。

方案二：用 Docker 启动 Hermes Memory Gateway

如果你使用 Hermes，官方 Docker 镜像会将 hermes-agent 与 memory_tencentdb provider 一起构建，Gateway 默认监听 8420。在仓库根目录执行：

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

启动后先检查健康状态：

`1`	`curl http://localhost:8420/health`

返回 {"status":"ok"} 或 {"status":"degraded"} 说明 Gateway 已启动；degraded 时不要直接投入长期任务，应先检查模型连接、存储卷与日志。

与 Ollama 对接时的正确边界

项目的 MODEL_PROVIDER="custom" 用于 OpenAI 兼容端点。Ollama 提供兼容接口时，可以作为该 Gateway 的模型来源；但“记忆存储在本地”与“模型也完全本地”是两件不同的事，分别验证。

在 Docker 中连接宿主机 Ollama 前，先确认端点可达。Windows/macOS Docker Desktop 通常可使用 host.docker.internal；Linux 则需要按 Docker 网络方式配置宿主机网关。示意配置如下，具体模型名以你本机已拉取的模型为准：

MODEL_API_KEY="ollama"
MODEL_BASE_URL="http://host.docker.internal:11434/v1"
MODEL_NAME="qwen3"
MODEL_PROVIDER="custom"

先在相同网络位置测试 /v1/models 或完成一个最小聊天请求，再启动长期记忆任务。若容器里把 localhost 写成模型地址，实际指向的是容器自身，而不是运行 Ollama 的宿主机，这是最常见的连接错误。

有关 OpenAI 兼容本地 API、Ollama、LM Studio 和 vLLM 的端点检查，可继续阅读本地大模型 API 给 Codex 使用教程。

可追溯性为什么比“自动总结”更重要

不可逆总结看似节省 token，却可能把一个关键条件、失败原因或用户限制丢掉。这个项目将高层信息与底层证据保持关联：

Persona / Mermaid canvas
        ↓
Scenario / jsonl 索引
        ↓
原始对话与工具日志（L0 / refs/*.md）

排查时不要只看最终摘要。若 Agent 记错了偏好或误判任务状态，应沿这条链路回到原始日志，判断是抽取错误、召回排序错误，还是原始输入本来就不完整。把原始资料、记忆索引和配置文件一起纳入备份，才能在迁移或升级时保留这种可验证性。

基础安全与运维检查

Hermes Gateway 暴露 capture、search、recall 等 HTTP 接口。官方默认按本地 sidecar 使用；如果要绑定非回环地址或让其他机器访问，必须加认证和来源限制。

1
2
3

export TDAI_GATEWAY_API_KEY="replace-with-a-long-random-secret"
export TDAI_CORS_ORIGINS="https://your-console.example"
export MEMORY_TENCENTDB_GATEWAY_API_KEY="$TDAI_GATEWAY_API_KEY"

然后确认 Gateway 与插件两侧使用同一个密钥。不要把 8420 端口直接暴露到公网，也不要把 API key、记忆数据库或 refs/*.md 一并提交进 Git。

建议把下面几项纳入日常检查：

为 SQLite 数据、挂载卷和记忆目录建立定期备份与恢复演练。
记录插件、OpenClaw/Hermes、模型和 Docker 镜像版本，升级后先在测试会话验证召回。
限制单次召回数量和注入字符预算，避免“记忆越多，上下文越重”。
定期抽查高层 Persona 是否包含过期或敏感信息，并按自己的数据规则清理。

常见问题

插件启用了，为什么 Agent 还是记不住？

先确认是跨会话问题，而不是当前对话未完成。再检查插件是否已启用、记忆抽取触发频率、存储目录是否可写，以及下一轮召回是否因超时被跳过。不要只用一句模糊问题测试，最好用可验证的项目约定或事实。

开启 offload 后，是否再也看不到原始日志？

不是。offload 的目标是把完整日志移出主上下文，而不是删除它。应通过 node_id、索引和 refs/*.md 回溯原始记录；若无法回溯，应停止将其用于重要任务并先修复存储路径或权限。

Ollama 接不上 Gateway，最先检查什么？

先区分宿主机和容器网络。容器中的 localhost 不等于宿主机；再确认 Ollama 服务、模型名称、OpenAI 兼容 URL、端口和防火墙。用最小接口请求连通后，再排查记忆插件本身。

小结

TencentDB Agent Memory 适合需要长期运行、又希望保持本地可控和可追溯的 Agent 工作流。先用默认 SQLite 后端跑通长期记忆，再按需开启日志 offload；本地模型接入则单独验证网络与 OpenAI 兼容端点。这样既能减少重复解释，也不会在压缩后失去定位问题的原始证据。