@aws/agentcore 1.0.0-preview.3 → 1.0.0-preview.31

package/dist/assets/python/http/strands/capabilities/payments/payments.py

@@ -0,0 +1,142 @@
+"""Payment capability -- auto-generated by agentcore CLI.
+
+Configures AgentCorePaymentsPlugin for Strands agents.
+Manager config is auto-discovered from AGENTCORE_PAYMENT_*
+environment variables set at deploy time.
+
+Uses a per-invocation factory pattern so each request gets its own
+plugin instance with the correct user_id, instrument_id, and session_id.
+This prevents concurrency bugs where one user's payment context
+could leak to another user's request.
+
+Uses the official SDK plugin which handles:
+- x402 v1 (body-based) and v2 (header-based) payment detection
+- Automatic 402 response interception and payment processing
+- Retry limiting (max 3 payment retries per tool use)
+- Error management and logging
+"""
+import os
+import logging
+
+import boto3
+from bedrock_agentcore.payments.integrations.strands import AgentCorePaymentsPlugin
+from bedrock_agentcore.payments.integrations.config import AgentCorePaymentsPluginConfig
+
+logger = logging.getLogger(__name__)
+
+PAYMENT_SYSTEM_PROMPT = """
+You have payment capabilities via the x402 protocol:
+- Use http_request to call HTTP endpoints. 402 Payment Required responses are settled automatically by the plugin and the call is retried.
+- Use get_payment_session to check your remaining budget before expensive operations
+- Use get_payment_instrument_balance to check wallet USDC balance
+- Use list_payment_instruments to see available payment instruments
+- If budget is low, inform the user before proceeding with paid requests
+"""
+
+_manager_arn = None
+_connector_id = None
+_process_payment_role_arn = None
+_name_segment = None
+_region = None
+_auth_mode = None
+_manager_count = 0
+for key, value in os.environ.items():
+    if key.startswith("AGENTCORE_PAYMENT_") and key.endswith("_MANAGER_ARN"):
+        if _manager_arn is None:
+            _manager_arn = value
+            _name_segment = key[len("AGENTCORE_PAYMENT_"):-len("_MANAGER_ARN")]
+        _manager_count += 1
+if _manager_count > 1:
+    logger.warning(
+        "Multiple payment managers detected in environment. Using the first one found. "
+        "Remove extra AGENTCORE_PAYMENT_*_MANAGER_ARN env vars to eliminate ambiguity."
+    )
+_region = os.getenv("AWS_REGION")
+
+_prefix = f"AGENTCORE_PAYMENT_{_name_segment}_" if _name_segment else "AGENTCORE_PAYMENT_"
+_auth_mode = os.getenv(f"{_prefix}AUTH_MODE", "sigv4")
+_connector_id = os.getenv(f"{_prefix}CONNECTOR_ID")
+_process_payment_role_arn = os.getenv(f"{_prefix}PROCESS_PAYMENT_ROLE_ARN")
+_auto_payment = os.getenv(f"{_prefix}AUTO_PAYMENT", "true").lower() == "true"
+_allowlist_raw = os.getenv(f"{_prefix}TOOL_ALLOWLIST")
+_allowlist = _allowlist_raw.split(",") if _allowlist_raw else None
+_network_prefs_raw = os.getenv(f"{_prefix}NETWORK_PREFERENCES")
+_network_prefs = _network_prefs_raw.split(",") if _network_prefs_raw else None
+
+if not _manager_arn:
+    logger.warning("No payment manager config found in environment")
+if not _connector_id:
+    logger.warning("No payment connector config found in environment")
+
+
+def _assume_role_session(role_arn):
+    """Assume an IAM role and return a boto3 session with temporary credentials."""
+    sts = boto3.client("sts", region_name=_region)
+    creds = sts.assume_role(
+        RoleArn=role_arn,
+        RoleSessionName="agentcore-payment-plugin",
+    )["Credentials"]
+    return boto3.Session(
+        aws_access_key_id=creds["AccessKeyId"],
+        aws_secret_access_key=creds["SecretAccessKey"],
+        aws_session_token=creds["SessionToken"],
+        region_name=_region,
+    )
+
+
+def create_payments_plugin(user_id, instrument_id=None, session_id=None):
+    """Create a fresh plugin instance per invocation.
+
+    Args:
+        user_id: From invocation context (required for SigV4, derived from JWT for bearer)
+        instrument_id: From invocation payload (created by app backend per user)
+        session_id: From invocation payload (created by app backend per conversation)
+
+    Returns:
+        AgentCorePaymentsPlugin instance, or None if no manager is configured.
+    """
+    if not _manager_arn:
+        return None
+
+    config_kwargs = {
+        "payment_manager_arn": _manager_arn,
+        "region": _region,
+        "payment_instrument_id": instrument_id,
+        "payment_session_id": session_id,
+        "payment_connector_id": _connector_id,
+    }
+
+    config_kwargs["auto_payment"] = _auto_payment
+    if _allowlist:
+        config_kwargs["payment_tool_allowlist"] = _allowlist
+    if _network_prefs:
+        config_kwargs["network_preferences_config"] = _network_prefs
+
+    if _process_payment_role_arn:
+        # Only pass boto3_session if SDK supports it (added in bedrock-agentcore >= 1.11).
+        # Older SDKs use the runtime role's default credentials and can still call ProcessPayment
+        # if the runtime role has been granted permission directly.
+        import inspect
+        if "boto3_session" in inspect.signature(AgentCorePaymentsPluginConfig).parameters:
+            config_kwargs["boto3_session"] = _assume_role_session(_process_payment_role_arn)
+        else:
+            logger.warning(
+                "PROCESS_PAYMENT_ROLE_ARN set but bedrock-agentcore SDK does not support boto3_session. "
+                "Upgrade to bedrock-agentcore>=1.11 to enable cross-role payment processing."
+            )
+
+    if _auth_mode == "bearer":
+        bearer_token = os.getenv("AGENTCORE_BEARER_TOKEN")
+        if bearer_token:
+            config_kwargs["bearer_token"] = bearer_token
+        else:
+            logger.warning(
+                "Bearer auth mode configured but AGENTCORE_BEARER_TOKEN not set. "
+                "Falling back to SigV4. Set AGENTCORE_BEARER_TOKEN or pass bearer_token in invoke context."
+            )
+            config_kwargs["user_id"] = user_id or "default-user"
+    else:
+        config_kwargs["user_id"] = user_id or "default-user"
+
+    config = AgentCorePaymentsPluginConfig(**config_kwargs)
+    return AgentCorePaymentsPlugin(config=config)

