feat(experimental): SessionManager — multi-session lifecycle and search by mattzcarey · Pull Request #1167 · cloudflare/agents

mattzcarey · 2026-03-23T22:04:06Z

Summary

SessionManager: registry of named sessions with lifecycle (create/get/list/delete/rename)
Chainable builder API: SessionManager.create(agent).withContext(...).withCachedPrompt()
getSession(id) uses Session.create().forSession(id) internally — each session gets auto-namespaced provider keys (e.g. memory_chat-123, _system_prompt_chat-123)
Convenience methods: append, appendAll, getHistory, clearMessages, deleteMessages
Compaction: needsCompaction, addCompaction, compactAndSplit
Usage tracking: addUsage (input/output tokens, cost)
Cross-session FTS search with session_search tool
Tool separation: session.tools() → update_context, manager.tools() → session_search

const manager = SessionManager.create(this)
  .withContext("soul", { defaultContent: "You are helpful.", readonly: true })
  .withContext("memory", { description: "Learned facts", maxTokens: 1100 })
  .withCachedPrompt();

// Each getSession(id) auto-namespaces providers per session
const session = manager.getSession("chat-123");
const tools = { ...await session.tools(), ...manager.tools() };

Stack

1/4 — #1166 Session API core
2/4 — this PR
3/4 — #1168 Examples (depends on this)
4/4 — #1169 Think integration (depends on 3)

Test plan

13 DO-backed tests: session isolation, compaction isolation, system prompt persistence/refresh, clear isolation, manager CRUD, cross-session search, search tool, context block proxies, AgentContextProvider

changeset-bot · 2026-03-23T22:04:09Z

⚠️ No Changeset found

Latest commit: 4a29fa3

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 potential issues.

View 4 additional findings in Devin Review.

devin-ai-integration · 2026-03-23T22:09:08Z

packages/agents/src/experimental/memory/session/manager.ts

+  deleteMessages(messageIds: string[]): void {
+    for (const session of this._sessions.values()) {
+      session.deleteMessages(messageIds);
+    }
+  }


🔴 deleteMessages silently no-ops when no sessions have been accessed via getSession()

SessionManager.deleteMessages iterates over this._sessions.values(), which is an in-memory cache populated only by prior getSession() calls. If no sessions have been accessed yet, the map is empty and the loop body never executes — messages remain in the database untouched. Even when sessions are cached, the same SQL DELETE FROM assistant_messages WHERE id = ${id} (packages/agents/src/experimental/memory/session/providers/agent.ts:182) runs redundantly once per cached session, since it doesn't filter by session_id. The method should execute the deletes directly against the database rather than depending on cached session instances.

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

packages/agents/src/experimental/memory/session/manager.ts

devin-ai-integration

Devin Review found 1 new potential issue.

View 9 additional findings in Devin Review.

devin-ai-integration · 2026-03-23T23:27:48Z

packages/agents/src/experimental/memory/session/index.ts


 export { AgentContextProvider } from "./providers/agent-context";
+
+export { SessionManager, type SessionInfo, type SessionManagerOptions } from "./manager";


🔴 Missing changeset for public API addition of SessionManager

The AGENTS.md rule states: "Changes to packages/ that affect the public API or fix bugs need a changeset." This PR adds SessionManager, SessionInfo, and SessionManagerOptions to the public export of agents/experimental/memory/session (a published entry point in package.json). The .changeset/ directory contains only the auto-generated README.md and config.json — no changeset file was created for this change.

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

devin-ai-integration

Devin Review found 1 new potential issue.

View 10 additional findings in Devin Review.

devin-ai-integration · 2026-03-23T23:45:37Z

packages/agents/src/experimental/memory/session/manager.ts

+  upsert(sessionId: string, message: UIMessage, parentId?: string): string {
+    return this.append(sessionId, message, parentId);
+  }


🟡 upsert() silently drops updates to existing messages due to INSERT OR IGNORE semantics

upsert() at line 203-205 simply delegates to append(), which calls Session.appendMessage() → AgentSessionProvider.appendMessage() which uses INSERT OR IGNORE (providers/agent.ts:166). This means if a message with the same id already exists, the entire operation is silently ignored — the message content is NOT updated. A method named "upsert" should update the existing message if the ID already exists, not silently discard the new content. Callers relying on upsert semantics would lose data without any error.

Prompt for agents

In packages/agents/src/experimental/memory/session/manager.ts line 203-205, the upsert() method delegates to append(), which uses INSERT OR IGNORE and silently drops updates to existing messages. To implement true upsert semantics, upsert() should first check if the message exists (via session.getMessage(message.id)), and if so, call session.updateMessage(message) instead of appendMessage(). Alternatively, rename the method to something that doesn't imply update semantics, like appendIfNew().

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

