mcpField
W
walrus-memory

walrus-memory

github.com/mystenlabsエージェントワークフロー347 回インストール1 週間前に更新
リポジトリ

walrus-memory について

Walrus ストレージと Sui のアクセス制御を使い、AI エージェントに永続的でポータブルなメモリを提供する Walrus Memory の統合ガイドです。TypeScript、Python、MCP の設定先を示し、メモリ操作、暗号化、アカウントアクセスを説明します。

主な機能

  1. 01TypeScript と Python SDK のガイド
  2. 02MCP サーバー設定リファレンス
  3. 03メモリ保存、検索、分析の概念
  4. 04Seal 暗号化と委任アクセス
  5. 05リレイヤー、アカウント、名前空間の設定

活用シーン

  1. 01アプリに適した統合方法の選択
  2. 02MCP クライアントでのメモリ設定
  3. 03非同期の保存や検索の問題の調査
  4. 04委任キーとメモリ名前空間の設定

MCP 対応

Cursor、Claude Desktop、Claude Code、Codex などのクライアントで Walrus Memory を設定するための MCP サーバー資料を案内します。資料では、8 つの MCP ツールを含むパッケージと Streamable HTTP の設定を扱います。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/mystenlabs/walrus-skills --skill walrus-memory

インストール後、Claude Code で/walrus-memoryを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

mcp.md
python-sdk.md
ts-sdk.md
evals/
evals.json

詳細

Walrus Memory

ソースの制約： このスキルのすべての情報は、 Walrus Memory のドキュメントと MystenLabs/MemWal リポジトリを情報源としています。 このスキルを拡張する際は、これらの情報源のみを使用してください。

Walrus Memory は、Walrus（分散型ストレージ）と Sui（オンチェーンのアクセス制御）を基盤として、AI エージェントに永続的でポータブルなメモリを提供します。リレイヤー（または手動フローではクライアント）が各メモリを Seal で暗号化し、Walrus に BLOB として保存したうえで、セマンティック検索用のベクトル埋め込みでインデックスを作成します。所有者は、誰が読み取りや書き込みをできるかを制御し、デリゲートキーを使ってエージェント間でアクセスを共有できます。

よくある統合時の間違い：

  1. アカウント ID とデリゲートキーの生成を忘れる。 SDK を使う前に両方が必要です。memory.walrus.xyzで生成してください。
  2. 非同期の remember ジョブを await しない。 remember()はジョブ ID をすぐに返します。アップロードはバックグラウンドで実行されます。保存を確認するには、waitForRememberJob()またはrememberAndWait()を使用してください。
  3. ネームスペースを省略する。 指定しない場合、すべてが"default"に保存されます。メモリを分離するため、プロダクトの各サーフェスにネームスペースを設定してください。
  4. 誤ったリレイヤー URL を使用する。 本番環境（mainnet）はhttps://relayer.memory.walrus.xyzです。ステージング環境（testnet）はhttps://relayer-staging.memory.walrus.xyzです。

リファレンスファイル

ts-sdk — TypeScript SDK リファレンス

パス： ts-sdk.md 読み込むタイミング： @mysten-incubation/memwalを使った TypeScript コードの作成、MemWal、MemWalManual、withMemWalの使用、remember／recall／analyze／restoreの呼び出し、SDK エラーのデバッグを行う場合。 内容： インストール、3 つのエントリーポイント（MemWal、MemWalManual、withMemWal）、設定、完全な API（remember、rememberAndWait、rememberBulk、RecallParams を使った recall、analyze、restore、health）、低レベルメソッド、アカウント管理、Vercel AI SDK との AI ミドルウェア統合。

python-sdk — Python SDK リファレンス

パス： python-sdk.md 読み込むタイミング： PyPI パッケージmemwalを使った Python コードの作成、MemWal、MemWalSync、またはwith_memwal_langchain／with_memwal_openaiミドルウェアの使用を行う場合。 内容： インストール、非同期クライアントと同期クライアント、envプリセット（prod/staging）、RecallParams、askメソッド、LangChain および OpenAI ミドルウェア、Colab ノートブック。

mcp — MCP サーバーリファレンス

パス： mcp.md 読み込むタイミング： Cursor、Claude Desktop、Claude Code、Codex、または別の MCP クライアントで Walrus Memory をセットアップする場合。また、memwal-mcp パッケージの設定、ログイン／認証の問題のデバッグ、Streamable HTTP トランスポートの使用を行う場合。 内容： npx を使ったインストール、ログインフロー、クライアント設定（Cursor、Claude Desktop、Claude Code、Codex）、8 つの MCP ツール、認証必須モード、デフォルトのネームスペース、環境の切り替え、Streamable HTTP のセットアップ。

