[wrangler] Add agent_memory binding support and namespace commands

.changeset/agent-memory-binding-support.md

@@ -0,0 +1,25 @@
+---
+"miniflare": minor
+"wrangler": minor
+---
+
+Add support for `agent_memory` bindings
+
+Agent Memory bindings allow Workers to connect to Cloudflare's Agent Memory service for storing and retrieving agent conversation state. This binding is remote-only, meaning it always connects to the Cloudflare API during `wrangler dev` rather than using a local simulation.
+
+To configure an `agent_memory` binding, add the following to your `wrangler.json`:
+
+```jsonc
+{
+	"agent_memory": [
+		{
+			"binding": "MY_MEMORY",
+			"namespace": "my-namespace",
+		},
+	],
+}
+```
+
+Wrangler will automatically provision the namespace during deployment if it does not already exist. Type generation via `wrangler types` is also supported.
+
+This change also adds the `agent-memory:write` OAuth scope to Wrangler's default login scopes, so `wrangler login` can request the permissions needed to provision and manage Agent Memory namespaces.

.changeset/agent-memory-namespace-commands.md

@@ -0,0 +1,14 @@
+---
+"wrangler": minor
+---
+
+Add `wrangler agent-memory namespace` commands
+
+The following commands have been added for managing Agent Memory namespaces:
+
+```bash
+wrangler agent-memory namespace create <namespace>
+wrangler agent-memory namespace list [--json]
+wrangler agent-memory namespace get <namespace_name> [--json]
+wrangler agent-memory namespace delete <namespace_name> [--force]
+```

packages/miniflare/src/plugins/agent-memory/index.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import {
+	getUserBindingServiceName,
+	ProxyNodeBinding,
+	remoteProxyClientWorker,
+} from "../shared";
+import type { Plugin, RemoteProxyConnectionString } from "../shared";
+
+const AgentMemoryEntrySchema = z.object({
+	namespace: z.string(),
+	remoteProxyConnectionString: z
+		.custom<RemoteProxyConnectionString>()
+		.optional(),
+});
+
+export const AgentMemoryOptionsSchema = z.object({
+	agentMemory: z.record(AgentMemoryEntrySchema).optional(),
+});
+
+export const AGENT_MEMORY_PLUGIN_NAME = "agent-memory";
+
+const AGENT_MEMORY_SCOPE = "agent-memory";
+
+export const AGENT_MEMORY_PLUGIN: Plugin<typeof AgentMemoryOptionsSchema> = {
+	options: AgentMemoryOptionsSchema,
+	async getBindings(options) {
+		if (!options.agentMemory) {
+			return [];
+		}
+
+		return Object.entries(options.agentMemory).map(([bindingName, entry]) => ({
+			name: bindingName,
+			service: {
+				name: getUserBindingServiceName(
+					AGENT_MEMORY_SCOPE,
+					bindingName,
+					entry.remoteProxyConnectionString
+				),
+			},
+		}));
+	},
+	getNodeBindings(options) {
+		if (!options.agentMemory) {
+			return {};
+		}
+
+		return Object.fromEntries(
+			Object.keys(options.agentMemory).map((bindingName) => [
+				bindingName,
+				new ProxyNodeBinding(),
+			])
+		);
+	},
+	async getServices({ options }) {
+		if (!options.agentMemory) {
+			return [];
+		}
+
+		return Object.entries(options.agentMemory).map(([bindingName, entry]) => ({
+			name: getUserBindingServiceName(
+				AGENT_MEMORY_SCOPE,
+				bindingName,
+				entry.remoteProxyConnectionString
+			),
+			worker: remoteProxyClientWorker(
+				entry.remoteProxyConnectionString,
+				bindingName
+			),
+		}));
+	},
+};

packages/miniflare/src/plugins/index.ts

