← Agent Memory / agent-memory / api

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 string required: 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 string required: 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 | null optional: 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 string required: Memory content to store. The service classifies and summarizes automatically.
• memory.sessionId string | null optional: 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 string required: 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 | string optional: 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 number optional (default: 20, max: 500): Maximum number of memories to return.
• options.cursor string optional: Opaque cursor from a previous page.
• options.sessionId string optional: 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 string required: 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 string required: 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 string required: 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 | null optional: 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.