agents 0.22.0 → 0.23.0

package/docs/sessions.md

@@ -1,1024 +1,390 @@
-# Sessions (Experimental)
+# Sessions
 
-The Session API provides persistent conversation storage for agents, with tree-structured messages, context blocks, compaction, full-text search, and AI-controllable tools. By default it uses Durable Object SQLite; external Postgres storage is also available for apps that need shared database access, analytics, or cross-DO queries.
+> **Experimental.** Everything exported from `agents/sessions` may change between releases while the API stabilizes.
 
-> **Experimental.** The Session API is under `agents/experimental/memory/session`. The API surface is stable but may evolve before graduating to the main package.
+`agents/sessions` stores durable conversation history in a [Lifecycle Object](./lifecycle.md). It provides tree-structured messages, streamed and byte-budgeted reads, compaction overlays, optional full-text search, and lossless payload storage.
 
-## Quick Start
+**Sessions stores messages. It is not a file store.** Media you attach to a message is kept out of the message row and stored separately, addressed by content, and put back verbatim when you read. That keeps a message row small however large its attachments are — but it does not reclaim database space, because the payload lives in the same Durable Object. A Durable Object's 10 GB ceiling is therefore the real bound on how much media one conversation can hold: roughly 39,000 200 KB images, measured. An application that handles files should keep them in a file store and put a reference in the message. Think does exactly that with its [Workspace](../think/index.md), which spills to R2.
 
-```typescript
-import { Agent } from "agents";
-import { Session } from "agents/experimental/memory/session";
+Prompt assembly lives in [`agents/context`](./context.md) and composes with a session handle rather than living inside it.
 
-class MyAgent extends Agent {
-  session = Session.create(this)
-    .withContext("soul", {
-      provider: { get: async () => "You are a helpful assistant." }
-    })
-    .withContext("memory", {
-      description: "Learned facts about the user",
-      maxTokens: 1100
-    })
-    .withCachedPrompt();
-
-  async onMessage(message) {
-    await this.session.appendMessage(message);
-    const history = await this.session.getHistory();
-    const system = await this.session.freezeSystemPrompt();
-    const tools = await this.session.tools();
-    // Pass history, system prompt, and tools to your LLM
-  }
-}
-```
-
-## Session
+`Think` and `AIChatAgent` use this capability for message persistence. You can also install it on a plain Durable Object.
 
-`Session` manages a single conversation's messages, context blocks, and compaction state.
+## Install the capability
 
