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: e416388

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.

Suggested change

	const key = slugify(title ?? content);
	const key = title ? slugify(title) : `${slugify(content)}-${Array.from(new TextEncoder().encode(content)).reduce((h, b) => (((h << 5) - h) + b) | 0, 0).toString(36).replace('-', 'n')}`;

---

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 1 new potential issue.

View 22 additional findings in Devin Review.

[devin-ai-integration]

🔴 DO-backed test agent passes removed key parameter to set_context tool

The set_context tool was refactored to use title instead of key for keyed blocks (skill/search providers). The tool's execute function destructures { label, content, title, action } (packages/agents/src/experimental/memory/session/context.ts:657-667). However, the TestSearchAgent integration test agent still passes key as a parameter (e.g., key: "meeting-notes") which is silently ignored. The key is auto-generated via slugify(content) instead, producing keys like the-deployment-is-scheduled-for-friday-with-budget-concerns. The test then asserts r1.includes("meeting-notes") which will fail since that key was never stored. The testUpdateReplacesEntry method has the same issue — it passes key: "doc" twice with different content, but the slugified keys will differ, so the second write creates a new entry instead of updating the first.

(Refers to lines 158-167)

Prompt for agents

The set_context tool was refactored from using a `key` parameter to `title`. The TestSearchAgent class in packages/agents/src/tests/agents/session.ts needs to be updated:

1. testIndexAndSearch (line 158-167): Change `key: "meeting-notes"` to `title: "meeting-notes"` and `key: "design-doc"` to `title: "design-doc"`. The assertions checking for these keys in search results should also use the slugified versions of the titles (which happen to be the same: "meeting-notes" and "design-doc").

2. testUpdateReplacesEntry (line 242-250): Change both `key: "doc"` to `title: "doc"`. Since slugify("doc") = "doc", the upsert behavior should work correctly with this fix.

3. testInitLifecycle (line 219): The assertion `prompt.includes("search_context")` needs to be changed to `prompt.includes("[searchable]")` since the prompt format now uses tag-style markers instead of tool name hints.

---

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.

[devin-ai-integration]

🔴 appendMessage with explicit parentId: null incorrectly auto-detects parent instead of creating a root message

In PostgresSessionProvider.appendMessage, parentId uses nullish coalescing (??) which treats both null and undefined the same way. When called with explicit parentId: null (meaning "create a root message with no parent"), the code falls through to latestLeafRow() and attaches the message as a child of the latest leaf instead.

Code path

At postgres.ts:125-126:

const parent =
  parentId ?? ((await this.latestLeafRow())?.id as string) ?? null;

If parentId is null, null ?? latestLeaf evaluates to latestLeaf, not null. The SessionProvider interface at provider.ts:57-60 declares parentId?: string | null, where null should mean "no parent" and undefined/omitted should mean "auto-detect".

This breaks the branching contract — callers who explicitly pass null to create a root message get an unexpected parent chain instead. The AgentSessionProvider at providers/agent.ts likely has the same distinction via its SQL logic.

Suggested change

	const parent =
	parentId ?? ((await this.latestLeafRow())?.id as string) ?? null;
	const parent =
	parentId !== undefined
	? parentId
	: (((await this.latestLeafRow())?.id as string) ?? null);

---

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

[devin-ai-integration]

🟡 Skill restoration silently skipped for async providers, losing loaded-skill tracking after hibernation

_restoreLoadedSkills() at packages/agents/src/experimental/memory/session/session.ts:214-216 checks if (history instanceof Promise) return and silently skips skill restoration for all async SessionProvider implementations (including the new PostgresSessionProvider). After DO hibernation/eviction, skills that were loaded via load_context are forgotten — the _loadedSkills set is empty. This means unload_context reports "not currently loaded" for skills that are actually loaded in the conversation, and the unload_context tool description shows "No skills currently loaded" even when skills are present in history.

Prompt for agents

In session.ts _restoreLoadedSkills(), the method skips entirely when the provider is async (returns a Promise from getHistory). This causes loaded skills to be silently lost after hibernation for Postgres-backed sessions.

Consider making _restoreLoadedSkills async and calling it with await in _ensureReady. Since _ensureReady is called at the start of every Session method (which are all now async), making it async should be safe. Alternatively, defer the restore to the first async method call (e.g. inside getHistory or tools) so it runs before the data is needed.

The key issue is in _ensureReady (line 157) which is synchronous. Either make _ensureReady async and await skill restoration, or lazily restore skills on first async use.

---

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