TencentDB Agent Memory on KnightLiブログ

TencentDB エージェントメモリを OpenClaw に接続する方法: ローカル長期メモリ、ログ圧縮、追跡可能な取得

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

長い OpenClaw タスクがツール呼び出しの複数ラウンドにまたがると、通常 2 つの問題が発生します。コンテキストがログで詰まるか、新しいセッションでプロジェクト規約の再解釈が必要になるかです。 TencentDB エージェントメモリは、OpenClaw にローカルの長期メモリと短期ログ圧縮を提供します。SQLite + sqlite-vec は、長期情報を階層的に編成するためにデフォルトで使用されます。オフロードが有効になると、完全なツール出力が外部ファイルに保存され、合理化されたシンボリック状態のみがコンテキストに挿入されます。【プロジェクト公式倉庫】(https://github.com/TencentCloud/TencentDB-Agent-Memory)

この記事では、OpenClaw アクセスについてのみ説明します。主な目標は、「エージェントにすべてを記憶させる」ことではなく、必要に応じて事実を取得できるようにし、元の会話やツールのログまで大まかな概要を追跡できるようにすることです。

インストール前に 2 つのことを確認してください

現在、OpenClaw は基本的な会話を通常どおり開始および実行できます。まずモデル、権限、またはゲートウェイの問題を解決してから、メモリプラグインを追加します。
ローカルデータのバックアップ場所とアクセス境界を知っています。メモリにはプロジェクトコンテキスト、タスクレコード、ツール出力が含まれる場合があるため、無関係な一時的なキャッシュとして扱うべきではありません。

初めてアクセスする場合は、最初に長期記憶のみを有効にし、リコールが正しいことを確認してからログ圧縮を有効にすることをお勧めします。このようにして、エラーが発生すると、その原因がメモリの抽出、取得、またはオフロード構成のいずれであるかを明確に判断できます。

プラグインをインストールして有効にする

OpenClaw ネイティブプラグインコマンドを使用してインストールします。

1
2

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

後続のアップグレードでは、セマンティックバージョン範囲が原因でプラグインが無効になることを避けるために、OpenClaw のプラグイン更新コマンドも使用する必要があります。

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

~/.openclaw/openclaw.json で有効化:

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

公式 README には、デフォルトのバックエンドはローカル SQLite + sqlite-vec であると記載されています。有効にすると、プラグインは会話をキャプチャし、記憶を抽出し、シーンを集約し、ペルソナを生成し、次のラウンドの前にリコールします。メモリ機能のために外部 API を追加で呼び出す必要はありません。

一連の検証可能な事実を使用して長期記憶をテストする

「私のことを覚えていますか？」とただ尋ねないでください。回答とレビュー可能性を備えたテストを受けてください:

1
2
3

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

標準に合格したということは、より多くの内容を記述したことを意味するのではなく、事実を正確に取得し、許可なく存在しない情報を追加しなかったことを意味します。プロジェクトのコミットメントが変更された場合は、どれが古いかをモデルが自動的に判断することを期待するのではなく、古いメモリを更新または消去する必要があります。

短期ログ圧縮 (オフロード) を有効にする

多くの場合、ツールの出力、検索結果、エラースタックは、長いタスクのトークン肥大化の主な原因となります。プロジェクトのオフロード機能は、圧縮された Mermaid 状態図をコンテキスト内に残したまま、完全なログを外部ファイルに移動します。公式要件では、OpenClaw とプラグインのバージョンが少なくとも 0.3.4 である必要があります。

プラグイン設定で開きます:

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

次に、コンテキストエンジンスロットを登録し、OpenClaw がコンテキストオフロードリクエストをプラグインに引き渡せるようにします。

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

最後に、プロジェクトが提供するパッチを実行して、after-tool-call メッセージをアンインストールして復元できるようにします。

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

このパッチは、OpenClaw のインストールごとに 1 回だけ実行する必要があります。 OpenClaw のアップグレード後に再適用する必要があります。

追跡可能な取得の仕組み

ログを圧縮しても、詳細が失われることはありません。 TencentDB Agent Memory の短期リンクは次のとおりです。

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

エージェントまたはユーザーが結論を検証する必要がある場合、対応する概要と元のログは node_id に沿った Mermaid 状態図から見つけることができます。長期記憶は、同様のドリルダウン関係 Persona → Scenario → Atom → Conversation に従います。したがって、「エージェントが間違って記憶した理由」をトラブルシューティングする場合は、最終的な概要を変更するだけでなく、最初に元の証拠に戻る必要があります。

アクティベーション後に実行する必要がある 3 つの受け入れチェック

長期再現: 新しいセッションでテスト事実を正しく検索し、不確実な項目を認めることができます。
ログトレースバック: マルチツール呼び出しタスクを実行し、圧縮後も node_id を通じて元の出力が見つかることを確認します。
障害保護: ツール呼び出しを意図的に失敗させ、エラーメッセージ、元のログ、および次の回復ラウンドが理解できるかどうかを確認します。

短縮されたコンテキストのみが表示され、元の情報を追跡できない場合は、重要な運用タスクにオフロードを使用しないでください。圧縮の前提は、トークン自体を削減することではなく、回復可能であることです。

構成とデータのセキュリティ境界

デフォルトでローカルストレージを使用しても、セキュリティを無視できるわけではありません。提案:

メモリデータディレクトリを暗号化バックアップおよびリカバリドリルに組み込みます。
長期保存すべきではない会話、ツールログ、ペルソナにキーを入れないでください。
OpenClaw またはプラグインを更新した後、テストセッションを使用して、メモリ抽出、リコール、およびオフロードが低下していないことを確認します。
古いペルソナ、シナリオ、プロジェクトの取り組みを定期的に見直して、古い情報や機密情報を削除します。

Hermes、Docker Gateway、または OpenAI 互換のローカルモデルを同時にデプロイする場合は、[TencentDB エージェントメモリのローカルデプロイメントの概要] (/ja/2026/07/15/tencentdb-agent-memory-local-deployment-ollama-guide/) を参照してください。

よくある質問

プロジェクト契約を有効にした後も忘れてしまった場合、最初にどこを確認すればよいですか?

まず、プラグインが有効になっていること、ゲートウェイが再起動されていることを確認し、実際に新しいセッションにまたがるかどうかをテストします。メモリ抽出のトリガータイミングと格納ディレクトリの権限を確認してください。テストを曖昧にしないでください。検証可能なコマンド、パス、または出力規則を使用してください。

オフロード後に完全なログが表示されないのはなぜですか?

完全なログは、コンテキストを完全に挿入せずに、refs/*.md などの外部ログに保存する必要があります。 node_id と Mermaid ダイアグラムの概要インデックスを元に戻します。ファイルが存在しない、または読み取れない場合は、まずパス、権限、パッチが正しく適用されているかどうかを確認してください。

オフロードを有効にする必要がありますか?

いいえ。短期のタスクまたはデバッグの初期段階では、長期記憶のみを使用できます。ツールの出力が実際にコンテキストの肥大化を引き起こしており、バックリンクが損なわれていないことを確認した場合にのみ、オフロードをオンにします。

概要

TencentDB エージェントメモリにアクセスするための安全なシーケンスは、まず OpenClaw プラグインをインストールして有効にし、検証可能な事実で長期リコールをテストし、次に必要に応じてオフロードをオンにし、コンテキストエンジンを登録し、パッチを適用し、最後に node_id が元のログに戻れるかどうかを確認します。その結果、解釈できない自動要約ではなく、監査可能なローカルメモリシステムが作成されます。

TencentDB エージェントメモリのローカル展開チュートリアル: 長期メモリ、ログ圧縮、および追跡可能なリコール

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 兼容端点。这样既能减少重复解释，也不会在压缩后失去定位问题的原始证据。