@@ -1,3 +1,4 @@
+import { AGENT_MEMORY_PLUGIN, AGENT_MEMORY_PLUGIN_NAME } from "./agent-memory";
 import { AI_PLUGIN, AI_PLUGIN_NAME } from "./ai";
 import { AI_SEARCH_PLUGIN, AI_SEARCH_PLUGIN_NAME } from "./ai-search";
 import {
@@ -66,6 +67,7 @@ export const PLUGINS = {
 	[EMAIL_PLUGIN_NAME]: EMAIL_PLUGIN,
 	[ANALYTICS_ENGINE_PLUGIN_NAME]: ANALYTICS_ENGINE_PLUGIN,
 	[AI_PLUGIN_NAME]: AI_PLUGIN,
+	[AGENT_MEMORY_PLUGIN_NAME]: AGENT_MEMORY_PLUGIN,
 	[AI_SEARCH_PLUGIN_NAME]: AI_SEARCH_PLUGIN,
 	[BROWSER_RENDERING_PLUGIN_NAME]: BROWSER_RENDERING_PLUGIN,
 	[DISPATCH_NAMESPACE_PLUGIN_NAME]: DISPATCH_NAMESPACE_PLUGIN,
@@ -135,6 +137,7 @@ export type WorkerOptions = z.input<typeof CORE_PLUGIN.options> &
 	z.input<typeof SECRET_STORE_PLUGIN.options> &
 	z.input<typeof ANALYTICS_ENGINE_PLUGIN.options> &
 	z.input<typeof AI_PLUGIN.options> &
+	z.input<typeof AGENT_MEMORY_PLUGIN.options> &
 	z.input<typeof AI_SEARCH_PLUGIN.options> &
 	z.input<typeof BROWSER_RENDERING_PLUGIN.options> &
 	z.input<typeof DISPATCH_NAMESPACE_PLUGIN.options> &
@@ -226,6 +229,7 @@ export * from "./secret-store";
 export * from "./email";
 export * from "./analytics-engine";
 export * from "./ai";
+export * from "./agent-memory";
 export * from "./ai-search";
 export * from "./browser-rendering";
 export * from "./dispatch-namespace";

packages/workers-utils/src/config/config.ts

@@ -336,6 +336,7 @@ export const defaultWranglerConfig: Config = {
 	vectorize: [],
 	ai_search_namespaces: [],
 	ai_search: [],
+	agent_memory: [],
 	hyperdrive: [],
 	workflows: [],
 	secrets_store_secrets: [],

packages/workers-utils/src/config/environment.ts

@@ -1052,6 +1052,24 @@ export interface EnvironmentNonInheritable {
 		remote?: boolean;
 	}[];
 
+	/**
+	 * Specifies Agent Memory namespace bindings that are bound to this Worker environment.
+	 *
+	 * NOTE: This field is not automatically inherited from the top level environment,
+	 * and so must be specified in every named environment.
+	 *
+	 * @default []
+	 * @nonInheritable
+	 */
+	agent_memory: {
+		/** The binding name used to refer to the Agent Memory namespace in the Worker. */
+		binding: string;
+		/** The user-chosen namespace name. Must exist in Cloudflare at deploy time. */
+		namespace: string;
+		/** Whether the Agent Memory binding should be remote in local development */
+		remote?: boolean;
+	}[];
+
 	/**
 	 * Specifies Hyperdrive configs that are bound to this Worker environment.
 	 *

packages/workers-utils/src/config/validation.ts

@@ -82,6 +82,7 @@ export type ConfigBindingFieldName =
 	| "vectorize"
 	| "ai_search_namespaces"
 	| "ai_search"
+	| "agent_memory"
 	| "hyperdrive"
 	| "r2_buckets"
 	| "logfwdr"
@@ -124,6 +125,7 @@ export const friendlyBindingNames: Record<ConfigBindingFieldName, string> = {
 	vectorize: "Vectorize Index",
 	ai_search_namespaces: "AI Search Namespace",
 	ai_search: "AI Search Instance",
+	agent_memory: "Agent Memory",
 	hyperdrive: "Hyperdrive Config",
 	r2_buckets: "R2 Bucket",
 	logfwdr: "logfwdr",
@@ -181,6 +183,7 @@ const bindingTypeFriendlyNames: Record<Binding["type"], string> = {
 	vectorize: "Vectorize Index",
 	ai_search_namespace: "AI Search Namespace",
 	ai_search: "AI Search Instance",
+	agent_memory: "Agent Memory",
 	hyperdrive: "Hyperdrive Config",
 	service: "Worker",
 	fetcher: "Service Binding",
@@ -1756,6 +1759,16 @@ function normalizeAndValidateEnvironment(
 			validateBindingArray(envName, validateAISearchBinding),
 			[]
 		),
+		agent_memory: notInheritable(
+			diagnostics,
+			topLevelEnv,
+			rawConfig,
+			rawEnv,
+			envName,
+			"agent_memory",
+			validateBindingArray(envName, validateAgentMemoryBinding),
+			[]
+		),
 		hyperdrive: notInheritable(
 			diagnostics,
 			topLevelEnv,
@@ -3024,6 +3037,7 @@ const validateUnsafeBinding: ValidatorFn = (diagnostics, field, value) => {
 			"ai",
 			"ai_search_namespace",
 			"ai_search",
+			"agent_memory",
 			"kv_namespace",
 			"durable_object_namespace",
 			"d1_database",
@@ -4173,6 +4187,40 @@ const validateAISearchBinding: ValidatorFn = (diagnostics, field, value) => {
 	return isValid;
 };
 
+const validateAgentMemoryBinding: ValidatorFn = (diagnostics, field, value) => {
+	if (typeof value !== "object" || value === null) {
+		diagnostics.errors.push(
+			`"agent_memory" bindings should be objects, but got ${JSON.stringify(value)}`
+		);
+		return false;
+	}
+	let isValid = true;
+	if (!isRequiredProperty(value, "binding", "string")) {
+		diagnostics.errors.push(
+			`"${field}" bindings should have a string "binding" field but got ${JSON.stringify(value)}.`
+		);
+		isValid = false;
+	}
+	if (!isRequiredProperty(value, "namespace", "string")) {
+		diagnostics.errors.push(
+			`"${field}" bindings must have a "namespace" field but got ${JSON.stringify(value)}.`
+		);
+		isValid = false;
+	}
+
+	if (!isRemoteValid(value, field, diagnostics)) {
+		isValid = false;
+	}
+
+	validateAdditionalProperties(diagnostics, field, Object.keys(value), [
+		"binding",
+		"namespace",
+		"remote",
+	]);
+
+	return isValid;
+};
+
 const validateHyperdriveBinding: ValidatorFn = (diagnostics, field, value) => {
 	if (typeof value !== "object" || value === null) {
 		diagnostics.errors.push(

packages/workers-utils/src/map-worker-metadata-bindings.ts

@@ -299,6 +299,16 @@ export function mapWorkerMetadataBindings(
 							},
 						];
 						break;
+					case "agent_memory": {
+						configObj.agent_memory = [
+							...(configObj.agent_memory ?? []),
+							{
+								binding: binding.name,
+								namespace: binding.namespace,
+							},
+						];
+						break;
+					}
 					case "hyperdrive":
 						configObj.hyperdrive = [
 							...(configObj.hyperdrive ?? []),

packages/workers-utils/src/types.ts

@@ -8,6 +8,7 @@ import type {
 } from "./config/environment";
 import type {
 	CfAIBinding,
+	CfAgentMemory,
 	CfAISearch,
 	CfAISearchNamespace,
 	CfAnalyticsEngineDataset,
@@ -73,6 +74,7 @@ export type WorkerMetadataBinding =
 	| { type: "data_blob"; name: string; part: string }
 	| { type: "ai_search_namespace"; name: string; namespace: string }
 	| { type: "ai_search"; name: string; instance_name: string }
+	| { type: "agent_memory"; name: string; namespace: string }
 	| { type: "kv_namespace"; name: string; namespace_id: string; raw?: boolean }
 	| { type: "media"; name: string }
 	| {
@@ -334,6 +336,7 @@ export type Binding =
 	| ({ type: "vectorize" } & BindingOmit<CfVectorize>)
 	| ({ type: "ai_search_namespace" } & BindingOmit<CfAISearchNamespace>)
 	| ({ type: "ai_search" } & BindingOmit<CfAISearch>)
+	| ({ type: "agent_memory" } & BindingOmit<CfAgentMemory>)
 	| ({ type: "hyperdrive" } & BindingOmit<CfHyperdrive>)
 	| ({ type: "service" } & BindingOmit<CfService>)
 	| { type: "fetcher"; fetcher: ServiceFetch }

packages/workers-utils/src/worker.ts

@@ -242,6 +242,12 @@ export interface CfAISearch {
 	remote?: boolean;
 }
 
+export interface CfAgentMemory {
+	binding: string;
+	namespace: string | typeof INHERIT_SYMBOL;
+	remote?: boolean;
+}
+
 export interface CfSecretsStoreSecrets {
 	binding: string;
 	store_id: string;