pkg-pr-new · 2026-03-23T23:46:52Z

Open in StackBlitz

agents

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

@cloudflare/ai-chat

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

@cloudflare/codemode

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

hono-agents

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

@cloudflare/shell

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

@cloudflare/think

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

@cloudflare/voice

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

@cloudflare/worker-bundler

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

commit: 4a29fa3

SessionManager for managing multiple named sessions: - create/get/getSession/list/delete/rename - Convenience: append/appendAll/getHistory/clearMessages by session ID - compactAndSplit — end session, create new one seeded with summary - addUsage — token tracking per session - search() — cross-session FTS (queries shared table directly) - tools() — returns session_search tool for LLM use - Uses assistant_* table names for Think backward compat - 8 new tests: create/get, list, delete, rename, search, search tool, context block proxies, AgentContextProvider persistence

…viders SessionManager.create(agent) returns a SessionManager with chainable config — .withContext(), .withCachedPrompt(), .maxContextMessages(). getSession(id) now uses Session.create().forSession(id) internally, so each session automatically gets namespaced provider keys (e.g. memory_chat-123, _system_prompt_chat-123). Removes sessionOptions from constructor — context and cachedPrompt are now top-level builder methods matching Session's API.

- upsert: check-then-update or insert (was silently dropping updates) - fork: pass parentSessionId to create() for session lineage - _ensureTable: also create assistant_fts (search could fail before any session access)

devin-ai-integration bot reviewed Mar 23, 2026

View reviewed changes

mattzcarey force-pushed the feat/session-manager branch from 1731b1e to 9b4b630 Compare March 23, 2026 23:07

This was referenced Mar 23, 2026

feat(experimental): Session API — messages, context blocks, compaction, search #1166

Open

feat(experimental): session-memory and multi-session-agent examples #1168

Open

feat(think): replace SessionManager with agents Session API #1169

Open

mattzcarey force-pushed the feat/session-manager branch from 9b4b630 to 265f0dd Compare March 23, 2026 23:22

devin-ai-integration bot reviewed Mar 23, 2026

View reviewed changes

mattzcarey force-pushed the feat/session-manager branch from 265f0dd to 4a81e4d Compare March 23, 2026 23:40

devin-ai-integration bot reviewed Mar 23, 2026

View reviewed changes

This comment was marked as resolved.

Sign in to view

mattzcarey added 6 commits March 24, 2026 00:21

style: format with oxfmt

967033d

fix: CI — inputSchema, unused imports, tool casts

4a2b455

feat(session-manager): add fork and getBranches convenience methods

9d411dd

mattzcarey force-pushed the feat/session-manager branch from 068ba87 to 4a29fa3 Compare March 24, 2026 00:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(experimental): SessionManager — multi-session lifecycle and search#1167

feat(experimental): SessionManager — multi-session lifecycle and search#1167
mattzcarey wants to merge 6 commits intofeat/session-api-corefrom
feat/session-manager

mattzcarey commented Mar 23, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Mar 23, 2026 •

edited

Loading

Uh oh!

devin-ai-integration bot left a comment

Uh oh!

devin-ai-integration bot Mar 23, 2026 •

edited

Loading

Uh oh!

Uh oh!

devin-ai-integration bot left a comment

Uh oh!

devin-ai-integration bot Mar 23, 2026 •

edited

Loading

Uh oh!

devin-ai-integration bot left a comment

Uh oh!

devin-ai-integration bot Mar 23, 2026

Uh oh!

pkg-pr-new bot commented Mar 23, 2026 •

edited

Loading

Uh oh!

This comment was marked as resolved.

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant


		export { AgentContextProvider } from "./providers/agent-context";

		export { SessionManager, type SessionInfo, type SessionManagerOptions } from "./manager";

Conversation

mattzcarey commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Stack

Test plan

Uh oh!

changeset-bot bot commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

devin-ai-integration bot left a comment

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration bot Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

devin-ai-integration bot left a comment

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration bot Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration bot left a comment

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration bot Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

pkg-pr-new bot commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

mattzcarey commented Mar 23, 2026 •

edited

Loading

changeset-bot bot commented Mar 23, 2026 •

edited

Loading

devin-ai-integration bot Mar 23, 2026 •

edited

Loading

devin-ai-integration bot Mar 23, 2026 •

edited

Loading

pkg-pr-new bot commented Mar 23, 2026 •

edited

Loading