导航|地址|刷新
Conversation state and memory

Skip to contentDocumentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/agents/llms.txt
Use this file to discover all available pages before exploring further.



DocsDirectoryAPISDKsChangelog

Search

Log in






Agents

/




Overview


Getting started


Quick start

Add to existing project

Testing your Agents






Concepts


What are agents?

Conversation state and memory

Tools

Calling LLMs

Using Agents with Workflows


Agentic patterns


Overview

Human-in-the-loop patterns

Long-running agents










Communication channels



Chat


Chat agents

Autonomous responses

Client SDK





Voice

Email

Slack


Webhooks


Overview

Push notifications










Tools


Sandbox

MCP

Browser

AI Search


Agentic Payments


Overview

Charge for HTTP content


x402


Overview

Charge for HTTP content

Charge for MCP tools

Pay from Agents SDK

Pay from coding tools





MPP (Machine Payments Protocol)






Code Mode


Overview

Create a durable Code Mode runtime

AI SDK integration

Use Code Mode with TanStack AI

Browser-owned tools

MCP

OpenAPI

How Code Mode works

Code Mode API reference










Harnesses


Overview


Think


Overview

Getting started

Configuration

Tools

Actions

Lifecycle hooks

Client tools

Messengers

Channels

Scheduled tasks

Workflows

Sub-agent RPC and programmatic turns

Programmatic submissions

Durable recovery










Runtime


Agents API


Lifecycle


Agent class internals

Callable methods

Store and sync state

Sessions

getCurrentAgent()






Communication


Routing

WebSockets

HTTP and Server-Sent Events

Chat SDK

Protocol messages

Readonly connections






Execution


Sub-agents

Schedule tasks

Durable execution with fibers

Queue tasks

Retries

Run Workflows

Agents as tools

Agent Skills






Operations


Configuration

Cross-domain authentication

Using AI Models

Observability










Examples


Chat agent

Slack agent

Voice agent

Browser agent

Email agent






Model Context Protocol (MCP)


Overview


APIs


MCP handler APIs

McpAgent

McpClient






Protocol


Tools

Authorization

Transport

MCP governance






Guides


Build MCP client

Build a Remote MCP server

Test a Remote MCP Server

Securing MCP servers

Connect to an MCP server

Handle OAuth with MCP servers

Migrate to MCP SDK v2

Build a single-tool Code Mode MCP server

Build a search and execute MCP server






Cloudflare


MCP server portals ↗


Cloudflare's own MCP servers


Overview

Cloudflare Community MCP Server









Code Mode MCP server patterns






Platform


Limits






Agent resources


Agent setup ↗

Cloudflare Skills ↗

Code Mode MCP Server ↗

Domain-specific MCP Servers ↗MCP

Agents llms.txt ↗

Agents llms-full.txt ↗

Cloudflare Docs llms.txt ↗

Cloudflare Docs llms-full.txt ↗













Home

/Agents

/Concepts

/Conversation state and memory



Conversation state and memory


Last updated Jun 3, 2026|Copy as Markdown|View as Markdown|Agent setup

OverviewConversation historyContext memory Read-only context Writable short-form context Searchable context Loadable context (Skills)How agents interact with memory Generated toolsThe system promptGotchas Prompt caching CompactionRelated




Agents need memory to be useful over time. Without it, every conversation starts from zero. The agent forgets who the user is, what it learned, and what it was doing. Memory is what turns a stateless LLM call into a persistent, context-aware agent.

The Session API provides the memory layer for agents built on the Cloudflare Agents SDK. It manages two kinds of memory: conversation history (the messages and tool calls that make up a session) and context memory (persistent blocks injected into the system prompt that the agent can read, write, search, and load).

Use this page when you need more than simple synced state or flat chat history. For small UI state, use Store and sync state. For basic chat persistence, AIChatAgent stores messages for you. For opinionated long-term memory, Think builds on Session and context blocks.


Experimental


The Session memory APIs currently use agents/experimental/memory/session. The concepts are stable, but import paths and details may change before graduation.




Conversation history


The most fundamental type of memory is the conversation itself: the messages between the user and the agent, the tool calls the agent made, and the results it received. The Session stores all of this in a tree-structured message history backed by a Session Provider, defaulting to SQLite.






