Tablestore:エージェントエコシステムの統合

インストール

openclaw plugins install @tablestore/openclaw-tablestore-memory

認証方法

このプラグインは、以下の 2 つの認証モードに対応しています。いずれかを選択してください。

• AccessKey (AK/SK)： すべての機能に対応しています。AK/SK を使用する場合、endpoint と otsInstanceName が未設定であれば、プラグインは cn-beijing リージョンにマネージドインスタンスを自動的に作成し、再利用します。

• API キー： apiKey が設定されている場合、AK/SK よりも優先されます。API キーは、メモリサービスのデータプレーン操作のみを許可し (コントロールプレーンは許可されません)、HTTPS の endpoint と otsInstanceName を明示的に指定する必要があります。また、マネージドインスタンスの自動作成には対応していません。

設定

最小限の AK/SK 設定：

{
  "plugins": {
    "slots": {
      "memory": "tablestore-mem"
    },
    "entries": {
      "tablestore-mem": {
        "enabled": true,
        "config": {
          "endpoint": "https://<instance>.cn-beijing.ots.aliyuncs.com",
          "otsInstanceName": "<instance-name>",
          "accessKeyId": "<AccessKey ID>",
          "accessKeySecret": "<AccessKey Secret>"
        }
      }
    }
  }
}

API キー設定：

{
  "plugins": {
    "slots": { "memory": "tablestore-mem" },
    "entries": {
      "tablestore-mem": {
        "enabled": true,
        "hooks": { "allowConversationAccess": true },
        "config": {
          "apiKey": "<API Key>",
          "endpoint": "https://<instance>.cn-beijing.ots.aliyuncs.com",
          "otsInstanceName": "<instance-name>"
        }
      }
    }
  }
}

以下の設定は、環境変数 TABLESTORE_MEMORY_APP_ID、TABLESTORE_MEMORY_TENANT_ID、TABLESTORE_MEMORY_API_KEY を使用して上書きすることもできます。

オプションパラメーター

スコープマッピング

記憶を書き込む際、プラグインは現在のランタイムアイデンティティを使用します。

{
  "appId": "openclaw",
  "tenantId": "<current-user>",
  "agentId": "<runtime-agent>",
  "runId": "<runtime-session>"
}

記憶を取得する際、プラグインは、すべてのエージェントとセッションにわたるテナントレベルのスコープを使用し、agentId と runId を * に設定します。

{
  "appId": "openclaw",
  "tenantId": "<current-user>",
  "agentId": "*",
  "runId": "*"
}

ランタイムの動作

• before_prompt_build 時に、関連する長期記憶を取得します。

• 取得した記憶を非表示のコンテキストに挿入します (会話履歴には表示されません)。

• agent_end 時に、現在のターンからユーザーおよびアシスタントのメッセージを収集します。

• AddMemories を介してメモリストアに書き戻します (デフォルトでは非同期)。

メモリ統合 (Dream)

このプラグインには、以前に書き込まれた長期記憶の重複排除、書き換え、マージ、クリーンアップを行うオフラインの Dream 統合プロセスが含まれています。

• 書き戻しが成功するたびに、正確なスコープ (appId/tenantId/agentId/runId) が統合のためにキューに追加されます。

• バックグラウンドスケジューラは、 dreamIntervalHours (デフォルト： 24時間) ごとにキューを処理し、 applyMode=safe_auto と incremental=true を使用して、実行ごとに最大 dreamMaxScopesPerRun 個のスコープを統合します。

• dreamOnSessionEnd が有効 (デフォルト) の場合、セッション終了 (ローテーション、リセット、アイドル、またはコンパクション) により、そのセッションスコープが即座に統合されます。これは、バックグラウンドスケジューラとスコープごとのウォーターマークおよび dreamMinIntervalHours スロットリングを共有するため、同じスコープが間隔内に 2 回統合されることはありません。

• safe_auto は、信頼度のしきい値を満たす add、update、merge アクションを自動的に適用します。DELETE は自動的に適用されることはありません。しきい値の優先順位： --threshold (すべてのアクションをカバー) > アクションごとの dreamConfidenceThresholds > 単一値の dreamConfidenceThreshold (デフォルト： 0.9)。

• dreamInstructions が設定されている場合、バックグラウンドジョブ、 session_end トリガー、および CLI Dream ジョブはすべて、カスタム指示を渡します。

