Workers API

Worker から Agent Memory にアクセスするには、Workers API を使います。バインディングは、Worker を namespace に接続します。namespace には、エージェント用の分離されたメモリストアであるプロファイルが含まれます。

Wrangler の設定に agent_memory エントリを追加します。binding は Worker コードで使う変数名、namespace はバインド先の Agent Memory namespace です。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "agent_memory": [
    {
      "binding": "MEMORY",
      "namespace": "<NAMESPACE_NAME>"
    }
  ]
}

[[agent_memory]]
binding = "MEMORY"
namespace = "<NAMESPACE_NAME>"

複数の namespace をバインドするには、agent_memory 配列にエントリを追加します。

npx wrangler types を実行すると、worker-configuration.d.ts にバインディングの型が生成されます。

interface Env {
	MEMORY: AgentMemoryNamespace;
}

バインディングの namespace メソッドで、メモリプロファイルにアクセスし、管理します。

名前でメモリプロファイルを取得します。プロファイルが存在しない場合、Agent Memory が作成します。

• profileName string 必須: アクセスするプロファイル名。最大 100 文字。
• 戻り値 Promise<AgentMemoryProfile>

新しいプロファイルに対する最初の getProfile() は、Agent Memory がプロファイルを作成するため、時間がかかることがあります。

プロファイルと、そのメモリおよびメッセージをすべて削除対象としてマークします。

• profileName string 必須: 削除するプロファイル名。最大 100 文字。
• 戻り値 Promise<void>

バインディングからプロファイルを取得したあと、プロファイルのメソッドを呼び出します。

type AgentMemoryMemory = {
	id: string;
	type: "fact" | "event" | "instruction" | "task";
	summary: string;
	content: string;
	sessionId: string | null;
	createdAt: Date;
	updatedAt: Date;
};

会話を処理し、構造化されたメモリを抽出します。Agent Memory は fact、event、instruction、task を自動で識別するため、何を覚えるかを指定する必要はありません。

• messages Iterable<AgentMemoryMessage> 必須: 処理する会話メッセージ。
• options.sessionId string | null 任意: 会話セッションの識別子。最大 64 文字。省略すると、Agent Memory がメッセージ内容から導出します。
• 戻り値 Promise<void>

type AgentMemoryMessage = {
	role: "system" | "user" | "assistant";
	content: string; // Max 32 KB
	timestamp?: Date;
};

ingest() はべき等です。同じ会話を再取り込みしても、重複メモリは作りません。

メモリを1件、明示的に保存します。会話を ingest() に渡して抽出するのではなく、アプリケーションやエージェントが保存すべき内容をすでに把握しているときに remember() を使います。

• memory.content string 必須: 保存するメモリの内容。サービスが自動で分類と要約を行います。
• memory.sessionId string | null 任意: 関連する会話セッションの識別子。
• 戻り値 Promise<AgentMemoryMemory>

プロファイル内の保存済みメモリを検索し、保存内容に基づいて合成した回答を返します。

• query string 必須: 自然言語の質問または検索クエリ。最大 1 KB（1,024 バイト UTF-8）。
• options.thinkingLevel "low" | "medium" | "high" 任意（デフォルト: "low"）: 検索の幅を制御します。高いレベルほど候補を多く探しますが、時間がかかります。
• options.responseLength "short" | "medium" | "long" 任意（デフォルト: "medium"）: 合成回答の詳しさを制御します。
• options.referenceDate Date | string 任意: 日付相対のクエリに使う時間的な基準点です。
• 戻り値 Promise<AgentMemoryRecallResult>

type AgentMemoryRecallResult = {
	count: number;
	answer: string;
	candidates: AgentMemoryScoredCandidate[];
};

type AgentMemoryScoredCandidate = {
	id: string;
	summary: string;
	sessionId: string | null;
	score: number;
};

クエリに一致するメモリがない場合、recall() は空の回答を返します。

プロファイルに保存されているメモリを一覧します。ページ分割とフィルタが可能な一覧を返します。次のページを取得するには、返された cursor（ある場合）を使います。

• options.limit number 任意（デフォルト: 20、最大: 500）: 返すメモリの最大数。
• options.cursor string 任意: 前のページから得た不透明なカーソル。
• options.sessionId string 任意: セッションの完全一致フィルタ。
• options.type "fact" | "event" | "instruction" | "task" 任意: メモリタイプの完全一致フィルタ。
• 戻り値 Promise<AgentMemoryListMemoriesResult>

type AgentMemoryMemoryListEntry = Omit<AgentMemoryMemory, "content">;

type AgentMemoryListMemoriesResult = {
	memories: AgentMemoryMemoryListEntry[];
	cursor?: string;
};

一覧エントリには content が含まれません。メモリ全体を取得するには get(memoryId) を使います。

ID でメモリを取得します。

• memoryId string 必須: メモリ ID。
• 戻り値 Promise<AgentMemoryMemory>

メモリが存在しない場合はエラーを投げます。

ID でメモリを削除します。メモリと、それに紐づくソースメッセージを削除します。削除したメモリを返します。

• memoryId string 必須: メモリ ID。
• 戻り値 Promise<AgentMemoryMemory>

メモリが存在しない場合はエラーを投げます。

指定したセッション ID が付いた、プロファイル内のすべてのメモリとメッセージを削除対象としてマークします。同じプロファイル内の他セッションの行は変更しません。べき等です。該当行がないセッション ID を削除しても何も起きません。

• sessionId string 必須: 削除するセッション ID。最大 64 文字。
• 戻り値 Promise<void>

メモリプロファイルに保存されている内容全体の、構造化された Markdown 要約を生成します。Agent Memory がそのプロファイルについて覚えている内容を確認するときに使います。

• options.sessionId string | null 任意: 要約の「Last Session」セクションの対象にするセッション ID。省略すると、Agent Memory は最新のセッションを使います。
• 戻り値 Promise<AgentMemoryGetSummaryResponse>

type AgentMemoryGetSummaryResponse = {
	summary: string;
};

制約の全体は 制限 を参照してください。