関連スキル

トピックスキル読み込むタイミング
Walrus の BLOB ストレージwalrus-overviewWalrus 自体を理解する場合
Seal 暗号化walrus-data-securitySeal 暗号化の内部動作を理解する場合
Sui Move コントラクトsui-moveMemWal Move モジュールを理解する場合
トラブルシューティングwalrus-troubleshootingWalrus の一般的なエラーメッセージを確認する場合

ルーティングガイド

タスク読み込むファイル
TypeScript アプリにメモリを統合するts-sdk.md
Python アプリにメモリを統合するpython-sdk.md
Cursor／Claude／Codex 用に MCP をセットアップするmcp.md
Walrus Memory とは何かを理解する以下のスキルの内容
統合方法を選ぶ以下のスキルの内容
アカウントとデリゲートキーを管理するts-sdk.md（アカウント管理のセクション）
リレイヤーをセルフホストする以下のスキルの内容 ＋ リレイヤーのドキュメント
AI ミドルウェア（Vercel AI SDK）を使うts-sdk.md（withMemWal のセクション）
AI ミドルウェア（LangChain／OpenAI）を使うpython-sdk.md

スキルの内容

主な概念

  • メモリ空間。 owner address + namespace + app ID (package ID) によって一意に定義される、分離されたストレージ単位です。ある空間のメモリが別の空間のメモリと混在することはありません。名前空間を使って用途を分けます（例：personal、work、research）。

  • 4 つの主要な操作。

    • Remember — セマンティック埋め込みを使ってメモリを保存します。非同期で、すぐにジョブ ID を返します。
    • Recall — 自然言語のクエリでメモリを検索します。コサイン距離に基づく順位で一致結果を返します。
    • Analyze — LLM を使ってテキストから構造化された事実を抽出します。各事実は個別のメモリとして保存されます。
    • Ask — recall と LLM による推論を組み合わせます。メモリにクエリを送信し、AI が生成した回答を得られます。Python SDK、リレイヤー HTTP API（POST /api/ask）から利用でき、TypeScript SDK ではまだラップされていません。

  • オーナーとデリゲート。 オーナーはアカウントを作成した Sui ウォレットです。デリゲートはオーナーからアクセス権を付与された Ed25519 キーペアです。デリゲートは保存、想起、復号を行えますが、キーの管理や所有権の移転はできません。アクセスは Sui 上の Move スマートコントラクトによって制御されます。

  • 暗号化。 リレイヤーは、Walrus に届く前にすべてのメモリ内容を Seal で暗号化します。手動のクライアントフローではクライアント側で暗号化するため、リレイヤーが平文を見ることはありません。復号できるのはオーナーと承認済みのデリゲートのみです。

  • 忘却と削除。 POST /api/forget は、指定した名前空間のベクトルインデックスの行を削除します。暗号化された Walrus のブロブは残るため、後から restore で再インデックスできます。ブロブを完全に削除する場合は、Security Delete API が有効なデプロイ環境で、ウォレット認証を使ってスポンサー付き Sui 削除トランザクションを準備できます。メモリをプログラムから削除すると、ダッシュボードガイドの古いメモリを削除するを参照してください。

  • リレイヤー。 REST API の背後で埋め込み、暗号化、Walrus へのアップロード、ベクトル検索を処理するバックエンドサービス（Rust + TypeScript サイドカー）です。マネージドリレイヤーは Walrus Foundation が提供しています。セルフホストも可能です。

  • 復元。 ベクトルデータベースが失われた場合、復元フローでは、オンチェーンでブロブを再検出し、復号、再埋め込み、再インデックスすることで、Walrus からデータベースを再構築します。永続的な信頼できるデータソースは Walrus です。

アーキテクチャ
Your App → SDK → Relayer → { Seal encrypt, Walrus upload, pgvector index }
                         ← { pgvector search, Walrus download, Seal decrypt }

6 つのコンポーネント：

  1. SDK（TypeScript または Python）— リクエストに署名し、リレイヤーを呼び出します
  2. リレイヤー（Rust + TS サイドカー）— 埋め込み、暗号化、ストレージ、検索を処理します
  3. スマートコントラクト（Sui 上の memwal::account）— 所有権、デリゲートキー、Seal アクセスを管理します
  4. インデクサー — コントラクトのイベントを PostgreSQL に同期し、高速な検索を実現します
  5. Walrus — 暗号化されたブロブを分散ストレージに保存します
  6. PostgreSQL + pgvector — セマンティック検索用のベクトル埋め込みを保存します
