TencentDB Agent Memory 使い方ガイド（2026 最新版）

最終更新：2026年8月6日。インストール手順と設定項目は TencentDB-Agent-Memory 公式リポジトリ、npm プラグイン文書、Tencent Cloud Memory 接続準備 に照合済みです。

OpenClaw、Hermes、自前フレームワークで AI Agent を組んだ経験があるなら、次のような破綻に心当たりがあるはずです。三往復目で指定した Swift のコードスタイルを忘れる。二十手のツール呼び出しのあとコンテキストが溢れ、存在しないパスを捏造する。セッションを変えると毎回プロジェクト背景を説明し直す。

従来の対処は「履歴を全部ベクトル庫に入れる」か「雑に要約する」でした。Tencent が 2026 年に MIT で公開した TencentDB Agent Memory は別ルートを取ります。符号化された短期記憶と四层の長期記憶（L0–L3）を組み合わせ、デフォルトはローカル SQLite + sqlite-vec で外部クラウド依存なしに動かせます。本稿は iOS / Flutter / AI 開発者向けに、「原理を理解 → プラグイン導入 → ローカルかクラウドか判断」という順で書き、Gateway を クラウド Mac に 7×24 常駐させるタイミングも示します。

はじめに：Agent が「忘れる」理由

長時間タスクで Agent が失敗する主因は、モデルの賢さではなくコンテキスト管理の破綻であることが多いです。Wide Search や SWE-bench 型の作業では、ツールが返す JSON、Web 本文、ビルドログが簡単に数十万トークンに達します。原文をすべてウィンドウに残せばコストと遅延が爆発し、乱暴に削除すれば次のステップで同じ検索を繰り返したり、誤ったファイルを直したりします。

TencentDB Agent Memory が解くのはこの矛盾です。覚えるべきことは覚えつつ、証拠鎖は下钻可能な底層に保持する。OpenClaw プラグイン向けの公開ベンチマークでは、短期記憶タスクで最大約 61% のトークン削減、PersonaMem 長期記憶精度が 48% から 76% へ——数値はモデルとタスクで変わりますが、分层＋オフロードが平铺ベクトルより省エネで安定する方向は明確です。

Kvmkit 読者にとって典型のワークフローは二つあります。① Mac 上で Cursor / Claude Code に OpenClaw プラグインを付け、プロジェクト級の記憶を持たせる。② Windows で Flutter を書き、クラウド Mac で Gateway とローカル MLX 推論を動かし、「記憶サービス」と「Xcode ビルド」を同一の安定ノードに置く。

社内で Agent を試験運用しているチームなら、失敗ログを見ると「モデルが弱い」より「コンテキストが壊れた」ケースが目立ちます。特にツールチェーンが長い iOS CI や MCP 連携では、一度の暴走が後続タスク全体を汚染します。記憶層を先に整えることは、モデル選定より先にやる価値がある投資です。

核心概念：分层記憶と符号化短期圧縮

本プロジェクトは「記憶スライスをすべてベクトルに平らに並べる」設計を拒否します。長期側は意味のピラミッド、短期側は 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% 追跡可能にします。ログ全文をウィンドウに戻す必要はありません。

MCP ツールチェーンを並行構築している場合は、記憶プラグインと GitHub MCP Server 全プラットフォーム導入ガイド を同じ OpenClaw 設定に載せると整理しやすいです。ツールが「何ができるか」を担い、Memory が「何をしたか・ユーザーは誰か」を担います。

ベクトル RAG だけに頼る設計と比べると、監査とデバッグのしやすさが段違いです。「なぜその結論に至ったか」を L0 まで辿れるため、本番障害の再現調査でも役立ちます。Flutter チームが Widget ツリーの状態遷移をログで追う感覚に近い、構造化された記憶です。

実践：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 スロットを登録します。

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

リポジトリの scripts/openclaw-after-tool-call-messages.patch.sh を実行（OpenClaw 更新後は再実行推奨）。ツール結果のオフロードと回溯がここで初めて正しく動きます。「プラグインを入れたがトークンが減らない」多くの原因はこのパッチ未適用です。

方案 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（クラウド）

チーム記憶を Tencent Cloud マネージドに載せる場合は、コンソールで Memory を作成後 SDK を導入します。

pip install tencentdb-agent-memory-sdk

非同期クライアントで会話書き込み・Atom 検索（フィールドはコンソール仕様に従う）。Python オーケストレーションがあり、複数 Agent が共有庫を使う企業向け。個人試用でクラウド必須ではありません。

受け入れチェックリスト

• 三往復の対話後、persona.md やシナリオファイルが生成されているか；
• offload 有効後、同一 SWE タスクの前後でトークン曲線を比較；
• 意図的に古いツール結果を参照させ、node_id から refs/ 原文を取り戻せるか；
• Tool Calls がループする場合は記憶のせいにせず、Kimi K3 Tool Calls 循環対策（2026 止血手順） でメッセージ鎖を確認。

クラウド Mac / Apple Silicon との関係

Memory Gateway は常駐サービスです。ポート待受、ローカル SQLite の読み書き、バックグラウンドでの抽出と召回を行います。ノートのスリープ、Windows Update 再起動、家庭回線の断続は、Agent にとって「突然の健忘」に見えます。iOS チームに現実的な構成は次のとおりです。

• ローカル：Cursor / Xcode でコード；
• クラウド Mac mini：OpenClaw Gateway + TencentDB Memory + Ollama / MLX を同機；
• リモート：SSH や画面共有でデバッグ、データはクラウドディスクに永続化。

Apple Silicon の強みは統一メモリとネイティブ Unix 環境。Node 22、Docker Desktop、Homebrew の導入経路が明確で、Gateway を長時間動かしてもデスクトップ級 GPU より消費電力が低い。M4 Mac mini の待機は数ワット程度で、チーム共有の記憶ノードに向きます。ローカル GPU で小モデルを回す案を検討中なら、大モデル推論は Windows に置き、7×24 オンラインが必要な記憶と macOS ツールチェーンだけ Kvmkit クラウド Mac へ移すと、自宅機のスリープでセッションが切れるリスクを避けられます。

リモート Mac を採用する際は、データボリュームのバックアップ方針も先に決めてください。SQLite と refs/ はディスク上のファイルなので、スナップショットや定期エクスポートを組み込むと、ノード移行時の痛みが大幅に減ります。

コスト・性能・リスクの比較

判断はシンプルに覚えてください。プロトタイプはローカル SQLite でゼロインフラ検証。記憶データがチーム資産になったら常駐クラウド Mac か Tencent インスタンスへ。ノートで二週間本番 Agent を回してから移行すると、L0 対話と refs の移行コストを過小評価しがちです。

よくある質問

まとめ

• TencentDB Agent Memory は L0–L3 分层と Mermaid オフロードで長時間 Agent のコンテキスト膨張を抑え、デフォルトはローカルで完結。
• OpenClaw プラグインが最速の入門。Hermes は Docker、企業自前は Python SDK でクラウド。
• 記憶と macOS ツールチェーンを 7×24 同機したいなら、スリープするノートよりクラウド Mac mini が安定。

Agent 記憶は「ベクトルをいくつか足す」だけでは解けません。まず分层モデルを動かし、データをローカル SQLite に置くかチームノードへ移すか決める——ここを正しくやれば、その後の iOS CI、MCP ツール、より大きなモデル接続が楽になります。