import { Session } from "agents/experimental/memory/session";// Append messages as the conversation progressesawait session.appendMessage({ id: `user-${crypto.randomUUID()}`, role: "user", parts: [{ type: "text", text: "What's the status of the deployment?" }],});// Read the full conversation historyconst history = await session.getHistory();

import { Session } from "agents/experimental/memory/session";// Append messages as the conversation progressesawait session.appendMessage({ id: `user-${crypto.randomUUID()}`, role: "user", parts: [{ type: "text", text: "What's the status of the deployment?" }],});// Read the full conversation historyconst history = await session.getHistory();




Conversation history persists across Durable Object hibernation and eviction. When the agent wakes up, the full history is available in SQLite. It does not need to be replayed or reconstructed.

Messages are stored in a tree structure via parent_id, which enables branching conversations. When you appendMessage with a parentId that already has children, you create a branch, useful for features like response regeneration. getHistory(leafId) walks any chosen path through the tree.

The Session also provides full-text search across the conversation history:






const results = await session.search("deployment Friday", { limit: 10 });

const results = await session.search("deployment Friday", { limit: 10 });




As conversations grow long, compaction summarizes older messages to keep the context window manageable without losing the underlying data.


Context memory


Context memory is persistent information injected into the system prompt, separate from the conversation history. It gives the agent access to identity, instructions, learned facts, knowledge bases, and reference material across every turn.

The Session API supports four types of context memory, each suited to different kinds of information. The type is determined by the provider backing the context block. The Session detects the provider's capabilities automatically.


Read-only context


This is your traditional system prompt: the agent's identity, personality, and instructions. You might write it directly in your codebase, load it from a SOUL.md file in R2, or fetch it from an API. The content is injected into the system prompt and the agent cannot modify it.

A coding assistant might have a soul that defines its personality and constraints:






import { Session } from "agents/experimental/memory/session";const session = Session.create(this).withContext("soul", { provider: { get: async () => "You are a senior TypeScript engineer. You write concise, " + "well-tested code. You prefer composition over inheritance. " + "When you are unsure, you say so rather than guessing.", },});

import { Session } from "agents/experimental/memory/session";const session = Session.create(this).withContext("soul", { provider: { get: async () => "You are a senior TypeScript engineer. You write concise, " + "well-tested code. You prefer composition over inheritance. " + "When you are unsure, you say so rather than guessing.", },});




Or load it from R2 so you can update the agent's personality without redeploying:






const session = Session.create(this).withContext("soul", { provider: { get: async () => { const obj = await env.CONFIG_BUCKET.get("soul.md"); return obj ? obj.text() : "You are a helpful assistant."; }, },});

const session = Session.create(this).withContext("soul", { provider: { get: async () => { const obj = await env.CONFIG_BUCKET.get("soul.md"); return obj ? obj.text() : "You are a helpful assistant."; }, },});




Read-only blocks are defined by providing an object with only a get() method. No tools are generated. The content appears in the system prompt and the agent has no way to change it.


Writable short-form context


Think of this as a scratchpad the agent maintains for itself, a place to jot down things it needs to remember. Like how Claude Code keeps a todo list of tasks to work through, or how a customer support agent might track what it has learned about the user during the conversation.






const session = Session.create(this) .withContext("memory", { description: "Important facts learned during conversation", maxTokens: 1100, }) .withContext("todos", { description: "Task list, track what needs to be done and what is complete", maxTokens: 2000, });

const session = Session.create(this) .withContext("memory", { description: "Important facts learned during conversation", maxTokens: 1100, }) .withContext("todos", { description: "Task list, track what needs to be done and what is complete", maxTokens: 2000, });




When you omit the provider option in the builder, the Session auto-wires to a SQLite-backed writable provider. The agent gets a set_context tool that lets it replace or append content to these blocks. Token limits are enforced, so the agent cannot write more than the maxTokens budget allows.