-### Creating a Session
+```ts
+import { DurableObject } from "cloudflare:workers";
+import { Lifecycle } from "agents/lifecycle";
+import { Sessions } from "agents/sessions";
 
-There are two ways to create a Session:
-
-**Builder API (recommended)** — uses `Session.create(agent)` with a chainable builder. Context providers without an explicit `provider` option are auto-wired to SQLite.
-
-```typescript
-const session = Session.create(this)
-  .withContext("soul", { provider: { get: async () => "You are helpful." } })
-  .withContext("memory", { description: "Learned facts", maxTokens: 1100 })
-  .withCachedPrompt()
-  .onCompaction(myCompactFn)
-  .compactAfter(100_000);
-```
-
-**Direct constructor** — takes a `SessionProvider` and options directly. Used when you want full control over providers.
-
-```typescript
-import {
-  AgentSessionProvider,
-  AgentContextProvider
-} from "agents/experimental/memory/session";
-
-const session = new Session(new AgentSessionProvider(this), {
-  context: [
-    {
-      label: "memory",
-      description: "Notes",
-      maxTokens: 500,
-      provider: new AgentContextProvider(this, "memory")
-    },
-    { label: "soul", provider: { get: async () => "You are helpful." } }
-  ]
-});
+export class ConversationObject extends DurableObject<Env> {
+  readonly sessions = new Sessions();
+  readonly lifecycle = Lifecycle.install(this).use(this.sessions);
+  readonly session = this.sessions.session();
+}
 ```
 
-### Builder Methods
-
-All builder methods return `this` for chaining. Order does not matter — providers are resolved lazily on first use.
-
-| Method                                    | Description                                                                                                                                                   |
-| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Session.create(agent)`                   | Static factory. `agent` is any object with a `sql` tagged template method (i.e. your Agent/DO).                                                               |
-| `.forSession(sessionId)`                  | Namespace this session by ID. Required for multi-session isolation when not using SessionManager. Context provider keys and storage are scoped to this ID.    |
-| `.withContext(label, options?)`           | Add a context block. See [Context Blocks](#context-blocks).                                                                                                   |
-| `.withCachedPrompt(provider?)`            | Enable system prompt persistence. The prompt is frozen on first use and survives DO hibernation/eviction. Without an explicit provider, auto-wires to SQLite. |
-| `.onCompaction(fn)`                       | Register a compaction function. See [Compaction](#compaction).                                                                                                |
-| `.compactAfter(tokenThreshold, options?)` | Auto-compact when estimated token count exceeds the threshold. Checked after each `appendMessage()`. Requires `.onCompaction()`.                              |
-| `.onCompactionError(handler)`             | Handle errors from automatic compaction. Handler failures are swallowed so message writes remain non-fatal.                                                   |
-
-### Messages
-
-Messages use the `SessionMessage` type — a minimal shape with `id`, `role`, `parts`, and optional `createdAt`. The Vercel AI SDK's `UIMessage` is structurally compatible and can be passed directly without conversion. The session stores messages in a tree structure via `parent_id`, enabling branching conversations.
-
-```typescript
-// Append — auto-parents to the latest leaf unless parentId is specified
-await session.appendMessage(message);
-await session.appendMessage(message, parentId);
+On an `Agent`, install it in the constructor:
 
-// Update an existing message (matched by message.id)
-await session.updateMessage(message);
+```ts
+import { Agent, type AgentContext } from "agents";
+import { Sessions } from "agents/sessions";
 
-// Delete specific messages
-await session.deleteMessages(["msg-1", "msg-2"]);
+export class ConversationAgent extends Agent<Env> {
+  readonly sessions = new Sessions();
+  readonly session = this.sessions.session();
 
-// Clear all messages and skill state
-await session.clearMessages();
+  constructor(ctx: AgentContext, env: Env) {
+    super(ctx, env);
+    this.lifecycle.use(this.sessions);
+  }
+}
 ```
 
-> **Note:** Session methods are async. SQLite-backed sessions are usually fast, but external providers may perform network I/O, and `appendMessage()` may also trigger auto-compaction.
+The default session ID is an empty string. This is the primary path when one Durable Object owns one conversation.
 
-#### Reading History
-
-```typescript
-// Linear history from root to the latest leaf
-const messages = await session.getHistory();
+Sessions needs no alarm, so it also works on facets, which have isolated SQLite but no independent alarm slot.
 
-// History to a specific leaf (for branching)
-const branch = await session.getHistory(leafId);
+## Write messages
 
-// Get a single message
-const msg = await session.getMessage("msg-1");
+`UIMessage` from the AI SDK is structurally compatible with `SessionMessage`.
 
-// Get the newest message
-const latest = await session.getLatestLeaf();
+```ts
+const result = await this.session.appendMessage({
+  id: crypto.randomUUID(),
+  role: "user",
+  parts: [{ type: "text", text: "Hello" }]
+});
 
-// Count messages in path
-const count = await session.getPathLength();
+result.inserted; // false when this ID already existed
+result.message; // exact stored form
 ```
 
-#### Branching
-
-Messages form a tree. When you `appendMessage` with a `parentId` that already has children, you create a branch. Use `getBranches()` to get all child messages branching from a given point:
+An append without `parentId` attaches to the active leaf. Pass `null` to create a root or pass a message ID to create a branch:
 
-```typescript
-// Get all child messages that branch from messageId (e.g. multiple responses to a user message)
-const branches = await session.getBranches(messageId);
+```ts
+await this.session.appendMessage(alternativeReply, {
+  parentId: userMessage.id
+});
 ```
 
-This powers features like response regeneration — pass the user message ID to get both the original and regenerated responses. `getHistory(leafId)` walks the chosen path.
+Every write runs the same pipeline: sanitize provider metadata, strip reserved metadata on client input, then commit the row and any continuation rows in one synchronous SQLite transaction.
 
-### Search
+Mark untrusted input with `source: "client"`:
 
-Full-text search over the conversation history. SQLite-backed sessions use FTS5; Postgres-backed sessions use the provider's Postgres full-text index.
+```ts
+const sessions = new Sessions({
+  reservedMetadataKeys: ["channel", "turnMetadata"]
+});
 
-```typescript
-const results = await session.search("deployment Friday", { limit: 10 });
-// Returns: Array<{ id, role, content, createdAt? }>
+await sessions.session().appendMessage(clientMessage, {
+  source: "client"
+});
 ```
 
-Uses porter stemming and unicode tokenization. The search covers all messages in the session.
-
-> **Note:** `search()` throws if the session provider does not support search. The built-in `AgentSessionProvider` and `PostgresSessionProvider` support it.
+This strips reserved metadata keys. It does not limit message size — see [There is no upper bound on a message](#there-is-no-upper-bound-on-a-message).
 
-### WebSocket Broadcasts
+Other writes:
 
-When the Session's `agent` object has a `broadcast()` method (all `Agent` subclasses do), the Session automatically broadcasts status events over WebSocket after each write operation:
+```ts
+await session.updateMessage(message); // SessionMessage | null
+await session.upsertMessage(message);
+await session.deleteMessages([messageId]);
+await session.clearMessages();
+```
 
-- **`CF_AGENT_SESSION`** — phase (`"idle"` or `"compacting"`), `tokenEstimate`, `tokenThreshold`
-- **`CF_AGENT_SESSION_ERROR`** — emitted on compaction failure
+`updateMessage()` returns the stored form of the message, or `null` when the ID is not in this session. It does not throw for an absent row. An unchanged message writes nothing and dispatches no change event.
 
-This allows connected clients to display real-time token usage and compaction status.
+Deleting a message splices its children to its parent. Removing a message in the middle of a chain does not make older history unreachable.
 
----
+### Row budget
 
-## Context Blocks
+Sessions stores messages. One SQLite row holds up to 1.5 MiB of serialized JSON, which is more than the overwhelming majority of messages need: they occupy exactly one row, and cost exactly one billed row write.
 
-Context blocks are persistent key-value sections injected into the system prompt. Each block has a **label**, optional **description**, and a **provider** that determines its behavior.
+A message that does not fit is split across continuation rows and reassembled on read. Nothing is truncated, nothing is summarized, and no message is too large to store — a 5 MB message is one message row plus three continuation rows, and reads back byte for byte. There is no error to catch and nothing to configure.
 
-### Provider Types
+Slices are cut on UTF-8 **byte** boundaries, never in the middle of a surrogate pair, so a message full of emoji or CJK text round-trips exactly like an ASCII one.
 
-There are four provider types, detected by duck-typing:
+### There is no upper bound on a message
 
-| Provider                    | Interface                       | Behavior                                                                                         | AI Tool                                         |
-| --------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
-| **ContextProvider**         | `get()`                         | Read-only block in system prompt                                                                 | —                                               |
-| **WritableContextProvider** | `get()` + `set()`               | Writable via AI                                                                                  | `set_context`                                   |
-| **SkillProvider**           | `get()` + `load()` + `set?()`   | On-demand keyed documents. `get()` returns a metadata listing; `load(key)` fetches full content. | `load_context`, `unload_context`, `set_context` |
-| **SearchProvider**          | `get()` + `search()` + `set?()` | Full-text searchable entries. `get()` returns a summary; `search(query)` runs FTS5.              | `search_context`, `set_context`                 |
+This is a deliberate position, not an omission: Sessions imposes no maximum message size. A message is split across as many continuation rows as it needs, so a single very large write can consume a meaningful share of the Durable Object's 10 GB.
 
-All providers also support an optional `init(label)` method, called before first use with the block's label.
+Bounding the size of untrusted input is the application's job. In particular, `appendMessage(message, { source: "client" })` sanitizes provider metadata and strips reserved metadata keys — it does **not** limit size. If clients can write to a session, check the size of what they send before you append it.
 
-### Built-in Providers
+An application that handles files should keep them in a file store (R2, or the Workspace) and put a reference in the message.
 
-**`AgentContextProvider`** — SQLite-backed writable context. This is what you get by default when using the builder without an explicit provider.
+## Read history
 
-```typescript
-import { AgentContextProvider } from "agents/experimental/memory/session";
+Prefer streamed reads for unbounded history:
 
-// Explicit usage — key determines the SQLite row
-new AgentContextProvider(this, "memory");
+```ts
+for await (const message of session.history()) {
+  await consume(message);
+}
 ```
 
-**`R2SkillProvider`** — Cloudflare R2 bucket for on-demand document loading. Skills are listed in the system prompt as metadata; the model loads full content on demand via `load_context`.
+The capability first reads a content-free path of IDs and row sizes. It then fetches content in queries bounded to 50 rows and 4 MiB. Earlier chunks are not retained by the iterator.
 
-```typescript
-import { R2SkillProvider } from "agents/experimental/memory/session";
+Read from the leaf when you are looking for something recent. The newest content window is fetched first, so breaking out of the loop leaves every older row unread:
 
-Session.create(this).withContext("skills", {
-  provider: new R2SkillProvider(env.SKILLS_BUCKET, { prefix: "skills/" })
-});
+```ts
+for await (const message of session.history({ newestFirst: true })) {
+  if (ownsToolCall(message, toolCallId)) {
+    await session.updateMessage(applyResult(message));
+    break;
+  }
+}
 ```
 
-Descriptions are stored in R2 custom metadata (`description` key).
-
-**`AgentSearchProvider`** — SQLite FTS5 searchable context. Entries are indexed and searchable by the model via `search_context`.
+A newest-first read follows parent pointers from the leaf, one row per message the loop actually takes, so its cost has no transcript term. Compaction overlays are honored: the walk stays row-by-row until it reaches the end of a compacted span, and only then plans the overlays over the remaining prefix and streams it leaf-first in eight-row windows.
 
-```typescript
-import { AgentSearchProvider } from "agents/experimental/memory/session";
+Use `historyBatches()` when each downstream operation has a fixed cost:
 
-Session.create(this).withContext("knowledge", {
-  description: "Searchable knowledge base",
-  provider: new AgentSearchProvider(this)
-});
+```ts
+for await (const batch of session.historyBatches({
+  batchSize: 25,
+  maxBatchBytes: 2 * 1024 * 1024
+})) {
+  await sendBatch(batch);
+}
 ```
 
-### Adding and Removing Context at Runtime
-
-Blocks can be added and removed dynamically after initialization — useful for extensions:
+Use a byte-budgeted recent window during Durable Object startup:
 
-```typescript
-// Add a new block (auto-wires to SQLite if no provider given)
-await session.addContext("extension-notes", {
-  description: "From extension X",
-  maxTokens: 500
-});
+```ts
+const recent = await session.getRecentHistory(8 * 1024 * 1024, 4);
 
-// Remove it
-session.removeContext("extension-notes");
-
-// Rebuild the system prompt to reflect changes
-await session.refreshSystemPrompt();
+recent.messages;
+recent.truncated;
+recent.totalContentBytes;
 ```
 
-> **Note:** `addContext` and `removeContext` do NOT automatically update the frozen system prompt. You must call `refreshSystemPrompt()` afterward.
-
-### Reading Context Blocks
-
-```typescript
-// Single block
-const block = session.getContextBlock("memory");
-// block: { label, description?, content, tokens, maxTokens?, writable, isSkill, isSearchable }
-
-// All blocks
-const blocks = session.getContextBlocks();
-```
+The second argument is a minimum number of recent messages. The minimum can exceed the byte budget, so choose it deliberately.
 
-### Writing to Context Blocks
+The budget counts what hydration actually costs. Each row is charged its full stored size — the message row plus every continuation row it was split across — so a 12 MB message is charged 12 MB, not the 1.5 MiB its first slice occupies. That is what makes the budget a bound on isolate memory.
 
-```typescript
-// Replace content entirely
-await session.replaceContextBlock("memory", "User likes coffee.");
+`getHistory()` materializes the selected path and exists for consumers that require an array:
 
-// Append content
-await session.appendContextBlock("memory", "\nUser prefers dark roast.");
+```ts
+const messages = await session.getHistory();
 ```
 
-> **Note:** Writing to a context block updates the provider immediately but does NOT update the frozen system prompt snapshot. This is intentional — it preserves the LLM prefix cache. Call `refreshSystemPrompt()` when you want changes reflected in the prompt.
-
-### System Prompt
-
-The system prompt is built from all context blocks with headers and metadata:
-
-```
-══════════════════════════════════════════════
-SOUL (Identity) [readonly]
-══════════════════════════════════════════════
-You are a helpful assistant.
-
-══════════════════════════════════════════════
-MEMORY (Learned facts) [45% — 495/1100 tokens]
-══════════════════════════════════════════════
-User likes coffee.
-User prefers dark roast.
-```
+Do not use `getHistory()` for an unbounded transcript inside a memory-constrained Durable Object. Prefer `history()`, `historyBatches()`, or `getRecentHistory()`.
 
-```typescript
-// Freeze — first call renders and persists, subsequent calls return the cached value
-const prompt = await session.freezeSystemPrompt();
+Other reads:
 
-// Refresh — re-render from current block state and persist
-const updated = await session.refreshSystemPrompt();
+```ts
+await session.getMessage(id);
+await session.getLatestLeaf();
+await session.getBranches(parentId);
+await session.getHistoryRowStats();
 ```
 
-The frozen prompt survives DO hibernation and eviction when `withCachedPrompt()` is enabled. After eviction, the next `freezeSystemPrompt()` call loads from the configured prompt store rather than re-rendering.
+`getHistoryRowStats()` returns per-row stored bytes (row, continuation rows, and attachments) and stamped token estimates, without loading message content.
 
-### Skills (Load/Unload)
+## Branches
 
-Skills are on-demand documents stored in a `SkillProvider` (e.g. R2). The model sees a metadata listing in the system prompt and can load full content on demand:
+A message can have multiple children. Read one root-to-leaf path by selecting its leaf:
 
-```typescript
-// Unload a skill to free context space (rewrites the tool result in history)
-await session.unloadSkill("skills", "api-reference");
-
-// Check what's currently loaded
-const loaded = await session.getLoadedSkillKeys(); // Set<"skills:api-reference">
+```ts
+const branch = await session.getHistory({ leafId: alternativeReply.id });
+const alternatives = await session.getBranches(userMessage.id);
 ```
 
-After hibernation/eviction, loaded skills are reconstructed by scanning conversation history for `load_context` tool results. This means skill state survives restarts without additional storage.
-
-> **Gotcha:** Skill restoration scans the entire conversation history looking for `load_context` tool invocations in assistant messages with `state: "output-available"`. When you unload a skill, it does not delete the tool result — it rewrites the `output` field to `"[skill unloaded: key]"` in-place. This means the original loaded content is permanently lost from history after unload.
-
----
-
-## AI Tools
-
-Session automatically generates tools based on the provider types of your context blocks. Pass these to your LLM alongside your own tools.
+To move a conversation between Durable Objects, export the source with `history()` and replay it with `importMessage()` on the destination:
 
-```typescript
-const tools = await session.tools();
-// Merge with your own tools:
-const allTools = { ...tools, ...myTools };
+```ts
+let parentId: string | null = null;
+for await (const message of source.history()) {
+  await destination.importMessage(message, {
+    parentId,
+    createdAt: message.createdAt?.getTime() ?? Date.now()
+  });
+  parentId = message.id;
+}
 ```
 
-### `set_context`
-
-Generated when any writable block exists. Writes to regular blocks, skill blocks (keyed), or search blocks (keyed).
-
-- For regular blocks: `{ label, content, action: "replace" | "append" }`
-- For skill blocks: `{ label, content, metadata?: { title, description } }`
-- For search blocks: `{ label, content, metadata?: { title } }`
-
-Enforces `maxTokens` limits. Returns a usage string like `"Written to memory. Usage: 45% (495/1100 tokens)"`.
-
-For keyed blocks, `metadata.title` becomes the stable entry key. If title is omitted, the key is generated from the content plus a short deterministic hash to avoid silent collisions; provide a title when you want later writes to update the same entry.
-
-### `load_context`
-
-Generated when any skill block exists. Loads full content by key from a `SkillProvider`.
-
-- Input: `{ label, key }`
-- Returns the document content, or `"Not found: key"`
-
-### `unload_context`
-
-Generated alongside `load_context`. Frees context space by unloading a previously loaded skill.
+`importMessage()` writes one historical message verbatim: explicit parent and timestamp, no change-feed event. It splits over-budget messages the same way an append does.
 
-- Input: `{ label, key }`
-- Rewrites the tool result in conversation history to a short marker
-- The skill remains available for re-loading
-
-The tool's description dynamically lists currently loaded skills.
-
-### `search_context`
-
-Generated when any search block exists. Full-text search within a searchable context block.
-
-- Input: `{ label, query }`
-- Returns top 10 results by FTS5 rank, or `"No results found."`
-
-### `session_search`
-
-Available on `SessionManager` only (not on individual sessions). Searches across all sessions.
-
-- Input: `{ query }`
-- Returns results from all sessions, or `"No results found."`
-
-Use `{ ...sessionTools, ...manager.tools() }` to give the model both per-session and cross-session tools.
-
----
+For one-Durable-Object-per-conversation applications, keep the conversation directory in a parent or router Durable Object.
 
 ## Compaction
 
-Compaction summarizes older messages to keep conversations within token limits. Original messages are preserved in the underlying message store — the summary is a non-destructive overlay applied at read time.
+Compaction overlays replace a range at read time without deleting the original rows:
 
-### Setup
+```ts
+import { createCompactFunction } from "agents/sessions";
 
-```typescript
-import { createCompactFunction } from "agents/experimental/memory/utils/compaction-helpers";
-
-const session = Session.create(this)
-  .withContext("memory", { maxTokens: 1100 })
+session
   .onCompaction(
     createCompactFunction({
-      summarize: (prompt) =>
-        generateText({ model: myModel, prompt }).then((r) => r.text),
-      protectHead: 3, // Keep first 3 messages (default: 3)
-      tailTokenBudget: 20000, // Protect ~20K tokens at the tail (default: 20000)
-      minTailMessages: 2, // Always keep at least 2 tail messages (default: 2)
-      tokenCounter: async (messages) => estimateWithYourTokenizer({ messages })
+      summarize: async (prompt) => summarize(prompt),
+      keepRecentTokens: 20_000
     })
   )
-  .compactAfter(100_000); // Auto-compact at 100K estimated tokens
+  .compactAfter(80_000);
 ```
 
-### How It Works
-
-1. **Protect head** — first N messages are never compacted (default 3)
-2. **Protect tail** — walk backward from the end, accumulating tokens up to a budget (default 20K tokens)
-3. **Align boundaries** — shift boundaries to avoid splitting tool call/result pairs
-4. **Summarize middle** — send the middle section to an LLM with a structured format (Topic, Key Points, Current State, Open Items)
-5. **Store overlay** — saved in `assistant_compactions` table, keyed by `fromMessageId` and `toMessageId`
-6. **Iterative** — on subsequent compactions, the existing summary is passed to the LLM to update rather than replace
+`createCompactFunction` takes exactly two options. `summarize` calls the model with a prompt and returns its text. `keepRecentTokens` is the token budget for the recent tail kept verbatim, defaulting to 20,000. The first three messages are kept verbatim as the head, at least the last two are kept as the tail, and the boundaries are aligned so a tool call is never separated from its result.
 
-When `getHistory()` is called, compaction overlays are applied transparently — the compacted range is replaced by a synthetic message with id `compaction_<id>`.
+Run it explicitly:
 
-### Manual Compaction
-
-```typescript
-// Run registered compaction function
-const result = await session.compact();
-
-// Or manage overlays directly
-await session.addCompaction("Summary of messages 1-50", "msg-1", "msg-50");
-const overlays = await session.getCompactions();
+```ts
+await session.compact();
+await session.compact(leafId); // compact a specific branch
 ```
 
-### Auto-Compaction
-
-When `.compactAfter(threshold)` is set, `appendMessage()` checks the estimated token count after each write. If it exceeds the threshold, `compact()` is called automatically. Auto-compaction failure is non-fatal — the message is already saved.
-
-> Auto-compaction is checked **between turns** (on each `appendMessage()`), not within a turn. A single long, tool-heavy turn can grow past the model's context window mid-flight, before the next check. `@cloudflare/think` adds opt-in mid-turn recovery on top of this — see [Context-window overflow recovery](https://github.com/cloudflare/agents/blob/main/docs/think/index.md#context-window-overflow-recovery).
-
-By default, the estimate includes stored message parts plus the Session-managed frozen system prompt. That means context blocks and cached prompts managed by `Session` contribute to the threshold. The estimate does not include framework-specific prompt additions or tool schema serialization that happen outside `Session`, such as Think's final capability prompt and tool catalog.
-
-There are two token-counting decisions:
+Or store an already-produced summary:
 
-- `.compactAfter(threshold, { tokenCounter })` controls when automatic compaction is triggered after writes. It can include the frozen system prompt and context blocks.
-- `createCompactFunction({ tokenCounter })` controls which tail messages are protected from summarization. Use this when tool-heavy histories are much larger than the Workers-safe heuristic can estimate.
-
-You usually only need to configure one counter. The `.compactAfter()` counter now also flows into `createCompactFunction`'s boundary walk (via `CompactContext`) when no explicit `createCompactFunction({ tokenCounter })` is given, so a single counter drives both "should we compact?" and "what should we compact?". Without this, a fire-only counter plus the under-counting heuristic could make compaction trigger every turn but silently no-op on tool-heavy histories (fixed in [#1593](https://github.com/cloudflare/agents/issues/1593)).
-
-Caveat: the flowed counter is invoked **per message** during the boundary walk. A tokenizer-style counter budgets accurately; a usage-only counter that returns a fixed whole-prompt total (e.g. `usage.inputTokens` regardless of which messages are passed) degrades the tail budget to `minTailMessages` — compaction still runs and context stays bounded, but the byte budget is effectively ignored. Pass an explicit per-message `createCompactFunction({ tokenCounter })` for precise tail budgeting.
-
-Use a custom counter when you have model-reported usage or your own tokenizer:
-
-```typescript
-const session = Session.create(this)
-  .onCompaction(myCompactFn)
-  .compactAfter(100_000, {
-    tokenCounter: async ({ messages, systemPrompt, contextBlocks }) => {
-      return estimateWithYourTokenizer({
-        messages,
-        systemPrompt,
-        contextBlocks
-      });
-    }
-  })
-  .onCompactionError((err) => {
-    console.warn("Auto-compaction failed", err);
-  });
+```ts
+await session.addCompaction(summary, fromMessageId, toMessageId);
 ```
 
-> **Note:** The default token estimation is heuristic (not tiktoken). It uses `max(chars/4, words*1.3)` with 4 tokens per-message overhead, and also applies the string heuristic to the Session-managed system prompt. This is intentional — tiktoken would add 80-120MB heap overhead, which exceeds Cloudflare Workers' 128MB limit.
+Sessions stamps each message with a token estimate when the row is written. `compactAfter()` gates on that O(1) aggregate and never reads the transcript to decide whether to compact. Auto-compaction failures are non-fatal: they log, emit `session:error`, and leave the transcript alone.
 
-> **Gotcha:** Compaction is iterative but single-overlay. Each new compaction extends from the earliest existing compaction's `fromMessageId` to the new end. So you always have at most one active compaction overlay per session, and it keeps growing. The previous compaction rows remain in the database but are superseded by the latest one (which covers a wider range). `getCompactions()` returns all of them, but `getHistory()` applies the latest one.
+To trim a transcript before handing it to a model, `truncateOlderMessages` is exported from [`agents/chat`](./chat-agents.md), not from `agents/sessions`.
 
----
+## Large messages
 
-## SessionManager
+A message is stored as one JSON string. When that string exceeds the row budget it is cut into slices: slice 0 lives in the message row, the rest become numbered continuation rows in `cf_agents_session_message_chunks`. A read concatenates them back, so what you append is exactly what you read.
 
-`SessionManager` is a registry for multiple named sessions within a single Durable Object. It provides lifecycle management, convenience methods, and cross-session search.
+This is invisible from the outside. There is no pointer, no reconstruction mode, and no read option:
 
-### Creating a SessionManager
-
-```typescript
-import { SessionManager } from "agents/experimental/memory/session";
-
-const manager = SessionManager.create(this)
-  .withContext("soul", { provider: { get: async () => "You are helpful." } })
-  .withContext("memory", { description: "Learned facts", maxTokens: 1100 })
-  .withCachedPrompt()
-  .onCompaction(myCompactFn)
-  .compactAfter(100_000)
-  .withSearchableHistory("history");
-```
-
-Context blocks, prompt caching, and compaction settings are propagated to all sessions created through the manager. Provider keys are automatically namespaced by session ID (e.g. `memory_<sessionId>`).
-
-### Builder Methods
-
-| Method                                    | Description                                                                                                              |
-| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `SessionManager.create(agent)`            | Static factory.                                                                                                          |
-| `.withContext(label, options?)`           | Add context block template for all sessions.                                                                             |
-| `.withCachedPrompt(provider?)`            | Enable prompt persistence for all sessions.                                                                              |
-| `.onCompaction(fn)`                       | Register compaction function for all sessions.                                                                           |
-| `.compactAfter(tokenThreshold, options?)` | Auto-compact threshold for all sessions. Supports the same `tokenCounter` option as `Session`.                           |
-| `.onCompactionError(handler)`             | Handle automatic compaction errors for managed sessions.                                                                 |
-| `.withSearchableHistory(label)`           | Add a cross-session searchable history block to every session. The model can search past conversations from any session. |
-
-### Session Lifecycle
-
-```typescript
-// Create a new session
-const info = manager.create("My Chat");
-// info: { id, name, parent_session_id, model, source, input_tokens, output_tokens, estimated_cost, end_reason, created_at, updated_at }
-
-// Create with metadata
-const info2 = manager.create("My Chat", {
-  parentSessionId: "parent-id",
-  model: "claude-sonnet-4-20250514",
-  source: "web"
-});
-
-// Get session metadata (null if not found)
-const session = manager.get(sessionId);
-
-// List all sessions (ordered by updated_at DESC)
-const sessions = manager.list();
-
-// Rename
-manager.rename(sessionId, "New Name");
-
-// Delete (clears messages too)
-await manager.delete(sessionId);
-```
-
-### Accessing Sessions
-
-```typescript
-// Get or create the Session instance for an ID
-// Lazy — creates on first access, caches for subsequent calls
-const session = manager.getSession(sessionId);
+```ts
+await session.appendMessage(message); // any size
+const stored = await session.getMessage(message.id); // byte-identical
 ```
 
-### Message Convenience Methods
+The common path pays nothing for it. A window of messages with no continuations issues exactly the same queries it always did; the extra query for continuation rows runs only for the ids in the window that actually have them.
 
-These delegate to the underlying Session but also update the session's `updated_at` timestamp:
+### What it costs
 
-```typescript
-// Append a single message
-await manager.append(sessionId, message, parentId?);
+Splitting is not a way to shrink the database. Continuation rows live in the same Durable Object as the message they belong to, inside the same 10 GB. Billing counts rows written, not bytes, so a 500 KB message costs the same one billed row as a tiny one, and a 2 MB message costs two.
 
-// Add or update (upsert)
-await manager.upsert(sessionId, message, parentId?);
+`SessionRowStat.bytes` and the `totalContentBytes` returned by `getRecentHistory()` report the whole message — row plus continuations — so a byte budget passed to `getRecentHistory()` bounds the memory a hydration will actually take.
 
-// Batch append (auto-chains parent IDs)
-await manager.appendAll(sessionId, messages, parentId?);
+### Files belong in a file store
 
-// Read history
-const history = await manager.getHistory(sessionId, leafId?);
+Sessions is a message store, not a file store. Attaching a file is convenient and exact, but it is stored in the conversation forever and counted against the Durable Object's 10 GB. An application that handles files should write them to R2 or the Workspace and put a path or URL in the message instead.
 
-// Message count
-const count = await manager.getMessageCount(sessionId);
+## Attachments
 
-// Clear messages
-await manager.clearMessages(sessionId);
+A part that declares a non-text media type and carries its bytes inline — an image, an audio clip, a PDF — is stored outside the message. The part keeps its shape and its `mediaType`; only the payload is replaced, by an `attachment:sha256:<hex>` pointer. Reads put the payload back, so this is invisible from the outside:
 
-// Delete specific messages
-await manager.deleteMessages(sessionId, ["msg-1"]);
+```ts
+await session.appendMessage(messageWithImage);
+const stored = await session.getMessage(messageWithImage.id); // byte-identical
 ```
 
-### Forking
-
-Fork a session at a specific message — copies history up to that point into a new session:
-
-```typescript
-const forked = await manager.fork(sessionId, atMessageId, "Forked Chat");
-// forked.parent_session_id === sessionId
-```
-
-> **Gotcha:** Fork copies messages with new UUIDs, not the original IDs. This means message IDs in the forked session will not match the original. The fork also does not copy compaction overlays — the forked session starts clean with the materialized history.
-
-### Compaction
+The rule is about **type, not size**. An image is stored this way whether it is 8 KB or 8 MB, and text is never stored this way at any size — long prose is split across continuation rows instead. The two mechanisms never interact: media leaves the message before the row is measured, so a message carrying a large image usually has no continuation rows at all.
 
-```typescript
-// Add a compaction overlay
-await manager.addCompaction(sessionId, summary, fromId, toId);
+Identical payloads are stored once. That is a consequence of addressing bytes by their hash, which mainly means a retried write costs nothing; do not rely on it as a space optimization.
 
-// Get overlays
-const compactions = await manager.getCompactions(sessionId);
+A payload lives as long as some message references it. Deleting the last message that points at one deletes the bytes; clearing a session deletes all of them.
 
-// Compact and split — marks old session as ended, creates a continuation
-const continuation = await manager.compactAndSplit(
-  sessionId,
-  summary,
-  "Continued Chat"
-);
-// continuation.parent_session_id === sessionId
-// Old session gets end_reason = "compaction"
-```
-
-`compactAndSplit` is different from regular compaction — it creates a new session with a summary message instead of an in-place overlay. The original session is marked with `end_reason: "compaction"`.
+### What it costs
 
-### Usage Tracking
+Keeping media out of the message is not free. A 200 KB image bills four row writes — the message, one payload chunk, its metadata, and one reference — where inlining it would bill one. A 2 MiB image bills five. Text messages are unaffected and still bill exactly one row.
 
-```typescript
-manager.addUsage(sessionId, inputTokens, outputTokens, cost);
-// Increments input_tokens, output_tokens, and estimated_cost on the session row
-```
+What you get is a message row that stays a few hundred bytes however large the payload is. `SessionRowStat.bytes` still charges each message for the payloads it points at, so the byte budget you pass to `getRecentHistory()` remains a bound on the memory a hydration actually takes.
 
-### Cross-Session Search
+That budget is a hard ceiling with no message-count floor beneath it. `getRecentHistory()` returns the longest recent suffix that fits, and always at least the newest message; a window of unusually large messages is simply shorter. A floor that admitted rows regardless of size would defeat the bound it sits under, which is why there is no longer a `minRecentMessages` argument.
 
-```typescript
-// Search across all sessions (FTS5)
-const results = manager.search("deployment Friday", { limit: 20 });
-// Returns: Array<{ id, role, content, createdAt }>
+## Full-text search
 
-// Get tools for the model (includes session_search)
-const tools = manager.tools();
+```ts
+const results = await session.search("deployment failed");
 ```
 
-> **Note:** `manager.search()` uses a separate FTS5 index (`assistant_fts`) from per-session search. Messages are indexed into this table by the `AgentSessionProvider` when appended. The `session_search` tool limits results to 10.
-
-> **Gotcha:** `manager.search()` silently returns an empty array on FTS5 query errors (malformed queries, etc.) rather than throwing.
-
----
-
-## Storage
-
-By default, storage is in Durable Object SQLite and tables are created lazily on first use. Postgres-backed sessions use the external tables shown in the Postgres section below.
-
-### Tables
-
-**`assistant_messages`** — Tree-structured messages.
-
-| Column       | Type     | Notes                                                  |
-| ------------ | -------- | ------------------------------------------------------ |
-| `id`         | TEXT     | Message ID                                             |
-| `session_id` | TEXT     | Empty string for single-session; set for multi-session |
-| `parent_id`  | TEXT     | Parent message ID (null for roots)                     |
-| `role`       | TEXT     | `user`, `assistant`, `system`                          |
-| `content`    | TEXT     | JSON-serialized `SessionMessage`                       |
-| `created_at` | DATETIME | Auto-set                                               |
-
-For Postgres, messages use `PRIMARY KEY (session_id, id)` so caller-provided IDs only need to be unique within a session.
+The index is built by the first `search()` call on an object, with a one-time SQL-only backfill of the messages already stored, and maintained on every write from then on. An object that never searches never pays for an index: maintaining one costs an extra billed row on every append, so it exists only where something actually reads it.
 
-**`assistant_compactions`** — Compaction overlays.
+Search indexes text parts only. File contents, reasoning, and tool payloads are not indexed automatically.
 
-| Column            | Type     | Notes                    |
-| ----------------- | -------- | ------------------------ |
-| `id`              | TEXT PK  | Random UUID              |
-| `session_id`      | TEXT     | Scoped to session        |
-| `summary`         | TEXT     | LLM-generated summary    |
-| `from_message_id` | TEXT     | Start of compacted range |
-| `to_message_id`   | TEXT     | End of compacted range   |
-| `created_at`      | DATETIME | Auto-set                 |
+## Storage economics
 
-**`assistant_fts`** — FTS5 virtual table for message search. Tokenizer: `porter unicode61`.
+On Durable Object SQLite a row write costs roughly 1000 times a row read, so the schema is built to keep one logical write to one billed row.
 
-**`assistant_sessions`** — Session registry (SessionManager only).
+Every Sessions table is `WITHOUT ROWID` with a composite primary key and no secondary index:
 
-| Column              | Type     | Notes                      |
-| ------------------- | -------- | -------------------------- |
-| `id`                | TEXT PK  | Random UUID                |
-| `name`              | TEXT     | Display name               |
-| `parent_session_id` | TEXT     | For forks/splits           |
-| `model`             | TEXT     | Optional model identifier  |
-| `source`            | TEXT     | Optional source identifier |
-| `input_tokens`      | INTEGER  | Cumulative input tokens    |
-| `output_tokens`     | INTEGER  | Cumulative output tokens   |
-| `estimated_cost`    | REAL     | Cumulative cost            |
-| `end_reason`        | TEXT     | `"compaction"` when split  |
-| `created_at`        | DATETIME | Auto-set                   |
-| `updated_at`        | DATETIME | Updated on message ops     |
+| Table                              | Primary key             | Contents                                                                                        |
+| ---------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------- |
+| `cf_agents_session_messages`       | `(session_id, id)`      | `seq`, `parent_id`, `type`, `role`, JSON content, continuation count, token estimate, timestamp |
+| `cf_agents_session_message_chunks` | `(session_id, id, idx)` | Continuation slices of a message too large for one row                                          |
+| `cf_agents_session_compactions`    | `(session_id, id)`      | Non-destructive summary ranges                                                                  |
+| `cf_agents_session_config`         | `(session_id, key)`     | Lifted session configuration                                                                    |
+| `cf_agents_session_fts`            | virtual                 | FTS5 index, created by the first `search()`                                                     |
 
-**`cf_agents_context_blocks`** — Persistent context block storage (`AgentContextProvider`).
-
-**`cf_agents_search_entries`** + **`cf_agents_search_fts`** — Searchable context entries and FTS5 index (`AgentSearchProvider`).
-
----
-
-## Custom Providers
-
-You can implement any of the four provider interfaces to plug in your own storage:
-
-```typescript
-// Read-only context
-const myProvider: ContextProvider = {
-  get: async () => "Static content here"
-};
-
-// Writable context (enables set_context tool)
-const myWritable: WritableContextProvider = {
-  get: async () => fetchFromMyDB(),
-  set: async (content) => saveToMyDB(content)
-};
-
-// Skill provider (enables load_context tool)
-const mySkills: SkillProvider = {
-  get: async () => "- api-ref: API Reference\n- guide: User Guide",
-  load: async (key) => fetchDocument(key),
-  set: async (key, content, description) =>
-    saveDocument(key, content, description) // optional
-};
-
-// Search provider (enables search_context tool)
-const mySearch: SearchProvider = {
-  get: async () => "42 entries indexed",
-  search: async (query) => searchMyIndex(query),
-  set: async (key, content) => indexContent(key, content) // optional
-};
-```
-
-You can also implement `SessionProvider` to replace the SQLite storage entirely:
-
-```typescript
-const myStorage: SessionProvider = {
-  getMessage(id) { ... },
-  getHistory(leafId?) { ... },
-  getLatestLeaf() { ... },
-  getBranches(messageId) { ... },
-  getPathLength(leafId?) { ... },
-  appendMessage(message, parentId?) { ... },
-  updateMessage(message) { ... },
-  deleteMessages(messageIds) { ... },
-  clearMessages() { ... },
-  addCompaction(summary, fromId, toId) { ... },
-  getCompactions() { ... },
-  searchMessages(query, limit) { ... } // optional
-};
-```
+A text append bills exactly one row write on an object that has never searched. The `seq` column carries ordering and `type` distinguishes row kinds, so neither needs an index. A continuation row carries its slice and nothing else — no hash, no media type, no size — so an over-budget message costs one billed row per slice and nothing more.
 
----
+State is derived rather than maintained. The active leaf is the session's max-`seq` row and token totals come from per-row stamped estimates. No counter row, registry row, or refcount is written on the append path.
 
-## Postgres (External Database)
+## Observe changes
 
-The default providers use Durable Object SQLite. If you need session data in an external Postgres database — for cross-DO queries, analytics, or shared state — use `PostgresSessionProvider`, `PostgresContextProvider`, and `PostgresSearchProvider`.
+`Sessions.subscribe()` reports ordered writes in the active isolate:
 
-These work with any Postgres-compatible database (Neon, Supabase, PlanetScale, etc.) via [Cloudflare Hyperdrive](https://developers.cloudflare.com/hyperdrive/) for connection pooling.
-
-### Setup
-
-#### 1. Create a Postgres database
-
-Use any Postgres provider and copy the connection string.
-
-#### 2. Create a Hyperdrive config
-
-```bash
-npx wrangler hyperdrive create my-session-db \
-  --connection-string="postgresql://user:password@host:port/dbname"
-```
-
-Copy the returned Hyperdrive ID.
-
-#### 3. Create the tables
-
-The Postgres user might not have `CREATE TABLE` permissions. Run this once in your database console:
-
-```sql
-CREATE TABLE IF NOT EXISTS assistant_messages (
-  id TEXT NOT NULL,
-  session_id TEXT NOT NULL DEFAULT '',
-  parent_id TEXT,
-  role TEXT NOT NULL,
-  content TEXT NOT NULL,
-  text_content TEXT NOT NULL DEFAULT '',
-  created_at TIMESTAMPTZ DEFAULT NOW(),
-  content_tsv TSVECTOR GENERATED ALWAYS AS (to_tsvector('english', text_content)) STORED,
-  PRIMARY KEY (session_id, id)
-);
-CREATE INDEX IF NOT EXISTS idx_assistant_msg_parent ON assistant_messages (parent_id);
-CREATE INDEX IF NOT EXISTS idx_assistant_msg_session ON assistant_messages (session_id);
-CREATE INDEX IF NOT EXISTS idx_assistant_msg_fts ON assistant_messages USING GIN (content_tsv);
-
-CREATE TABLE IF NOT EXISTS assistant_compactions (
-  id TEXT PRIMARY KEY,
-  session_id TEXT NOT NULL DEFAULT '',
-  summary TEXT NOT NULL,
-  from_message_id TEXT NOT NULL,
-  to_message_id TEXT NOT NULL,
-  created_at TIMESTAMPTZ DEFAULT NOW()
-);
-
-CREATE TABLE IF NOT EXISTS cf_agents_context_blocks (
-  label TEXT PRIMARY KEY,
-  content TEXT NOT NULL,
-  updated_at TIMESTAMPTZ DEFAULT NOW()
-);
-
-CREATE TABLE IF NOT EXISTS cf_agents_search_entries (
-  label TEXT NOT NULL,
-  key TEXT NOT NULL,
-  content TEXT NOT NULL,
-  content_tsv TSVECTOR GENERATED ALWAYS AS (to_tsvector('english', content)) STORED,
-  created_at TIMESTAMPTZ DEFAULT NOW(),
-  updated_at TIMESTAMPTZ DEFAULT NOW(),
-  PRIMARY KEY (label, key)
-);
-CREATE INDEX IF NOT EXISTS idx_search_entries_fts ON cf_agents_search_entries USING GIN (content_tsv);
-```
-
-#### 4. Configure wrangler
-
-```jsonc
-{
-  "compatibility_flags": ["nodejs_compat"],
-  "hyperdrive": [
-    {
-      "binding": "HYPERDRIVE",
-      "id": "<your-hyperdrive-id>"
-    }
-  ],
-  "placement": {
-    "region": "aws:us-east-1" // match your database region
-  }
-}
-```
-
-#### 5. Wire it up
-
-```typescript
-import { Agent, callable } from "agents";
-import {
-  Session,
-  PostgresSessionProvider,
-  PostgresContextProvider,
-  PostgresSearchProvider
-} from "agents/experimental/memory/session";
-import { Client } from "pg";
-
-class MyAgent extends Agent<Env> {
-  private _session?: Session;
-  private _pgClient?: Client;
-
-  /**
-   * Initialize Hyperdrive and Session when the Durable Object starts.
-   * The providers take the raw pg.Client directly — no wrapper needed.
-   */
-  async onStart(): Promise<void> {
-    const client = new Client({
-      connectionString: this.env.HYPERDRIVE.connectionString
-    });
-    await client.connect();
-    this._pgClient = client;
-
-    const sessionId = this.ctx.id.toString();
-    this._session = Session.create(
-      new PostgresSessionProvider(client, sessionId)
-    )
-      .withContext("soul", {
-        provider: {
-          get: async () => "You are a helpful assistant."
-        }
-      })
-      .withContext("memory", {
-        description: "Short facts",
-        maxTokens: 1100,
-        provider: new PostgresContextProvider(client, `memory_${sessionId}`)
-      })
-      .withContext("knowledge", {
-        description: "Searchable knowledge base",
-        provider: new PostgresSearchProvider(client)
-      })
-      .withCachedPrompt(
-        new PostgresContextProvider(client, `_prompt_${sessionId}`)
-      );
+```ts
+const unsubscribe = sessions.subscribe(async (event) => {
+  if (event.sessionId !== "") return;
+  switch (event.type) {
+    case "append":
+    case "update":
+      await updateLocalProjection(event.message);
+      break;
+    case "delete":
+    case "clear":
+    case "compact":
+    case "compaction":
+      await refreshProjection();
+      break;
+    case "import":
+      markProjectionStale();
+      break;
   }
-}
-```
-
-### How it works
-
-When `Session.create()` receives a `SessionProvider` instead of a `SqlProvider`, it skips all SQLite auto-wiring. This means:
-
-- **Context blocks need explicit providers.** No auto-wiring to SQLite — each `withContext()` call needs a `provider` option, or the block will be read-only with no storage.
-- **`withCachedPrompt()` needs an explicit provider.** Pass a `PostgresContextProvider` to persist the frozen system prompt.
-- **Broadcaster is skipped.** WebSocket status broadcasts (`CF_AGENT_SESSION` events) only work with `SqlProvider`-based sessions.
-- **All Session methods are async.** `getHistory()`, `getMessage()`, etc. return Promises since the underlying storage is async.
-
-### System prompt lifecycle
-
-- **`freezeSystemPrompt()`** — returns the cached prompt from the store. On first call (cache miss), loads blocks from providers, renders, and persists. Subsequent calls return the stored value without re-rendering. This preserves LLM prefix cache hits.
-- **`refreshSystemPrompt()`** — force reloads blocks from providers, re-renders, and updates the store. Call this to invalidate the cached prompt (e.g. after `clearMessages`).
-
-### Connection types
-
-The Postgres providers accept either of:
-
-- A raw `pg.Client` (or any object with a compatible `query(text, values)` method) — the recommended path for Hyperdrive.
-- Any object implementing `PostgresConnection` — useful for tests or custom drivers.
-
-```typescript
-// For tests or custom drivers
-interface PostgresConnection {
-  execute(
-    query: string,
-    args?: (string | number | boolean | null)[]
-  ): Promise<{ rows: Record<string, unknown>[] }>;
-}
+});
 ```
 
-Internally the providers use `?` placeholders; when a `pg`-style client is passed, those are rewritten to `$1, $2, …` automatically.
-
-### Search
-
-Two levels of search are available:
+`import` fires once per `importMessage()` and carries the row; it is deliberately not an `append`, so a projection does not patch itself per imported row during a migration — it marks itself stale and re-derives once. `compaction` fires when an overlay is stored directly through `addCompaction()`; `compact()` reports its own overlay as `compact`.
 
-- **Message search** — `PostgresSessionProvider.searchMessages()` searches conversation history via the `content_tsv` column on `assistant_messages`.
-- **Knowledge search** — `PostgresSearchProvider` provides a searchable context block backed by `cf_agents_search_entries`. The LLM can index content via `set_context` and query it via `search_context`. Uses `tsvector` + GIN index with English stemming and `ts_rank` for relevance ranking.
+This is a local cache-coherence feed, not a cross-object event log. Capability diagnostics are also emitted through Lifecycle observability.
 
-The migration SQL above includes both tables with tsvector columns and GIN indexes — search works out of the box.
+## Errors
 
----
+Sessions defines no error classes. A message that is not JSON-serializable fails with the `TypeError` that `JSON.stringify` throws, and there is no "message too large" error. A message that exceeds the row budget is split across continuation rows instead.
 
-## Utilities
+## Multiple sessions
 
-Exported from `agents/experimental/memory/utils`:
+Multiple handles can share one Durable Object:
 
-### Token Estimation
-
-```typescript
-import {
-  estimateStringTokens,
-  estimateMessageTokens
-} from "agents/experimental/memory/utils/tokens";
-
-estimateStringTokens("Hello world"); // heuristic: max(chars/4, words*1.3)
-estimateMessageTokens(messages); // sum with 4 tokens per-message overhead
+```ts
+const support = sessions.session("support");
+const sales = sessions.session("sales");
 ```
 
-### Compaction Helpers
-
-```typescript
-import {
-  createCompactFunction,
-  isCompactionMessage,
-  sanitizeToolPairs,
-  alignBoundaryForward,
-  alignBoundaryBackward,
-  findTailCutByTokens,
-  computeSummaryBudget,
-  buildSummaryPrompt,
-  COMPACTION_PREFIX
-} from "agents/experimental/memory/utils/compaction-helpers";
-```
-
-- `createCompactFunction(options)` — Full compaction implementation. See [Compaction](#compaction).
-- `isCompactionMessage(msg)` — Check if a message is a compaction overlay (id starts with `compaction_`).
-- `sanitizeToolPairs(messages)` — Fix orphaned tool call/result pairs after compaction. Removes orphaned results and adds stub results for calls whose results were dropped.
-- `alignBoundaryForward/Backward(messages, idx)` — Shift a boundary index to avoid splitting tool call/result groups.
-- `findTailCutByTokens(messages, headEnd, budget, minMessages)` — Find where to stop compressing using a token budget.
-- `computeSummaryBudget(messages)` — 20% of compressed content tokens (minimum 100).
-- `buildSummaryPrompt(messages, previousSummary, budget)` — Structured prompt for LLM summarization.
-
----
-
-## Exports
-
-Everything is exported from `agents/experimental/memory/session`:
-
-```typescript
-import {
-  // Core
-  Session,
-  SessionManager,
-
-  // Providers
-  AgentSessionProvider,
-  AgentContextProvider,
-  AgentSearchProvider,
-  R2SkillProvider,
-  PostgresSessionProvider,
-  PostgresContextProvider,
-  PostgresSearchProvider,
-
-  // Type guards
-  isWritableProvider,
-  isSkillProvider,
-  isSearchProvider,
-
-  // Types
-  type SessionMessage,
-  type SessionMessagePart,
-  type SessionContextOptions,
-  type SessionInfo,
-  type SessionManagerOptions,
-  type SessionOptions,
-  type ContextBlock,
-  type ContextConfig,
-  type ContextProvider,
-  type WritableContextProvider,
-  type SkillProvider,
-  type SearchProvider,
-  type SearchResult,
-  type SessionProvider,
-  type StoredCompaction,
-  type SqlProvider,
-  type PostgresConnection
-} from "agents/experimental/memory/session";
-```
-
-Compaction utilities from `agents/experimental/memory/utils/compaction-helpers`:
-
-```typescript
-import {
-  createCompactFunction,
-  isCompactionMessage,
-  sanitizeToolPairs,
-  COMPACTION_PREFIX,
-  type CompactResult,
-  type CompactOptions
-} from "agents/experimental/memory/utils/compaction-helpers";
-```
-
-Token utilities from `agents/experimental/memory/utils/tokens`:
-
-```typescript
-import {
-  estimateStringTokens,
-  estimateMessageTokens
-} from "agents/experimental/memory/utils/tokens";
-```
-
----
-
-## Gotchas and Quirks
-
-Things that might surprise you:
-
-1. **Lazy initialization.** Sessions created with the builder do not initialize until first use. The first call to any method (e.g. `getHistory()`) triggers `_ensureReady()`, which creates SQLite tables or initializes the configured provider, resolves providers, loads context blocks, and restores skill state from history. This means the first operation is slower than subsequent ones.
-
-2. **Snapshot freezing is sticky.** `freezeSystemPrompt()` caches the result. Writing to a context block does NOT update the cached snapshot — you must explicitly call `refreshSystemPrompt()`. This is deliberate (LLM prefix cache optimization), but easy to miss.
+Handles are cached, so per-session configuration such as the compaction trigger survives repeated `session()` calls. There is no registry table: a directory of conversations belongs to the application.
 
-3. **Session methods are async.** Always `await` reads and writes. SQLite-backed storage is local and fast, but external providers may perform network I/O, and `appendMessage` can trigger auto-compaction.
+For user-facing chat applications, prefer one Durable Object per conversation. This isolates storage and failure domains and allows conversations to hibernate independently. Use multiple handles inside one object for local branches, drafts, or application-specific namespaces.
 
-4. **Skills survive hibernation via history scanning.** On initialization, the session scans the entire conversation history looking for `load_context` tool results to reconstruct which skills are loaded. This is clever but means initialization cost scales with conversation length.
+## Chat hosts
 
-5. **Compaction overlays are superseding, not stacking.** Each compaction extends from the earliest existing `fromMessageId`. So you always have one effective overlay that keeps growing. Old compaction rows remain in the database but are unused. `getCompactions()` returns all rows, which can be confusing.
+`Think` and `AIChatAgent` use Sessions internally.
 
-6. **Search is silently absent.** `session.search()` throws if the provider does not support search, but `manager.search()` swallows FTS5 errors and returns `[]`. The `searchMessages` method on `SessionProvider` is optional (`searchMessages?`).
+- Think uses branches, compaction, search, and the change feed. Its prompt context comes from [`agents/context`](./context.md). Aged media leaves the conversation through Think's own media eviction, which is a context-window technique and unrelated to how Sessions stores a row.
+- AIChatAgent uses the default handle as a linear chain. Its existing destructive regeneration, mutable `messages` array, retention option, and wire protocol remain unchanged.
 
-7. **Fork copies with new IDs.** When forking via `SessionManager.fork()`, all messages get new UUIDs. If you are storing message IDs externally (e.g. for bookmarks), they will not survive a fork.
+Existing `assistant_*` Session tables and `cf_ai_chat_agent_messages` are lifted automatically, then dropped once every row is verified copied.
 
-8. **`removeContext` does not fire skill unload callbacks.** If you remove a context block that had loaded skills, the skill tracking is cleaned up but the conversation history is NOT rewritten. The tool results from those skills remain in history with their full content.
+## Memory boundaries and future streaming
 
-9. **FTS5 query sanitization.** Both `AgentSearchProvider.search()` and `SessionManager.search()` quote individual words to prevent FTS5 syntax injection. This means you cannot use FTS5 operators like `OR`, `NOT`, or `NEAR` — they will be treated as literal search terms.
+The capability streams history, but some consumers still require arrays.
 
-10. **Auto-compaction failure is silent.** When `compactAfter` triggers and the compaction function throws, the error is emitted via WebSocket broadcast but the `appendMessage` call still succeeds. The message is saved; only the compaction is skipped.
+| Operation                                 | Current shape                                 | Future direction                               |
+| ----------------------------------------- | --------------------------------------------- | ---------------------------------------------- |
+| History export and indexing               | Stream or bounded batches                     | Already streamable                             |
+| Tool-call lookup and reconciliation scans | Host-specific arrays in current chat packages | Can scan batches and stop early                |
+| Model request input                       | AI SDK message array                          | Must materialize a bounded model window        |
+| Compaction summarizer input               | Message array                                 | Must materialize a bounded compaction range    |
+| Legacy full-transcript client snapshots   | Message array                                 | Can move to paginated history plus live deltas |
 
-## Acknowledgments
+The chat packages retain their current public arrays and wire behavior in this release. Moving reconciliation and client history protocols to streaming requires separate protocol work.
 
-- Session's tree-structured messages are inspired by [Pi](https://pi.dev).
-- Context blocks are inspired by [Letta AI memory blocks](https://www.letta.com/blog/memory-blocks).
-- Formatting of blocks is inspired by [Hermes Agent](https://github.com/nousresearch/hermes-agent).
+See `examples/next/sessions` for a runnable server-only example.