feat(experimental): Postgres session providers with Hyperdrive support

[mattzcarey]

Summary

Adds Postgres-backed session providers for storing conversation history, context blocks, and searchable knowledge in an external database via Hyperdrive. This enables cross-DO queries, analytics, and shared state without relying on DO SQLite.

Supersedes #1196.

What's new

Providers (packages/agents/src/experimental/memory/session/providers/)

• PostgresSessionProvider — tree-structured messages, compaction overlays, message FTS via tsvector
• PostgresContextProvider — writable context block storage (memory, cached prompt)
• PostgresSearchProvider — searchable knowledge base with tsvector + GIN index

Framework improvements (packages/agents/src/experimental/memory/session/)

• Session.create() accepts SessionProvider for external storage (in addition to SqlProvider for DO SQLite)
• Hardened context tools: removed enum constraints on label params, validate inside execute, always return error strings instead of throwing (prevents orphaned tool calls with smaller LLMs)
• Simplified set_context API: removed key param, auto-generates keys from title or content slug
• Fixed prompt lifecycle: freezeSystemPrompt() returns cached, refreshSystemPrompt() force-reloads from providers
• clearMessages() calls refreshSystemPrompt() to invalidate the cached prompt
• appendToBlock() adds newline separator between entries
• Empty writable blocks render in system prompt so the LLM knows they exist
• Clean block tags: [readonly], [searchable], [loadable], [not searchable]
• Search provider get() returns entry count only (no key listing)

Example (experimental/session-planetscale/)

• Full Vite + React chat app with Hyperdrive + pg driver
• System prompt toggle, FULLTEXT search bar, connection indicator, theme toggle
• wrapPgClient helper converts ? placeholders to $1, $2, ... for pg compatibility

Tests (packages/agents/src/tests/experimental/memory/session/postgres-providers.test.ts)

• 37 tests covering: provider CRUD, message round-trip, dynamic-tool part serialization, convertToModelMessages compatibility, prompt lifecycle (freeze/refresh/invalidation/concurrent)

Docs (docs/sessions.md)

• Postgres setup guide: migration SQL, Hyperdrive config, wire-up code
• System prompt lifecycle docs
• Search provider docs (message search + knowledge search)

Migration SQL

Customers run this once — providers never create tables:

CREATE TABLE assistant_messages (
  id TEXT PRIMARY KEY, session_id TEXT NOT NULL DEFAULT '', parent_id TEXT,
  role TEXT NOT NULL, content TEXT NOT NULL, created_at TIMESTAMPTZ DEFAULT NOW(),
  content_tsv TSVECTOR GENERATED ALWAYS AS (to_tsvector('english', content)) STORED
);
CREATE TABLE 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 cf_agents_context_blocks (
  label TEXT PRIMARY KEY, content TEXT NOT NULL, updated_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE TABLE 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)
);

Test plan

• 37 unit tests passing (providers, round-trip, convertToModelMessages, prompt lifecycle)
• Deploy example and test chat flow end-to-end
• Verify search_context returns ranked results from knowledge base
• Verify clearMessages invalidates cached prompt
• Verify empty memory block renders in system prompt

---

[changeset-bot]

⚠️ No Changeset found

Latest commit: 941fc10

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[devin-ai-integration]

Devin Review found 2 new potential issues.

View 16 additional findings in Devin Review.

[devin-ai-integration]

🟡 slugify truncation causes silent key collisions when title is omitted for keyed blocks

When the LLM calls set_context for a skill or searchable block without providing a title, the key is generated via slugify(content) which truncates at 60 characters. Two different contents that share the same first 60 characters (after lowercasing and stripping non-alphanumeric chars) will produce identical keys, causing the second entry to silently overwrite the first.

For example, "The deployment process for production requires approval from security team" and "The deployment process for production requires approval from management" would both slugify to the same key. The old code required an explicit key parameter, avoiding this collision risk entirely.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Devin Review found 3 new potential issues.

View 21 additional findings in Devin Review.

[devin-ai-integration]

🟡 Hardcoded account_id and Hyperdrive ID in example wrangler.jsonc

The experimental/session-planetscale/wrangler.jsonc hardcodes account_id and a Hyperdrive id. The repository's AGENTS.md mandates "Never hardcode secrets or API keys." No other example in the repo includes account_id in its wrangler config. The Hyperdrive ID (e9c4a010628841f2a23f30d7fdceb63d) identifies a specific deployed resource tied to an individual account, and will fail for any other contributor or deployment.