The system prompt renders writable blocks with a token usage indicator so the agent knows how much space it has left:
══════════════════════════════════════════════MEMORY (Important facts learned during conversation) [45% — 495/1100 tokens] [writable]══════════════════════════════════════════════User prefers dark mode.User's project uses React and TypeScript.Deployment target is Cloudflare Workers.══════════════════════════════════════════════TODOS (Task list) [12% — 240/2000 tokens] [writable]══════════════════════════════════════════════- [x] Set up project scaffolding- [ ] Add authentication middleware- [ ] Write integration tests
The content persists across messages and survives hibernation. It is always visible in the system prompt, so the agent sees it on every turn without needing to fetch anything.


Searchable context


When you have a large body of information (a knowledge base, documentation, logs, accumulated notes) you do not want to stuff it all into the system prompt. Searchable context keeps a summary in the system prompt (for example, "42 entries indexed") and lets the agent retrieve specific entries when it needs them.

You provide a provider with a search() method. How that search works is entirely up to you: full-text search, vector search via Vectorize, a call to an external API, or anything else. The Session does not care about the implementation, only that the provider has a search() method.

The built-in AgentSearchProvider uses Durable Object SQLite with FTS5 as default:






import { AgentSearchProvider } from "agents/experimental/memory/session";const session = Session.create(this).withContext("knowledge", { description: "Searchable knowledge base, search for relevant information before answering", provider: new AgentSearchProvider(this),});

import { AgentSearchProvider } from "agents/experimental/memory/session";const session = Session.create(this).withContext("knowledge", { description: "Searchable knowledge base, search for relevant information before answering", provider: new AgentSearchProvider(this),});




But you can implement your own provider backed by any search mechanism:






const session = Session.create(this).withContext("knowledge", { description: "Searchable knowledge base", provider: { get: async () => "Product documentation and FAQs", search: async (query) => { // Use Vectorize, an external API, whatever you need const results = await env.VECTORIZE_INDEX.query( await generateEmbedding(query), { topK: 5 }, ); return results.matches.map((m) => m.metadata.text).join("\n\n"); }, set: async (key, content) => { // Index new content }, },});

const session = Session.create(this).withContext("knowledge", { description: "Searchable knowledge base", provider: { get: async () => "Product documentation and FAQs", search: async (query) => { // Use Vectorize, an external API, whatever you need const results = await env.VECTORIZE_INDEX.query( await generateEmbedding(query), { topK: 5 }, ); return results.matches.map((m) => m.metadata.text).join("\n\n"); }, set: async (key, content) => { // Index new content }, },});




The agent gets a search_context tool for querying and a set_context tool for indexing new entries. It decides what to search for, and you decide how the search works.

This is the right choice when the agent needs to find specific pieces of information from a large collection, rather than loading entire documents.


Loadable context (Skills)


Skills are large pieces of context (complete documents, reference guides, runbooks, templates) that the agent can discover and load on demand. Think of them as reference material on a shelf: the agent sees a list of titles and descriptions, picks what is relevant to the current task, loads it, uses it, and unloads it when done.

Unlike searchable context where the agent retrieves small chunks from a larger collection, skills are designed to be loaded whole. When an agent loads a skill, it gets the entire document in its context window.

Skills are backed by the SkillProvider interface. A skill provider has three methods:

get() returns a metadata listing (titles and descriptions) that appears in the system prompt

load(key) fetches the full content of a specific skill

set(key, content, description?) writes or updates a skill entry (optional)

The system prompt shows available skills as a listing. The [loadable] tag tells the LLM that these entries are not inline. It needs to use a tool to access the full content:
══════════════════════════════════════════════SKILLS [loadable]══════════════════════════════════════════════- api-ref: API Reference documentation- style-guide: Company style guide- deploy-checklist: Production deployment checklist
The agent sees the titles, decides which skill is relevant to the current task, and uses load_context to pull the full content into its working context. When it is done, it uses unload_context to free the space. When the skill provider implements set(), the agent can also write back, updating existing skills or creating new ones.
Agent sees: "- deploy-checklist: Production deployment checklist"User asks: "Walk me through a production deployment"Agent calls: load_context({ block: "skills", key: "deploy-checklist" })→ Full checklist content is loaded into the agent's working context

R2-backed skills


The built-in R2SkillProvider stores skills in a Cloudflare R2 bucket. Each skill is an R2 object with optional custom metadata for descriptions.






import { Session, R2SkillProvider }
…(内容过长已截断)

------
导航页 打开网址