add-agent-memory

エージェントメモリを追加する

モデルの実行前に、ユーザーについて把握していることを思い出します。ターンの後に、やり取りを書き戻します。このサービスは、セッションから長期メモリを抽出します。何を記憶し、共有し、除外し、保持するかはサービスの設定であり、SDK の引数ではありません。まず確認してからプロビジョニングし、その後に接続してください。

1. 調査する

プロジェクトを確認します。

• ターン（モデルが呼び出される場所）と、その時点で対象となるユーザー ID、およびセッション ID またはスレッド ID を見つけます。
• インポートからフレームワークを特定します。
• 既存のメモリコード（BaseStore、InMemoryStore、カスタムの辞書または DB）を見つけます。グラフではなく、その読み書きを置き換えます。
• 独自のクライアントを使って、すでに Redis Agent Memory を利用していますか？変更前に、以下をすべて確認します。生成された redis_agent_memory クライアントのアダプター、モデルにメモリツールを公開する MCP クライアント、すべてのレコードに書き込まれる namespace 文字列、同じストアに書き込む別のランタイムやフレームワークプラグインです。ステップ 4 の「すでに Redis Agent Memory を利用している場合」を参照してください。
• 非同期エージェントですか？a が先頭に付くメソッドを使用します。

次に、開発者には以下の5つの質問だけをします。それ以外は質問しません。回答が曖昧な場合は、デフォルトを使用します。

質問	回答	設定
セッションをまたいで、エージェントはユーザーについて何を記憶すべきですか？	自由形式の事実や好み（デフォルト）	不要です。組み込みの semantic と episodic タイプで対応できます
	構造化された業務データ：旅行の要件、注文の制約、アカウントの設定	名前付きの fields と抽出用の prompt を含む memory_types エントリーを1つ設定します
すべての会話で参照すべきナレッジはありますか？	インシデント、一時的なポリシー、チームのメモ	memory.shared_namespace("<name>") を設定します。運用担当者が remember(..., namespace_id=...) で書き込み、エージェントは recall(shared=[...]) で読み取ります
	いいえ（デフォルト）	ネームスペースを省略します
決して保持してはならない情報は何ですか？	パスワード、トークン、カード番号、確認コード、健康データ	それぞれを指定する exclusions.prompt を設定します。これはガイダンスであり、保証ではありません。セッションの内容は引き続きモデルプロバイダーに送信され、remember() による直接書き込みでは除外が適用されません
メモリをどのくらいの期間保持しますか？	セッション TTL、長期 TTL（デフォルトは30日／365日）	short_term_ttl、long_term_ttl
リクエストに応じてユーザーの情報を忘れる必要がありますか？	はい	消去処理で memory.forget(owner) を呼び出します

長時間のセッション（サポートスレッド、数時間にわたるチャット）では、after_messages: 20、keep_recent: 10 を指定して summarization を有効にしたままにします。

2. MCP から最新情報を取得する

コードを書く前に実行します。フレームワークの API を記憶に頼って推測してはいけません。

• フレームワークのドキュメント：利用可能なドキュメント MCP（Context7、または LangChain のものなど、フレームワーク独自のドキュメント MCP）に問い合わせて、インストール済みバージョンの動的なシステムプロンプトまたは指示、モデルの呼び出し前後のコールバック、実行コンテキスト（ツールまたはコールバックがユーザー ID を取得する方法）を確認します。
• Redis のドキュメント：Redis のドキュメント MCP に接続できる場合は、Agent Memory の概念（セッション、長期メモリ、ネームスペース、カスタムメモリタイプ、除外）について search／fetch／ask を使用します。
• MCP を利用できない場合：仮想環境内のインストール済みパッケージのソースを確認します。その旨を報告書に記載します。

3. 設定する

回答をもとに service.yaml を作成します。これをコミットしてください。サービスのレビュー可能な記録になります。

name: support-memory
# database: "1"                # the default on-prem; the registered database id the store lives in
short_term_ttl: 30d
long_term_ttl: 365d
# extraction_cadence: 60s      # the default (60s to 600s); raise it to spend less on extraction
summarization: {enabled: true, after_messages: 20, keep_recent: 10}
exclusions: {prompt: "Do not keep passwords, access tokens, recovery codes, payment card information, or booking confirmation codes in long-term memory."}
memory_types:                  # only when question 1 named structured data
  - name: trip_preference
    description: Structured requirements for a planned trip
    prompt: Extract trip requirements only when the user states a destination or travel plan.
    enabled: true
    fields: {destinations: "list[str]", travel_period: str, dietary_requirements: "list[str]"}

ターミナルからプロビジョニングします。

