cloudflare · mattzcarey · Feb 26, 2026 · Feb 26, 2026 · Mar 23, 2026 · Mar 23, 2026
diff --git a/examples/assistant/src/server.ts b/examples/assistant/src/server.ts
@@ -150,11 +150,13 @@ export class ChatSession extends Think<Env, AgentConfig> {
     });
   }
 
-  override getSystemPrompt(): string {
+  override getContextBlocks() {
     const config = this.getConfig();
-    if (config?.systemPrompt) return config.systemPrompt;
-
-    return `You are a helpful assistant with access to workspace tools.
+    return [
+      {
+        label: "soul",
+        description: "Agent identity and instructions",
+        defaultContent: config?.systemPrompt ?? `You are a helpful assistant with access to workspace tools.
 
 You have two workspaces:
 - Session workspace (private to this conversation): read, write, edit, list, find, grep, delete
@@ -164,17 +166,20 @@ You also have an "execute" tool that runs JavaScript in a sandbox with access to
 Use it for multi-file refactors, coordinated edits, search/replace across files, or any batch operation.
 For simple single-file reads and writes, prefer the direct tools.
 
-Example execute usage:
-  await state.replaceInFiles("/src/**/*.ts", "oldName", "newName");
-  const plan = await state.planEdits([...]);
-  await state.applyEditPlan(plan);
-
 Guidelines:
 - Always read a file before editing it
 - When editing, provide enough context in old_string to make the match unique
 - Use find/shared_find to discover project structure
 - Use grep/shared_grep to search for patterns across files
-- For bulk changes across many files, use the execute tool with state.*`;
+- For bulk changes across many files, use the execute tool with state.*`,
+        readonly: true,
+      },
+      {
+        label: "memory",
+        description: "Learned facts — save environment details, conventions, user preferences",
+        maxTokens: 1100,
+      },
+    ];
   }
 
   override getTools(): ToolSet {

diff --git a/experimental/multi-session-agent/README.md b/experimental/multi-session-agent/README.md
@@ -0,0 +1,46 @@
+# Session Memory Example
+
+Demonstrates the experimental `Session` API for conversation history with automatic compaction.
+
+## Session API
+
+```typescript
+import {
+  Session,
+  AgentSessionProvider
+} from "agents/experimental/memory/session";
+
+export class ChatAgent extends Agent<Env> {
+  // microCompaction is enabled by default — truncates tool outputs
+  // and long text in older messages on every append()
+  session = new Session(new AgentSessionProvider(this), {
+    compaction: {
+      tokenThreshold: 10000,
+      fn: (msgs) => compactMessages(msgs, this.env.AI)
+    }
+  });
+
+  @callable()
+  async chat(message: string, messageId?: string): Promise<string> {
+    await this.session.append({
+      id: messageId ?? `user-${crypto.randomUUID()}`,
+      role: "user",
+      parts: [{ type: "text", text: message }]
+    });
+    const response = await generateResponse(this.session.getMessages());
+    await this.session.append({
+      id: `assistant-${crypto.randomUUID()}`,
+      role: "assistant",
+      parts: [{ type: "text", text: response }]
+    });
+    return response;
+  }
+}
+```
+
+## Setup
+
+```bash
+npm install
+npm start
+```
diff --git a/experimental/multi-session-agent/env.d.ts b/experimental/multi-session-agent/env.d.ts
@@ -0,0 +1,13 @@
+/* eslint-disable */
+// Generated by Wrangler by running `wrangler types env.d.ts --include-runtime false` (hash: 33efd3b17229f92f32173efc2e9ad735)
+declare namespace Cloudflare {
+  interface GlobalProps {
+    mainModule: typeof import("./src/server");
+    durableNamespaces: "ChatAgent";
+  }
+  interface Env {
+    AI: Ai;
+    ChatAgent: DurableObjectNamespace<import("./src/server").ChatAgent>;
+  }
+}
+interface Env extends Cloudflare.Env {}
diff --git a/experimental/multi-session-agent/index.html b/experimental/multi-session-agent/index.html
@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="en" data-theme="workers">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" href="/favicon.ico" />
+    <title>Multi-Session Agent</title>
+    <script>
+      (() => {
+        const mode = localStorage.getItem("theme") || "light";
+        document.documentElement.setAttribute("data-mode", mode);
+        document.documentElement.style.colorScheme = mode;
+      })();
+    </script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/index.tsx"></script>
+  </body>
+</html>
diff --git a/experimental/multi-session-agent/package.json b/experimental/multi-session-agent/package.json
@@ -0,0 +1,26 @@
+{
+  "name": "@cloudflare/agents-multi-session-example",
+  "version": "0.0.0",
+  "description": "Single Agent with multiple independent chat sessions via Session API",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "vite dev",
+    "deploy": "vite build && wrangler deploy",
+    "types": "wrangler types env.d.ts --include-runtime false"
+  },
+  "dependencies": {
+    "@cloudflare/agents-ui": "*",
+    "@cloudflare/kumo": "^1.15.0",
+    "@phosphor-icons/react": "^2.1.10",
+    "agents": "*",
+    "ai": "^6.0.134",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "workers-ai-provider": "*"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4",
+    "tailwindcss": "^4.2.2"
+  }
+}
diff --git a/experimental/multi-session-agent/public/favicon.ico b/experimental/multi-session-agent/public/favicon.ico