• 統合は、特定のスコープのみを対象とし (ワイルドカードなし)、結果をその場で保持し (preserve_scope)、リアルタイムパスとは完全に独立して実行されます。失敗はログに記録されるだけで、取得や書き戻しには影響しません。

• バックグラウンドスケジューラは、OpenClaw プロセスが稼働している間のみ実行されます。非常駐環境の場合は、cron で CLI を実行してください (以下を参照)。

CLI とスラッシュコマンド

OpenClaw プラグインは、以下のデバッグおよび操作コマンドを提供します。

# 書き込みと取得
openclaw tablestore-mem add "田中一郎はジャスミンティーが好きです" --uid ichirou
openclaw tablestore-mem search "田中一郎の好みは" --uid ichirou
openclaw tablestore-mem search "田中一郎の好みは" --uid ichirou --top-k 10 --min-similarity 0.3

# 接続性、メモリストア、スコープの一覧表示を診断
openclaw tablestore-mem doctor --uid ichirou

# オンデマンドでメモリ統合 (Dream) をトリガー
openclaw tablestore-mem dream --uid ichirou --wait
openclaw tablestore-mem dream --uid ichirou --apply-mode proposal --wait
openclaw tablestore-mem dream --uid ichirou --threshold 0.8 --wait
openclaw tablestore-mem dream --uid ichirou --instructions "Prioritize merging duplicate preferences" --wait

OpenClaw セッション内では、以下のスラッシュコマンドを使用します。

/tablestore-mem-add 田中一郎はジャスミンティーが好きです
/tablestore-mem-search jasmine tea

インストール

hermes plugins install https://github.com/aliyun/hermes-tablestore-memory
hermes memory setup

hermes memory setup の際に、tablestore-mem を選択します。

このプラグインには tablestore>=6.4.5 が必要です。この依存関係が Hermes Python 環境に存在しない場合は、SDK を手動でインストールしてください。

認証情報の設定

認証情報を ~/.hermes/.env に保存します：

TABLESTORE_MEMORY_AK=<AccessKey ID>
TABLESTORE_MEMORY_SK=<AccessKey Secret>

メモリサービスの設定

機密性の低い設定を $HERMES_HOME/tablestore_memory.json に保存します：

{
  "endpoint": "https://<instance>.cn-beijing.ots.aliyuncs.com",
  "instance_name": "<instance-name>",
  "memory_store_name": "hermes_mem",
  "description": "",
  "app_id": "hermes",
  "tenant_id": "",
  "enable_rerank": true,
  "auto_create_store": true,
  "timeout": 30
}

デフォルト値

スコープのマッピング

Hermes プラグインは、4 つのスコープフィールドを次のようにマッピングします：

書き込み時、プラグインは正確なセッションスコープを使用します。取得時は、agentId="" と runId="" が設定されることで、スコープはテナントレベルに拡張されます。

利用可能なツール

また、プラグインは各ターンの後にユーザーとアシスタントのメッセージを自動的に同期し、次のターンの前に関連するメモリをプリフェッチします。

Hermes CLI コマンド

memory.provider を tablestore-mem に設定した後、次のコマンドを実行します：

hermes tablestore-mem add "User prefers concise answers."
hermes tablestore-mem add "User likes Rust." --metadata source=manual --metadata topic=preferences
hermes tablestore-mem add "Write this memory synchronously." --sync
hermes tablestore-mem search "concise answers"
hermes tablestore-mem search "Rust" --top-k 10

機能

• ターンごとの自動取得 (UserPromptSubmit フック)：プロンプトの送信前に関連する長期記憶を取得し、会話の表示には含まれない非表示コンテキストに挿入します。

• ターンごとの自動書き戻し (Stop フック)：ターンの終了後、そのターンの新しいユーザー メッセージとアシスタント メッセージを増分的にメモリストアに書き込みます。バッチはサービス制限 (1 バッチあたり最大 20 メッセージ、32,000 バイト) に準拠します。

• オフラインの Dream 統合 (SessionEnd フックと CLI または cron)：重複排除、書き換え、マージを行い、古いメモリを削除します。

• MCP ツール (モデルが明示的に呼び出し)：search_memory、add_memory、consolidate_memory。

• スラッシュコマンド：/search、/add、/doctor、/dream。

• CLI：search、add、doctor、dream。

• API キー と AccessKey (AK/SK) の両方の認証をサポートします。

要件

• Node.js 18 以降。

