Workers API

Use the Workers API to access Agent Memory from your Worker. The binding connects your Worker to a namespace containing profiles, which are isolated memory stores for your agent.

Add an agent_memory entry to your Wrangler configuration. The binding field is the variable name you use in Worker code, and the namespace field is the Agent Memory namespace to bind to.

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

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

To bind multiple namespaces, add multiple entries to the agent_memory array.

Run npx wrangler types to generate the binding type in worker-configuration.d.ts:

interface Env {
	MEMORY: AgentMemoryNamespace;
}

Use namespace methods on the binding to access and manage memory profiles.

Gets a memory profile by name. If the profile does not exist, Agent Memory creates it.

• profileName stringrequired: Name of the profile to access. Maximum 100 characters.
• Returns Promise<AgentMemoryProfile>

The first getProfile() call for a new profile may take longer while Agent Memory creates the profile.

Marks a profile and all its memories and messages for deletion.

• profileName stringrequired: Name of the profile to delete. Maximum 100 characters.
• Returns Promise<void>

Call profile methods after you get a profile from the binding.

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

Processes a conversation and extracts structured memories from it. Agent Memory identifies facts, events, instructions, and tasks automatically, so you do not need to specify what to remember.

• messages Iterable<AgentMemoryMessage>required: Conversation messages to process.
• options.sessionId string | nulloptional: Identifier for the conversation session. Maximum 64 characters. If omitted, Agent Memory derives one from the message content.
• Returns Promise<void>

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

ingest() is idempotent. Re-ingesting the same conversation does not create duplicate memories.

Stores a single memory explicitly. Use remember() when your application or agent already knows what should be stored, instead of passing a conversation to ingest() for extraction.

• memory.content stringrequired: Memory content to store. The service classifies and summarizes automatically.
• memory.sessionId string | nulloptional: Identifier for the related conversation session.
• Returns Promise<AgentMemoryMemory>

Searches stored memories in the profile and returns a synthesized answer grounded in the stored content.

• query stringrequired: Natural language question or search query. Maximum 1 KB (1,024 bytes UTF-8).
• options.thinkingLevel "low" | "medium" | "high"optional (default: "low"): Controls retrieval breadth. Higher levels search more candidates but take longer.
• options.responseLength "short" | "medium" | "long"optional (default: "medium"): Controls the verbosity of the synthesized answer.
• options.referenceDate Date | stringoptional: Temporal anchor for date-relative queries.
• Returns Promise<AgentMemoryRecallResult>

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

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

If no memories match the query, recall() returns an empty answer.

Lists memories stored in the profile. Returns a paginated, filterable view of stored memories. Use the returned cursor (when present) to fetch the next page.

• options.limit numberoptional (default: 20, max: 500): Maximum number of memories to return.
• options.cursor stringoptional: Opaque cursor from a previous page.
• options.sessionId stringoptional: Exact-match session filter.
• options.type "fact" | "event" | "instruction" | "task"optional: Exact-match memory-type filter.
• Returns Promise<AgentMemoryListMemoriesResult>

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

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

List entries omit content. Use get(memoryId) to retrieve the full memory.

Retrieves a memory by ID.

• memoryId stringrequired: Memory ID.
• Returns Promise<AgentMemoryMemory>

Throws an error if the memory does not exist.

Deletes a memory by ID. Removes the memory and any source messages linked to it. Returns the deleted memory.

• memoryId stringrequired: Memory ID.
• Returns Promise<AgentMemoryMemory>

Throws an error if the memory does not exist.

Marks all memories and messages in the profile that are tagged with the given session ID for deletion. Rows from other sessions in the same profile are untouched. Idempotent: deleting a session ID that has no rows is a no-op.

• sessionId stringrequired: Session ID to delete. Maximum 64 characters.
• Returns Promise<void>

Generates a structured Markdown summary of everything stored in a memory profile. Use it to inspect what Agent Memory remembers about a profile.

• options.sessionId string | nulloptional: Session ID to scope the "Last Session" section of the summary. If omitted, Agent Memory uses the most recent session.
• Returns Promise<AgentMemoryGetSummaryResponse>

type AgentMemoryGetSummaryResponse = {
	summary: string;
};

Refer to Limits for the complete list of constraints.