Suggested change

	"$schema": "../../node_modules/wrangler/config-schema.json",
	"account_id": "543fbdef1eeaed8a02c251c8c4d9510b",
	"name": "agents-session-planetscale-example",
	"main": "src/server.ts",
	"compatibility_date": "2026-01-28",
	"compatibility_flags": ["nodejs_compat"],
	"ai": {
	"binding": "AI"
	},
	"assets": {
	"directory": "./public",
	"not_found_handling": "single-page-application",
	"run_worker_first": ["/agents/*"]
	},
	"hyperdrive": [
	{
	"binding": "HYPERDRIVE",
	"id": "e9c4a010628841f2a23f30d7fdceb63d"
	"$schema": "../../node_modules/wrangler/config-schema.json",
	"name": "agents-session-planetscale-example",
	"main": "src/server.ts",
	"compatibility_date": "2026-01-28",
	"compatibility_flags": ["nodejs_compat"],
	"ai": {
	"binding": "AI"
	},
	"assets": {
	"directory": "./public",
	"not_found_handling": "single-page-application",
	"run_worker_first": ["/agents/*"]
	},
	"hyperdrive": [
	{
	"binding": "HYPERDRIVE",
	"id": "<your-hyperdrive-id>"
	}
	],

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Devin Review found 3 new potential issues.

View 25 additional findings in Devin Review.

[devin-ai-integration]

🔴 slugify fallback key "entry" causes silent data overwrites for non-Latin content

The new slugify function strips all non [a-z0-9] characters, then falls back to "entry" if the result is empty. When the LLM doesn't provide a title (it's optional), slugify(content) is used as the key. For non-Latin content (Chinese, Japanese, Arabic, emoji-only, etc.), slugify produces "entry" for every input, causing all entries to silently overwrite each other.

Example of the collision

For a knowledge base with entries:

• set_context({ label: "knowledge", content: "用户喜欢咖啡" }) → key = "entry"
• set_context({ label: "knowledge", content: "用户的名字是小明" }) → key = "entry" (overwrites first!)

The second write silently replaces the first because both map to key "entry".

Prompt for agents

The slugify function in context.ts:24-32 strips all non-ASCII-alphanumeric characters and falls back to "entry" when nothing remains. This causes silent data loss for non-Latin content (Chinese, Japanese, Arabic, emoji, etc.) since all such content maps to the same key "entry", overwriting each other.

The function is used in the set_context tool at context.ts:673 where `slugify(title ?? content)` generates the storage key for skill/search blocks.

Possible approaches:
1. Use a hash (e.g., first 8 chars of a SHA-256 hex digest) of the full text as a fallback instead of the static "entry" string.
2. Allow Unicode letters in the slug (e.g., use a Unicode-aware regex like /[^\p{L}\p{N}]+/gu).
3. Generate a random UUID as the fallback key when the slug is empty.

Any approach must ensure that the same input consistently produces the same key (for upsert semantics), so option 1 (hash-based) is likely the best fit.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[pkg-pr-new]

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@1297

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@1297

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@1297

hono-agents

npm i https://pkg.pr.new/hono-agents@1297

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@1297

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@1297

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@1297

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@1297

commit: 941fc10

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 28 additional findings in Devin Review.

[devin-ai-integration]

🟡 set_context tool description no longer distinguishes keyed blocks from regular writable blocks

In the set_context tool's blockDescriptions at context.ts:616-618, all writable blocks are now described identically as - "label": description. Previously, skill blocks were described as "skill collection (requires key and optional description)" and searchable blocks as "searchable (requires key)". Now the LLM has no indication from the block listing that some blocks require a title parameter while others don't. The title parameter description mentions which blocks it applies to, but the block listing itself gives no hint about the different write semantics. This increases the chance the LLM will omit title for keyed blocks, falling back to slugify(content) which produces poor auto-generated keys from content text.

Prompt for agents

In context.ts around line 616-618, the blockDescriptions array maps all writable blocks identically. Previously keyed blocks (skill and searchable) had distinct descriptions like 'skill collection (requires key and optional description)' and 'searchable (requires key)'. Consider restoring distinct descriptions for keyed blocks so the LLM understands the difference. For example, after the initial map, iterate over keyedBlocks and modify their entries to add a hint like '(keyed — provide title)' to their description string.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[mattzcarey]

this feels like boilerplate. could we put this into the postgres session provider or how can we clean this up so people dont have to do this?

[mattzcarey]

why do we need this? are we only saving the text?

[mattzcarey]

I think I prefered this as an enum

[mattzcarey]

seems like this is for skills right?

so you can set_context(skill, title here, description here, content here)

need to make sure it is

`set_context("label of block", {
metadata_title: a good title,
metadata_description: "some metadata"
content: "this is the main thing here"
})

nothing needs metadata but its good to have it for longer stuff like skills (loadables). we should have this in the description of this tool.

[mattzcarey]

again. i prefer enums

[mattzcarey]

do not eg anything here.

[mattzcarey]

again enum is more concise here

[mattzcarey]

rename this to provider. not storageOrAgent

[mattzcarey]

what does reclaim mean in this context?

[mattzcarey]

is the tool addContext or add_context

[mattzcarey]

what do we need this for? I cant rememeber

[devin-ai-integration]

Devin Review found 2 new potential issues.

View 31 additional findings in Devin Review.

[devin-ai-integration]

🟡 PostgresSessionProvider.appendMessage lacks parent validation, allowing cross-session parent references

Unlike AgentSessionProvider.appendMessage (packages/agents/src/experimental/memory/session/providers/agent.ts:184-189), the PostgresSessionProvider does not validate that an explicitly supplied parentId belongs to the current session. If a caller passes a parentId that belongs to a different session (e.g., during SessionManager.fork or a bug in application code), the message will be inserted with a cross-session parent reference, silently corrupting the tree structure. The AgentSessionProvider falls back to parent = null when the parent doesn't belong to the session; the Postgres version should do the same.

Suggested change

	const parent =
	parentId !== undefined
	? parentId
	: (((await this.latestLeafRow())?.id as string | undefined) ?? null);
	const json = JSON.stringify(message);
	const text = this.extractSearchableText(json);
	await this.conn.execute(
	`INSERT INTO assistant_messages (id, session_id, parent_id, role, content, text_content)
	VALUES (?, ?, ?, ?, ?, ?)
	ON CONFLICT (id) DO NOTHING`,
	[message.id, this.sessionId, parent, message.role, json, text]
	);
	let parent =
	parentId !== undefined
	? parentId
	: (((await this.latestLeafRow())?.id as string | undefined) ?? null);
	// Validate parentId belongs to this session
	if (parent) {
	const { rows: valid } = await this.conn.execute(
	"SELECT id FROM assistant_messages WHERE id = ? AND session_id = ?",
	[parent, this.sessionId]
	);
	if (valid.length === 0) parent = null;
	}
	const json = JSON.stringify(message);
	const text = this.extractSearchableText(json);
	await this.conn.execute(
	`INSERT INTO assistant_messages (id, session_id, parent_id, role, content, text_content)
	VALUES (?, ?, ?, ?, ?, ?)
	ON CONFLICT (id) DO NOTHING`,
	[message.id, this.sessionId, parent, message.role, json, text]
	);

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🟡 captureSnapshot skips empty skill blocks that lack a .set method

The skip condition at line 498 if (!block.content && !block.writable && !block.isSearchable) continue does not check block.isSkill. A skill block backed by a read-only SkillProvider (one that implements load but not set) has writable=false, isSkill=true, isSearchable=false. When its content is empty (no skills indexed yet), the condition evaluates to true and the block is skipped from the system prompt entirely — even though the LLM should see the [loadable] block to know it can issue load_context calls. The condition should also preserve isSkill blocks, matching the intent expressed by the [loadable] tag on line 507.

Suggested change

	if (!block.content && !block.writable && !block.isSearchable) continue;
	if (!block.content && !block.writable && !block.isSearchable && !block.isSkill) continue;

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 31 additional findings in Devin Review.

[devin-ai-integration]

🟡 Race condition in getPgClient creates duplicate connections that leak

In a Durable Object, concurrent requests can interleave at await points. If two requests call getPgClient() before _pgClient is assigned, both will see _pgClient as undefined, both create a new Client, both await client.connect(), and both assign to _pgClient. The first client is orphaned — its TCP connection is never closed. The same race exists in getSession() at line 40.

Fix: use a shared connect promise

Replace the if (this._pgClient) return guard with a promise-based pattern:

private _pgConnectPromise?: Promise<Client>;
private async getPgClient(): Promise<Client> {
  if (!this._pgConnectPromise) {
    this._pgConnectPromise = (async () => {
      const client = new Client(...);
      await client.connect();
      return client;
    })();
  }
  return this._pgConnectPromise;
}

This ensures only one connection is ever created, and concurrent callers share the same promise.

Prompt for agents

The getPgClient() method has a classic check-then-act race condition. In a Durable Object, two concurrent requests can interleave at the `await client.connect()` line. Both see `_pgClient` as undefined, both create and connect a new Client, and the first one is leaked (never closed). The same pattern exists in getSession() at line 39-69.

Fix both methods by storing the in-flight promise rather than the resolved value. For getPgClient, store a `_pgConnectPromise: Promise<Client>` and assign it synchronously before the first await. For getSession, store `_sessionPromise: Promise<Session>` similarly. This ensures only one connection/session is ever created even under concurrent request interleaving.

Files: experimental/session-planetscale/src/server.ts (getPgClient at line 29, getSession at line 39)
Also affects: docs/sessions.md example at line 769-778 which shows the same pattern.

---

Was this helpful? React with 👍 or 👎 to provide feedback.