package/dist/assets/python/mcp/standalone/base/main.py

@@ -1,7 +1,65 @@
+{{#if needsOs}}
+import os
+{{/if}}
 from mcp.server.fastmcp import FastMCP
 
 mcp = FastMCP("{{ name }}", host="0.0.0.0", stateless_http=True)
 
+{{#if needsOs}}
+_MOUNT_PATHS = [
+    {{#if sessionStorageMountPath}}"{{sessionStorageMountPath}}",{{/if}}
+    {{#each efsMounts}}"{{mountPath}}",{{/each}}
+    {{#each s3Mounts}}"{{mountPath}}",{{/each}}
+]
+
+def _safe_resolve(path: str) -> str:
+    resolved = os.path.realpath(path)
+    if not any(resolved == os.path.realpath(m) or resolved.startswith(os.path.realpath(m) + os.sep) for m in _MOUNT_PATHS):
+        raise ValueError(f"Path '{path}' is not within any configured mount ({', '.join(_MOUNT_PATHS)})")
+    return resolved
+
+@mcp.tool()
+def file_read(path: str) -> str:
+    """Read a file from a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."""
+    try:
+        full_path = _safe_resolve(path)
+        with open(full_path) as f:
+            return f.read()
+    except ValueError as e:
+        return str(e)
+    except OSError as e:
+        return f"Error reading '{path}': {e.strerror}"
+
+@mcp.tool()
+def file_write(path: str, content: str) -> str:
+    """Write a file to a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."""
+    try:
+        full_path = _safe_resolve(path)
+        parent = os.path.dirname(full_path)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        with open(full_path, "w") as f:
+            f.write(content)
+        return f"Written to {path}"
+    except ValueError as e:
+        return str(e)
+    except OSError as e:
+        return f"Error writing '{path}': {e.strerror}"
+
+@mcp.tool()
+def list_files(path: str) -> str:
+    """List files in a mounted filesystem directory. Use the absolute path (e.g. /mnt/tools)."""
+    try:
+        full_path = _safe_resolve(path)
+        entries = os.listdir(full_path)
+        return "\n".join(entries) if entries else "(empty directory)"
+    except ValueError as e:
+        return str(e)
+    except OSError as e:
+        return f"Error listing '{path}': {e.strerror}"
+
+{{/if}}
+
 
 @mcp.tool()
 def add_numbers(a: int, b: int) -> int:

package/dist/assets/python/mcp/standalone/base/pyproject.toml

@@ -9,7 +9,7 @@ description = "AgentCore MCP Server"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
-    "mcp >= 1.19.0",
+    "mcp ~= 1.24.0",
 ]
 
 [tool.hatch.build.targets.wheel]

package/dist/assets/typescript/http/strands/base/README.md

@@ -0,0 +1,42 @@
+This is a project generated by the AgentCore CLI!
+
+# Layout
+
+The generated application code lives at the agent root directory. At the root, there is a `.gitignore` file, an
+`agentcore/` folder which represents the configurations and state associated with this project. Other `agentcore`
+commands like `deploy`, `dev`, and `invoke` rely on the configuration stored here.
+
+## Agent Root
+
+The main entrypoint to your app is defined in `main.ts`. Using the AgentCore SDK `BedrockAgentCoreApp`, this file
+defines an HTTP server that streams tokens from your chosen Agent framework SDK.
+
+`model/load.ts` instantiates your chosen model provider.
+
+## Input Validation
+
+The generated Zod request schema keeps plain prompts typed as strings before forwarding them to Strands. Retain this
+validation when extending the request shape, and pass only prompt text to the agent.
+
+## Environment Variables
+
+| Variable | Required | Description |
+| --- | --- | --- |
+{{#if hasIdentity}}| `{{identityProviders.[0].envVarName}}` | Yes | {{modelProvider}} API key (local) or Identity provider name (deployed) |
+{{/if}}| `LOCAL_DEV` | No | Set to `1` to use `.env.local` instead of AgentCore Identity |
+
+# Developing locally
+
+If installation was successful, `node_modules/` is already populated with dependencies.
+
+`agentcore dev` will start a local server using `npx tsx watch main.ts` for hot reload. The port is logged to the terminal (default `8080`).
+
+In a new terminal, you can invoke that server with:
+
+`agentcore invoke --dev "What can you do"`
+
+# Deployment
+
+After providing credentials, `agentcore deploy` will deploy your project into Amazon Bedrock AgentCore.
+
+Use `agentcore invoke` to invoke your deployed agent.

package/dist/assets/typescript/http/strands/base/gitignore.template

@@ -0,0 +1,22 @@
+# Environment variables
+.env
+.env.*
+
+# Node
+node_modules/
+dist/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

package/dist/assets/typescript/http/strands/base/main.ts

@@ -0,0 +1,149 @@
+import { BedrockAgentCoreApp } from 'bedrock-agentcore/runtime';
+import { Agent, McpClient, tool, type ToolList } from '@strands-agents/sdk';
+import { z } from 'zod';
+import { loadModel } from './model/load.js';
+import { getStreamableHttpMcpClient } from './mcp_client/client.js';
+{{#if hasMemory}}
+import { getActorId, getOrCreateMemoryManager } from './memory/memory.js';
+{{/if}}
+
+// Define a collection of MCP clients (filter out anything that failed to initialize)
+const mcpClients: McpClient[] = [getStreamableHttpMcpClient()].filter(
+  (client): client is McpClient => Boolean(client)
+);
+
+// Define a collection of tools used by the model
+const tools: ToolList = [];
+
+// Define a simple function tool — the Zod schema gives us type inference and runtime validation for free
+const addNumbers = tool({
+  name: 'add_numbers',
+  description: 'Return the sum of two numbers',
+  inputSchema: z.object({
+    a: z.number(),
+    b: z.number(),
+  }),
+  callback: async ({ a, b }) => a + b,
+});
+tools.push(addNumbers);
+
+// Add MCP clients to tools
+tools.push(...mcpClients);
+
+const SYSTEM_PROMPT = `
+You are a helpful assistant. Use tools when appropriate.
+`;
+
+const requestSchema = z.object({
+  prompt: z.string().default(''),
+});
+
+{{#if hasMemory}}
+const agentCache = new Map<string, Agent>();
+
+async function getOrCreateAgent(sessionId: string, actorId: string): Promise<Agent> {
+  const key = `${actorId}:${sessionId}`;
+  let agent = agentCache.get(key);
+  if (agent) return agent;
+
+  const model = await loadModel();
+  agent = new Agent({
+    model,
+    systemPrompt: SYSTEM_PROMPT,
+    tools,
+    memoryManager: getOrCreateMemoryManager(sessionId, actorId) ?? undefined,
+  });
+  agentCache.set(key, agent);
+  return agent;
+}
+{{else}}
+const AGENT_CACHE_LIMIT = 128;
+
+// Reuses one Agent per sessionId so each session keeps its own in-process
+// conversation history (best-effort; resets on cold start). A Map preserves
+// insertion order, so it doubles as an LRU bounded to 128 sessions — a local
+// dev process serving many sessions cannot leak history between them or grow
+// without bound. On AgentCore Runtime each microVM serves a single session, so
+// this holds one entry. For durable history, attach memory.
+const agentCache = new Map<string, Agent>();
+
+async function getOrCreateAgent(sessionId: string): Promise<Agent> {
+  const existing = agentCache.get(sessionId);
+  if (existing) {
+    agentCache.delete(sessionId);
+    agentCache.set(sessionId, existing);
+    return existing;
+  }
+  if (agentCache.size >= AGENT_CACHE_LIMIT) {
+    const oldest = agentCache.keys().next().value;
+    if (oldest !== undefined) agentCache.delete(oldest);
+  }
+  const model = await loadModel();
+  const agent = new Agent({
+    model,
+    systemPrompt: SYSTEM_PROMPT,
+    tools,
+  });
+  agentCache.set(sessionId, agent);
+  return agent;
+}
+{{/if}}
+
+const app = new BedrockAgentCoreApp({
+  invocationHandler: {
+    requestSchema,
+    async *process(payload, context) {
+      {{#if hasMemory}}
+      const sessionId = context?.sessionId ?? 'default-session';
+      const actorId = getActorId(payload, context);
+      const agent = await getOrCreateAgent(sessionId, actorId);
+      {{else}}
+      const sessionId = context?.sessionId ?? 'default-session';
+      const agent = await getOrCreateAgent(sessionId);
+      {{/if}}
+
+      {{#if hasMemory}}
+      try {
+        for await (const event of agent.stream(payload.prompt)) {
+          if (
+            event.type === 'modelStreamUpdateEvent' &&
+            event.event?.type === 'modelContentBlockDeltaEvent' &&
+            event.event.delta?.type === 'textDelta'
+          ) {
+            yield { data: event.event.delta.text };
+          }
+        }
+      } finally {
+        // Drain in-flight createEvent calls before the runtime can reclaim
+        // the session microVM. flush() is the durability mechanism — without
+        // it, an idle reclamation can lose the tail of the conversation.
+        await agent.memoryManager?.flush();
+      }
+      {{else}}
+      // Snapshot history before streaming so a failed turn can be rolled back.
+      // Agent.stream() appends the user message before invoking the model; on a
+      // mid-stream error that user turn would otherwise linger in the cached
+      // agent, and the next turn for this session would send consecutive user
+      // messages (rejected by providers that require strict role alternation,
+      // e.g. Anthropic). Restoring on error keeps the session reusable.
+      const snapshot = agent.takeSnapshot({ include: ['messages'] });
+      try {
+        for await (const event of agent.stream(payload.prompt)) {
+          if (
+            event.type === 'modelStreamUpdateEvent' &&
+            event.event?.type === 'modelContentBlockDeltaEvent' &&
+            event.event.delta?.type === 'textDelta'
+          ) {
+            yield { data: event.event.delta.text };
+          }
+        }
+      } catch (error) {
+        agent.loadSnapshot(snapshot);
+        throw error;
+      }
+      {{/if}}
+    },
+  },
+});
+
+app.run({ port: parseInt(process.env.PORT ?? '8080') });

package/dist/assets/typescript/http/strands/base/mcp_client/client.ts

@@ -0,0 +1,11 @@
+import { McpClient } from '@strands-agents/sdk';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+
+// ExaAI provides information about code through web searches, crawling and code context searches through their platform. Requires no authentication
+const EXAMPLE_MCP_ENDPOINT = 'https://mcp.exa.ai/mcp';
+
+export function getStreamableHttpMcpClient(): McpClient {
+  // to use an MCP server that supports bearer authentication, add a headers() callback to requestInit
+  const transport = new StreamableHTTPClientTransport(new URL(EXAMPLE_MCP_ENDPOINT));
+  return new McpClient({ transport });
+}

package/dist/assets/typescript/http/strands/base/model/load.ts

@@ -0,0 +1,102 @@
+{{#if (eq modelProvider "Bedrock")}}
+import { BedrockModel } from '@strands-agents/sdk/models/bedrock';
+
+export function loadModel(): BedrockModel {
+  return new BedrockModel({ modelId: 'global.anthropic.claude-sonnet-4-5-20250929-v1:0' });
+}
+{{/if}}
+{{#if (eq modelProvider "Anthropic")}}
+import { AnthropicModel } from '@strands-agents/sdk/models/anthropic';
+import { withApiKey } from 'bedrock-agentcore/identity';
+
+const IDENTITY_PROVIDER_NAME = '{{identityProviders.[0].name}}';
+const IDENTITY_ENV_VAR = '{{identityProviders.[0].envVarName}}';
+
+async function getApiKey(): Promise<string> {
+  if (process.env.LOCAL_DEV === '1') {
+    const apiKey = process.env[IDENTITY_ENV_VAR] ?? process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+      throw new Error(`${IDENTITY_ENV_VAR} or ANTHROPIC_API_KEY not found. Add your key to agentcore/.env.local`);
+    }
+    return apiKey;
+  }
+  return withApiKey({ providerName: IDENTITY_PROVIDER_NAME })(async (apiKey: string) => apiKey)();
+}
+
+let _model: AnthropicModel | undefined;
+
+export async function loadModel(): Promise<AnthropicModel> {
+  if (!_model) {
+    const apiKey = await getApiKey();
+    _model = new AnthropicModel({
+      apiKey,
+      modelId: 'claude-sonnet-4-5-20250929',
+      maxTokens: 5000,
+    });
+  }
+  return _model;
+}
+{{/if}}
+{{#if (eq modelProvider "OpenAI")}}
+import { OpenAIModel } from '@strands-agents/sdk/models/openai';
+import { withApiKey } from 'bedrock-agentcore/identity';
+
+const IDENTITY_PROVIDER_NAME = '{{identityProviders.[0].name}}';
+const IDENTITY_ENV_VAR = '{{identityProviders.[0].envVarName}}';
+
+async function getApiKey(): Promise<string> {
+  if (process.env.LOCAL_DEV === '1') {
+    const apiKey = process.env[IDENTITY_ENV_VAR] ?? process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+      throw new Error(`${IDENTITY_ENV_VAR} or OPENAI_API_KEY not found. Add your key to agentcore/.env.local`);
+    }
+    return apiKey;
+  }
+  return withApiKey({ providerName: IDENTITY_PROVIDER_NAME })(async (apiKey: string) => apiKey)();
+}
+
+let _model: OpenAIModel | undefined;
+
+export async function loadModel(): Promise<OpenAIModel> {
+  if (!_model) {
+    const apiKey = await getApiKey();
+    _model = new OpenAIModel({
+      api: 'chat',
+      apiKey,
+      modelId: 'gpt-4.1',
+    });
+  }
+  return _model;
+}
+{{/if}}
+{{#if (eq modelProvider "Gemini")}}
+import { GoogleModel } from '@strands-agents/sdk/models/google';
+import { withApiKey } from 'bedrock-agentcore/identity';
+
+const IDENTITY_PROVIDER_NAME = '{{identityProviders.[0].name}}';
+const IDENTITY_ENV_VAR = '{{identityProviders.[0].envVarName}}';
+
+async function getApiKey(): Promise<string> {
+  if (process.env.LOCAL_DEV === '1') {
+    const apiKey = process.env[IDENTITY_ENV_VAR] ?? process.env.GEMINI_API_KEY;
+    if (!apiKey) {
+      throw new Error(`${IDENTITY_ENV_VAR} or GEMINI_API_KEY not found. Add your key to agentcore/.env.local`);
+    }
+    return apiKey;
+  }
+  return withApiKey({ providerName: IDENTITY_PROVIDER_NAME })(async (apiKey: string) => apiKey)();
+}
+
+let _model: GoogleModel | undefined;
+
+export async function loadModel(): Promise<GoogleModel> {
+  if (!_model) {
+    const apiKey = await getApiKey();
+    _model = new GoogleModel({
+      apiKey,
+      modelId: 'gemini-2.5-flash',
+    });
+  }
+  return _model;
+}
+{{/if}}

package/dist/assets/typescript/http/strands/base/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "description": "AgentCore Runtime Application using Strands TypeScript SDK",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/main.js",
+    "dev": "tsx watch main.ts"
+  },
+  "dependencies": {
+    {{#if (eq modelProvider "Anthropic")}}
+    "@anthropic-ai/sdk": "^0.71.2",
+    {{/if}}
+    {{#if (eq modelProvider "OpenAI")}}
+    "openai": "^6.7.0",
+    {{/if}}
+    {{#if (eq modelProvider "Gemini")}}
+    "@google/genai": "^1.40.0",
+    {{/if}}
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "@opentelemetry/api": "^1.9.0",
+    "@strands-agents/sdk": "^1.5.0",
+    "bedrock-agentcore": "^0.3.0",
+    "tsx": "^4.19.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "overrides": {
+    "bedrock-agentcore": {
+      "@strands-agents/sdk": "$@strands-agents/sdk"
+    }
+  }
+}

package/dist/assets/typescript/http/strands/base/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": false,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "types": ["node"]
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/dist/assets/typescript/http/strands/capabilities/memory/memory.ts

@@ -0,0 +1,52 @@
+import { randomUUID } from 'node:crypto';
+import { MemoryManager } from '@strands-agents/sdk';
+import { createAgentCoreMemoryStores } from 'bedrock-agentcore/experimental/memory/strands';
+
+const MEMORY_ID = process.env.{{memoryProviders.[0].envVarName}};
+
+const CUSTOM_ACTOR_ID_HEADER = 'x-amzn-bedrock-agentcore-runtime-custom-actor-id';
+
+export function getActorId(payload: any, context: any): string {
+  const raw =
+    context?.headers?.[CUSTOM_ACTOR_ID_HEADER] ||
+    payload?.userId ||
+    context?.sessionId;
+  return typeof raw === 'string' && raw.trim().length > 0 ? raw.trim() : randomUUID();
+}
+
+const memoryManagerCache = new Map<string, MemoryManager>();
+
+export function getOrCreateMemoryManager(sessionId: string, actorId: string): MemoryManager | null {
+  if (!MEMORY_ID) return null;
+
+  const key = `${actorId}:${sessionId}`;
+  let manager = memoryManagerCache.get(key);
+  if (manager) return manager;
+
+  const stores = createAgentCoreMemoryStores({
+    memoryId: MEMORY_ID,
+    actorId,
+    sessionId,
+    namespaces: [
+{{#if (includes memoryProviders.[0].strategies "SEMANTIC")}}
+      { namespace: '/users/{actorId}/facts' },
+{{/if}}
+{{#if (includes memoryProviders.[0].strategies "USER_PREFERENCE")}}
+      { namespace: '/users/{actorId}/preferences' },
+{{/if}}
+{{#if (includes memoryProviders.[0].strategies "EPISODIC")}}
+      { namespace: '/episodes/{actorId}/{sessionId}' },
+{{/if}}
+{{#if (includes memoryProviders.[0].strategies "SUMMARIZATION")}}
+      { namespace: '/summaries/{actorId}/{sessionId}' },
+{{/if}}
+    ],
+    // readMode defaults to 'per-namespace' (one retrieve call per namespace).
+    // Switch to 'subtree' to consolidate to a single hierarchical recall call.
+    extraction: true,
+  });
+
+  manager = new MemoryManager({ stores });
+  memoryManagerCache.set(key, manager);
+  return manager;
+}