iris --json --no-input agent-memory service create --from service.yaml --dry-run
iris --json --no-input agent-memory service create --from service.yaml --write-env .env
iris --json --no-input agent-memory service check <storeId from the result> --env-file .env

スタック	実行前の準備
ローカルのオンプレミス（Agent Memory サービス http://127.0.0.1:9100、Agent Memory URL http://127.0.0.1:9000）	--local を追加します
セルフマネージドスイート	担当者が IRIS_AGENT_MEMORY_SERVICE_TOKEN、IRIS_IDENTITY_TOKEN、およびマルチテナントの Identity Service では IRIS_IDENTITY_TENANT をエクスポートします。URL は IRIS_AGENT_MEMORY_SERVICE_URL、IRIS_AGENT_MEMORY_URL、IRIS_IDENTITY_URL、またはプロファイルから取得します。以下の「Identity トークン」を参照してください
Redis Cloud	サービスコマンドは cloud_unsupported を返します。以下のコンソールに関する注記を参照してください

Identity トークン。 各製品のチャートで、独自の Identity Service を実行できます。その場合は、製品固有の IRIS_AGENT_MEMORY_IDENTITY_TOKEN（および IRIS_AGENT_MEMORY_IDENTITY_URL、またはプロファイルの identity_url）を設定し、IRIS_IDENTITY_URL は未設定にしてください。この値は、プロファイル内のすべての製品の identity_url を上書きします。Identity Service を共有するスイートでは、IRIS_IDENTITY_TOKEN と IRIS_IDENTITY_URL で、すべての製品をカバーできます。CLI は、--identity-token、IRIS_AGENT_MEMORY_IDENTITY_TOKEN、IRIS_IDENTITY_TOKEN、製品のサービス トークンの順にトークンを取得します。最後の方法が機能するのは、2 つのトークンが同じシークレットの場合のみです。ドライランでは、このフォールバックが warnings に表示されます。

プロジェクトの iris.toml を用意します。iris.toml を読み取るのは iris CLI のみで、アプリは環境変数を読み取ります。ここには URL のみを記述します。TOML にトークンが含まれていると、CLI は終了コード 2 で終了します。プロファイルは IRIS_CONFIG=./iris.toml と IRIS_PROFILE=cloud または IRIS_PROFILE=suite で選択します。

Redis Cloud。担当者がコンソールを参照して .env に IRIS_AGENT_MEMORY_URL、IRIS_AGENT_MEMORY_STORE_ID、IRIS_AGENT_MEMORY_API_KEY を設定します。

[profiles.cloud]
kind = "cloud"
console_url = "https://cloud.redis.io"

[profiles.cloud.agent_memory]
url = "https://gcp-us-east4.memory.redis.io"  # the data-plane URL from the console

セルフマネージドスイート。オペレーターのトークンは .env.admin に設定し、アプリの .env には決して設定しません。service create --write-env .env はアプリの .env に書き込みます。

[profiles.suite]
kind = "self-managed"

[profiles.suite.agent_memory]
service_url = "https://memory-admin.example.com"  # control plane: the CLI calls it for service create and check
url = "https://memory.example.com"  # data plane: what the agent calls
identity_url = "https://memory-identity.example.com"  # Identity Service that mints the agent's keys

Identity Service を共有するスイートでは、各 identity_url ではなく、[profiles.suite.identity] の url を一度だけ設定します。IRIS_<PRODUCT>_SERVICE_URL、IRIS_<PRODUCT>_URL、IRIS_<PRODUCT>_IDENTITY_URL はプロファイルを上書きします。

エージェントとして CLI を実行する

実行する iris の呼び出しは、すべて同じ手順に従います。

1. 製品名の前に必ず --json --no-input を付けます。標準出力には 1 つの JSON 値が、エラーは標準エラー出力に 1 つの JSON 値として出力され、プロンプトは表示されません。
2. まずドライランを実行します。service create ... --dry-run は何も送信せず、実行に必要なすべての認証情報または URL を missing に一覧表示します。missing が空でない場合は停止し、書き込みを行う前に手順 4 に従って引き継ぎます。warnings に記載された内容（テナントのない権限付与、または Identity Service のトークンとしてサービス トークンが使用されること）は、実行前に担当者に伝えます。
3. キーは必ず --write-env PATH（または key で --write PATH）を指定して渡します。ファイルを指定せずに create または key を --json で実行してはいけません。キーが標準出力とトランスクリプトに出力されます。
4. credential_required が発生したら停止します。どの製品とプロファイルに対してどの変数（details.env）を設定するかを担当者に伝え、details.obtain のリンクを共有します。unauthenticated または forbidden の場合は、どの値が拒否されたか（details.source）を伝えます。チャットでシークレットを尋ねたり、コマンドラインで渡したり、環境ファイルを出力したり、cat や grep で読み取ったりしてはいけません。
5. プロビジョニング後、service check ID --env-file .env を実行します（create が書き込んだファイルを使用します。キーはシェルに出力されません）。各ステップの結果を報告します。失敗した場合は推測せず、失敗した接続先（details.hop、details.step、details.cause）を報告します。
6. resource_exists が発生したら、details.id を --reuse で再利用するか、別の名前を選ぶか、担当者に確認します。再試行のために削除してはいけません。create が details.created: true で失敗した場合、リソースは存在しますが、まだキーがありません。--reuse --write-env を付けて再実行します。