• 作成済みの Tablestore インスタンス (メモリサービスは China (Beijing) リージョンでのみ利用可能です)。HTTPS エンドポイント と インスタンス名 に加えて、API キーまたは AK/SK のペアを用意してください。

• このプラグインはインスタンスを自動作成しません。エンドポイントとインスタンス名を明示的に指定してください。

インストール

リポジトリ：https://github.com/aliyun/tablestore-memory-claude-plugin。依存関係は esbuild によって dist/ に事前にバンドルされ (リポジトリに同梱)、インストール時に npm install を実行する必要はありません。

# オプション1 (推奨): GitHub マーケットプレイスからインストール
claude plugin marketplace add aliyun/tablestore-memory-claude-plugin
claude plugin install tablestore-memory@tablestore-memory-marketplace

# オプション2: リポジトリをクローンし、ローカルディレクトリからインストール
git clone https://github.com/aliyun/tablestore-memory-claude-plugin.git
claude plugin marketplace add ./tablestore-memory-claude-plugin
claude plugin install tablestore-memory@tablestore-memory-marketplace

開発時はマーケットプレイスを使用せず、プラグインディレクトリを直接参照します：

claude --plugin-dir /path/to/tablestore-memory-claude-plugin

プラグインのソースを変更した後、バンドルを再ビルドします：

# dist/ に再ビルド
npm run build

設定

~/.claude/settings.json の env ブロックに次の変数を設定します。これらはフックと MCP サーバーの両方に注入されます：

{
  "env": {
    "TABLESTORE_MEMORY_ENDPOINT": "https://<instance>.cn-beijing.ots.aliyuncs.com",
    "TABLESTORE_MEMORY_INSTANCE": "<instance>",
    "TABLESTORE_MEMORY_API_KEY": "<api-key>"
  }
}

代わりに AK/SK を使用する場合は、TABLESTORE_MEMORY_API_KEY を TABLESTORE_ACCESS_KEY_ID と TABLESTORE_ACCESS_KEY_SECRET に置き換えます。

認証の優先度：TABLESTORE_MEMORY_API_KEY が設定されている場合、プラグインは API キー認証 (HTTPS エンドポイントが必要) を使用します。それ以外の場合は AK/SK を使用します。どちらも設定されていない場合、プラグインは通知なく無効化されます。

設定ファイルをフォールバックとして使用することもできます：~/.tablestore-memory/config.json (キャメルケースキー endpoint、instanceName、apiKey、accessKeyId、accessKeySecret、storeName)。環境変数は設定ファイルより優先されます。

環境変数の一覧：

スコープ設計 (ユーザー単位のグローバル プール)

• 特定のセッションにアンカーを書き込みます：appId / tenantId / agentId / runId=<session_id>。

• 取得範囲は固定のテナント内で拡張されます：agentId=* と runId=*。これにより、セッション間およびプロジェクト間の呼び出しが可能になります。

• ワイルドカードはサービス階層ルールに従います。あるレベルで * を使用した場合、それより下位のすべてのレベルでも * を使用する必要があります。

Dream (メモリ統合)

• セッションの終了 (SessionEnd) により、テナントスコープの統合がトリガーされます。DREAM_MIN_INTERVAL_HOURS によってスロットリングされます。状態は ~/.tablestore-memory/dream-state.json に保存されます。

• このプラグインはバックグラウンドデーモンとして実行できないため、cron から CLI を呼び出して定期的に統合処理を実行してください：

# 例: テナントのメモリを毎日 03:17 に統合し、結果を待つ
17 3 * * *  node /path/to/tablestore-memory/dist/cli.mjs dream --uid <tenant> --wait

CLI

node dist/cli.mjs search "What beverages does the user like?" --top-k 5
node dist/cli.mjs add "The user likes Americano." --sync
node dist/cli.mjs doctor
node dist/cli.mjs dream --uid <tenant> --apply-mode safe_auto --wait

--uid はテナントを上書きします (運用や cron での使用を想定)。-q/--quiet はデータ フィールドのみを出力します。

動作と制約

• フェイルオープン：設定の不足、または SDK の例外が発生した場合でも、会話は中断されません。フックは stderr にログを出力し、ステータス 0 で終了します。

• フックの stdout にはプロトコル JSON のみが出力されます。ログはすべて stderr に出力されます。

• 非同期書き込み (sync=false) の後、長期記憶は 約 15 秒以内に取得可能になります。--sync を使用すると、直ちに取得できます。