統合方法を選ぶ
方法使用する場面
MemWal（デフォルトの SDK）ほとんどのチームに適しています。すべての処理をリレイヤーが担います。
MemWalManualクライアント側での暗号化が必要な場合に適しています。リレイヤーが平文を見ることはありません。
withMemWal（AI ミドルウェア）Vercel AI SDK を使い、自動での想起と保存を行いたい場合に適しています。
Python SDKPython アプリ向けです。同じリレイヤーと認証を使い、TypeScript API に対応する API を提供します。
MCP サーバーMCP ツールを通じて Cursor／Claude／Codex にメモリ機能を追加できます。カスタムコードは不要です。
セルフホストのリレイヤー信頼境界を完全に制御できます。独自のインフラと認証情報を使用します。
アカウントのセットアップ
  1. memory.walrus.xyz（メインネット）または staging.memory.walrus.xyz（テストネット）にアクセスします
  2. Sui ウォレットを接続します
  3. Walrus Memory アカウントを作成します（Sui アドレスごとに 1 つ）
  4. デリゲートキー（Ed25519 キーペア）を生成します
  5. SDK で key（秘密鍵の 16 進数表記）と accountId（Sui オブジェクト ID）を使用します
リレーヤーのエンドポイント
ネットワークリレーヤー URLダッシュボード
Production（Mainnet）https://relayer.memory.walrus.xyzhttps://memory.walrus.xyz
Staging（Testnet）https://relayer-staging.memory.walrus.xyzhttps://staging.memory.walrus.xyz
コントラクト ID
ネットワークパッケージ IDレジストリ ID
Mainnet0xcee7a6fd8de52ce645c38332bde23d4a30fd9426bc4681409733dd50958a24c60x0da982cefa26864ae834a8a0504b904233d49e20fcc17c373c8bed99c75a7edd
Testnet0xcf6ad755a1cdff7217865c796778fabe5aa399cb0cf2eba986f4b582047229c60xe80f2feec1c139616a86c9f71210152e2a7ca552b20841f2e192f99f75864437
レート制限（管理リレーヤー）
スコープ上限
アカウントごと（バースト）60 ポイント／分
アカウントごと（継続）500 ポイント／時間
デリゲートキーごと30 ポイント／分
ストレージクォータアカウントごとに 1 GB

ポイントコスト：remember/bulk = 10、analyze = 5、remember = 5、restore / remember/manual = 3、ask = 2、その他すべて（recall、recall/manual など）= 1。

ルール
  1. 最初にアカウント ID とデリゲートキーを生成します。 これらがないと SDK は動作しません。memory.walrus.xyz のダッシュボードを使用してください。
  2. 名前空間を明示的に設定します。 設定しない場合、すべてのメモリーは "default" に保存されます。製品の用途、環境、またはドメインごとに分けてください。
  3. remember() は非同期です。 すぐにジョブ ID を返します。保存を確認するには、rememberAndWait() を使用するか、waitForRememberJob() でポーリングしてください。
  4. ネットワークに適したリレーヤー URL を使用します。 Mainnet：relayer.memory.walrus.xyz。Testnet：relayer-staging.memory.walrus.xyz。
  5. デリゲートキーはウォレットではありません。 オーナーが承認した Ed25519 キーペアです。保存と呼び出しはできますが、アカウントを管理することはできません。
  6. すべてのコンテンツは暗号化されます。 リレーヤーはデフォルトで Seal を使用して暗号化します。リレーヤーに平文を一切見せたくない場合は、MemWalManual を使用してください。
  7. Walrus が信頼できる唯一の情報源です。 データベースが失われた場合、restore() は Walrus からデータベースを再構築します。データベースは運用上のキャッシュです。
  8. 1 アカウントあたりのデリゲートキーは最大 20 個です。
よくある間違い
  • remember の直後、待たずに recall を呼び出す。 remember ジョブは非同期です。呼び出す前に完了を待たないと、メモリーは結果に表示されません。
  • 段落内の小さな事実を多数保存するために remember を使う。 代わりに analyze を使用してください。個々の事実を抽出してそれぞれ別に保存するため、より正確に呼び出せます。
  • ネットワークに合ったリレーヤー URL を使わず、ハードコードする。 Mainnet のアカウントはステージングリレーヤーでは機能せず、その逆も同様です。
  • Python クライアントを閉じない。 HTTP クライアントをクリーンアップするため、使用後に await memwal.close() を呼び出してください。
  • 非対話型シェルで MCP ログインを実行する。 login コマンドはブラウザーを開きます。IDE の埋め込みターミナルではなく、TTY を備えた通常のターミナルで実行してください。
  • restore() がすべての blob を一度に処理すると期待する。 設定可能な limit（デフォルト：10）があります。大規模なメモリースペースを復元するには、複数回呼び出してください。

コメント

Markdown 対応