すべてのエラーは、error.code を含む 1 つの JSON 値として標準エラー出力に出力されます。認証情報に関するエラーには、値ではなく details.env と details.obtain も含まれます。最初の失敗で停止し、その内容を伝えます。

error.code	担当者	対応
credential_required	担当者	エージェントのシェルで、details.env に記載された変数を設定します。前述の「ID トークン」を参照してください。
unauthenticated	担当者	details.source のトークンが拒否されました。有効期限が切れているか、別のデプロイメントに属しています。新しいトークンを発行してください。
forbidden	担当者	トークンは有効ですが、必要なロールまたはテナントがありません。その製品に適したロールを持つトークンを使用してください。
configuration_error	担当者またはエージェント	url などの URL が設定されていません。プロファイルに追加してください。
invalid_request	エージェント	HTTP 400 です。メッセージで指定されたリクエストを修正してください。
resource_exists	担当者	次のどちらかを選択してください。--reuse を付けて再実行し、details.id を引き継ぐか、別の名前を選択します。
unavailable	担当者	ホップに到達できません。URL、イングレス、サービスのポッドを確認してください。
check_failed	担当者	details.hop と details.cause に、問題のあるホップが示されています。修正してからチェックを再実行してください。
cloud_unsupported	担当者	プロファイルは kind = "cloud" です。コンソールで details.steps に記載された手順に従ってください。
input_error、usage_error	エージェント	コマンドを修正してください。--no-input のときに破壊的なコマンドを実行するには、担当者が --yes を指定する必要があります。

--write-env .env を実行すると、IRIS_AGENT_MEMORY_URL、IRIS_AGENT_MEMORY_STORE_ID、IRIS_AGENT_MEMORY_API_KEY が書き込まれます。同じ3つの名前を、空の値で .env.example に追加してください。.env は絶対にコミットしないでください。後から実行する場合は、iris agent-memory service list | show STORE_ID | env STORE_ID [--write PATH] を使用します（ローカルスタックの場合は --local を追加します）。

Agent Memory サービスにアクセスできない場合、または Redis Cloud を使用している場合は、担当者が Redis Cloud コンソールでサービスを作成します。Iris → Agent Memory → New service の順に選択します。Service name を入力し、Database を選択します。Customize settings では、TTL、抽出間隔、要約、カスタムメモリータイプ、除外項目を設定します。次に、ストアの Configuration タブにある URL List から Store ID と URL をコピーし、Iris → Access & Identity でストアへのアクセス権を持つ API キーを作成します。API キーは一度だけ表示されます。

コンソール	環境変数	必須
URL List	IRIS_AGENT_MEMORY_URL	はい
Store ID	IRIS_AGENT_MEMORY_STORE_ID	はい
API key	IRIS_AGENT_MEMORY_API_KEY	はい
	IRIS_AGENT_MEMORY_TIMEOUT	いいえ、秒単位、デフォルトは 30

起動時に一度作成します。

from redis_iris import AgentMemory

memory = AgentMemory.from_env(assistant_id="<agent-name>")
floor = memory.shared_namespace("<team-namespace>")  # question 2: memories every user may read

4. 2 つの接点をつなぐ

モデルの前（コンテキストの読み込み）：

known = memory.recall(question, owner=user_id, shared=[floor])  # await memory.arecall(...)
system_prompt = f"{system_prompt}\n\n{known.as_prompt()}"

ターンの後（書き戻し）：

convo = memory.conversation(owner=user_id, session_id=thread_id)  # session_id optional
convo.user(question)  # await convo.auser(...)
convo.assistant(answer)  # await convo.aassistant(...)

明示的な事実の記録：memory.remember(text, owner=user_id, topics=[...])。消去（質問 5）：memory.forget(user_id) は Forgotten(owner, sessions, memories) を返します。それ以外の場合：memory.client。

どの行でも、フレームワーク固有の処理はなく、同じ 2 つの呼び出しを行います。hooks = memory.hooks(shared=[...]) を実行し、返信後に hooks.before(message, owner=user_id) をシステムプロンプトに渡し、hooks.after(message, answer, owner=user_id, session=thread_id) を呼び出します（非同期コードでは abefore / aafter）。それぞれの配置場所については、手順 2 で名前を確認してください。

フレームワーク	モデルの前	ターンの後	ツール（任意の remember）
LangGraph (StateGraph)	redis_iris.integrations.langgraph の attach(memory, graph)（追加パッケージ redis-iris[langgraph]）が、compile() の前に両方の接点を処理します。owner と thread は configurable.user_id / thread_id から取得します。手動で配線する場合は、モデルの前にノードを配置します	attach に含まれます。含まれない場合は、モデルの後にノードを配置します	@tool / StructuredTool
OpenAI Agents SDK	動的な instructions callable	Runner.run の戻り後、または run hooks	@function_tool / FunctionTool
Google ADK (LlmAgent)	redis_iris.integrations.adk の attach(memory, agent)（追加パッケージ不要）が、エージェント独自のコールバックより前に両方のモデルコールバックを追加します。owner と session は呼び出しの user_id と session.id から取得します	attach に含まれます。最終返信時に一度だけ記録されます	FunctionTool
Pydantic AI	動的な @agent.system_prompt。ユーザー ID は deps に指定します	agent.run の戻り後	Tool / @agent.tool
CrewAI	kickoff の前に task または agent の入力へ挿入します	kickoff の戻り後、または task_callback	@tool / BaseTool
シンプルなループ	モデル呼び出しの前	モデル呼び出しの後	リクエスト内の関数定義

置き換えたメモリコードを削除します。グラフがスレッド状態に使用している場合は、チェックポインターを残してください。

すでに Redis Agent Memory を使用している場合

ストアはそのままにして、クライアントを変更します。プロジェクトで既存のセッションを引き続き利用できるよう、既存の owner ID と session ID の導出方法を維持してください。

• 過去のターンをメッセージとして扱う場合。 エージェントがこれまでのセッションをモデルに渡す場合は、memory.conversation(owner=user_id, session_id=thread_id).transcript() が turns を (role, text) として、また summary を返します。summary は最初のシステムメッセージとして配置してください。事実のみが必要な場合は、recall で十分です。
• 2 つの書き込み元を 1 つにまとめます。 モデル向けのメモリツール（create、search、edit、delete）と、サービス独自の抽出処理は、どちらも長期メモリに書き込みます。デフォルトではツールを削除し、事前に recall して返信後に記録し、サービスに抽出させます。評価の結果、明示的な書き込みが重要だと示された場合に限り、remember ツールを残してください。
• レコードの namespace 文字列は非推奨のフィールドです。 読み取りは owner でスコープされます。共有には shared_namespace で作成した namespace を使います。定数を削除する前に、recall(owner=...) が既存のレコードを返すことを確認してください。また、同じ環境で旧経路と新経路を同時に実行しないでください。文字列でフィルタリングするクライアントからは、新しい経路で書き込まれた内容が見えません。
• エージェントが値を必要とする場合は、文字列ではなく値を使用します。 hooks() はプロンプトブロックを生成します。キャッシュされた回答をメモリと照合するエージェントや、想起した内容の件数を数えるエージェントは、recall() と transcript() を直接呼び出します。
• 障害時のポリシー。 SDK は例外を発生させます。メモリ停止中もエージェントが回答する必要がある場合は、呼び出しごとに例外を捕捉し、空のブロックで処理を続けてください。

5. 検証

1. iris agent-memory service show $IRIS_AGENT_MEMORY_STORE_ID を実行すると、service.yaml の TTL、要約、除外項目、メモリーの種類が出力されます。
2. メモリーを1つシードします：memory.remember("Prefers email.", owner="<test-user>")。
3. <test-user> としてエージェントを1回実行します。
4. memory.recall("contact", owner="<test-user>").as_prompt() にメモリーが表示され、モデルのプロンプトに含まれていることを確認します。
5. セッションを表示します：memory.conversation(owner="<test-user>", session_id=...).transcript().turns が空でないことを確認します。
6. 質問5の答えが「はい」だった場合：memory.forget("<test-user>") がシードした件数を報告し、2回目の recall では何も返されないことを確認します。
7. 変数の設定を解除し、ConfigurationError にその変数名が含まれていることを確認します（最初の呼び出し時に発生します）。
8. 既存のクライアントから変換します：memory.recall(<a known topic>, owner=<an existing user>) が変更前に書き込まれたメモリーを返すことを確認します。

抽出されたメモリーは抽出ウィンドウの終了後に表示されます。シードしたメモリーはすぐに表示されます。

6. 報告

5つの回答、それぞれが生成した service.yaml、変更したファイル、追加した環境変数、各シームの行き先、検証結果、MCP 経由で確認できなかった内容を列挙します。