Skip to content

Commit dd87cc4

Browse files
payamcflpayamcfl
committed
feat: agent memory docs
- Add product directory entry (agent-memory.yaml) and SVG icon - Add product overview page with features, related products, and resource links - Add get-started guide: create namespace, configure binding, ingest/recall/summary - Add concepts: how Agent Memory works (extraction, classification, dedup, storage, recall pipeline, memory types, idempotency) and profiles/namespaces isolation model - Add configuration page for memory_namespaces Worker binding (single and multiple bindings, TypeScript types) - Add API reference: ingest() with Message type, timestamps, and idempotency; recall() with thinking levels, response length, and reference date; getSummary() with session scoping and summary structure - Add namespace management REST API reference (create, list, get, delete) - Add platform pages: validation limits and naming constraints, beta pricing placeholder - Add example: chat agent with memory using Workers AI (ingest, recall, getSummary in a conversation loop)
1 parent 4a16924 commit dd87cc4

20 files changed

Lines changed: 1604 additions & 0 deletions

File tree

‎src/content/directory/agent-memory.yaml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
id: aMem01
2+
name: Agent Memory
3+
4+
entry:
5+
title: Agent Memory
6+
url: /agent-memory/
7+
group: Developer platform
8+
additional_groups: [AI]
9+
tags: [AI]
10+
11+
meta:
12+
title: Cloudflare Agent Memory docs
13+
description: Persistent AI-powered memory for agents and applications — automatically extract, classify, and recall knowledge from conversations
14+
author: "@cloudflare"

‎src/content/docs/agent-memory/api/get-summary.mdx‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
title: getSummary()
3+
pcx_content_type: reference
4+
description: Generate a Markdown summary of a memory profile, organized into sections for system prompt injection.
5+
products:
6+
- agent-memory
7+
sidebar:
8+
order: 3
9+
label: getSummary()
10+
---
11+
12+
import { TypeScriptExample } from "~/components";
13+
14+
`getSummary()` generates a structured Markdown summary of everything stored in a memory profile. The summary is designed to be injected into a system prompt to give an LLM full context about a user.
15+
16+
## Signature
17+
18+
```ts
19+
profile.getSummary(options?: GetSummaryOptions): Promise<GetSummaryResponse>
20+
```
21+
22+
## Parameters
23+
24+
### `options`
25+
26+
```ts
27+
type GetSummaryOptions = {
28+
sessionId?: string | null;
29+
};
30+
```
31+
32+
| Field | Type | Default | Description |
33+
| --- | --- | --- | --- |
34+
| `sessionId` | `string` \| `null` | Most recent session | An optional session ID to scope the "Last Session" section of the summary. If omitted, the most recent session is used. |
35+
36+
## Return value
37+
38+
```ts
39+
type GetSummaryResponse = {
40+
summary: string;
41+
};
42+
```
43+
44+
| Field | Type | Description |
45+
| --- | --- | --- |
46+
| `summary` | `string` | A Markdown-formatted summary of the profile. |
47+
48+
## Summary structure
49+
50+
The generated summary is organized into the following sections, each allocated a portion of the total token budget:
51+
52+
| Section | Description | Budget share |
53+
| --- | --- | --- |
54+
| **Key Facts** | The most important facts about the user — preferences, identity, relationships, and goals. | 25-30% |
55+
| **Recent Events** | Events from the last 30 days, ordered by recency. | 25-30% |
56+
| **Active Tasks** | Current investigations, implementations, and follow-ups from the active session. | 15-20% |
57+
| **Last Session** | A summary of the most recent (or specified) session. | ~15% |
58+
| **Instructions** | Active procedures, conventions, and rules the agent should follow. | ~20% |
59+
60+
Sections with no content are omitted from the output. The summary is concise and factual, not conversational.
61+
62+
### Example output
63+
64+
```markdown
65+
## Key Facts
66+
- Prefers dark mode in all applications
67+
- Uses VS Code as primary editor
68+
- Works on the billing team
69+
- Primary language is TypeScript
70+
71+
## Recent Events
72+
- Deployed billing API v2.3.0 to production (April 15)
73+
- Completed migration from REST to GraphQL (April 10)
74+
75+
## Active Tasks
76+
- Investigating intermittent 500 errors on /users endpoint
77+
- Need to update README after refactoring
78+
79+
## Instructions
80+
- Use conventional commits: type: description
81+
- Run pnpm build && wrangler deploy --env production for deployments
82+
- Database migrations require approval before execution
83+
```
84+
85+
## Examples
86+
87+
### Basic summary
88+
89+
<TypeScriptExample>
90+
91+
```ts
92+
const profile = await env.MEMORY.getProfile("alice");
93+
const { summary } = await profile.getSummary();
94+
95+
console.log(summary);
96+
// Markdown summary of Alice's profile
97+
```
98+
99+
</TypeScriptExample>
100+
101+
### Injecting into a system prompt
102+
103+
<TypeScriptExample>
104+
105+
```ts
106+
const profile = await env.MEMORY.getProfile(userId);
107+
const { summary } = await profile.getSummary();
108+
109+
const response = await env.AI.run("@cf/meta/llama-3.3-70b-instruct-fp8-fast", {
110+
messages: [
111+
{
112+
role: "system",
113+
content: `You are a helpful coding assistant.\n\nHere is what you know about the user:\n\n${summary}`,
114+
},
115+
{ role: "user", content: userMessage },
116+
],
117+
});
118+
```
119+
120+
</TypeScriptExample>
121+
122+
### Scoping to a specific session
123+
124+
<TypeScriptExample>
125+
126+
```ts
127+
const { summary } = await profile.getSummary({
128+
sessionId: "deployment-session-42",
129+
});
130+
131+
// The "Last Session" section will reflect deployment-session-42
132+
// instead of the most recent session
133+
```
134+
135+
</TypeScriptExample>
136+
137+
## When to use `getSummary()` vs `recall()`
138+
139+
| Use case | Method |
140+
| --- | --- |
141+
| Broad context for a system prompt | `getSummary()` — Returns a comprehensive overview of the entire profile. |
142+
| Answer a specific question | `recall()` — Searches for and synthesizes an answer to a targeted query. |
143+
| Build a user profile card | `getSummary()` — Structured sections make it easy to extract key facts. |
144+
| Look up a specific fact or event | `recall()` — More efficient for targeted lookups. |
145+
146+
In many applications, you will use both: `getSummary()` to populate the system prompt at the start of a conversation, and `recall()` to fetch additional context as the conversation progresses.

‎src/content/docs/agent-memory/api/index.mdx‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
title: API reference
3+
pcx_content_type: navigation
4+
description: Complete API reference for Agent Memory, including the Worker binding methods and the namespace management REST API.
5+
products:
6+
- agent-memory
7+
sidebar:
8+
order: 5
9+
group:
10+
hideIndex: true
11+
---
12+
13+
import { DirectoryListing } from "~/components";
14+
15+
Agent Memory provides two APIs:
16+
17+
- **Worker binding API** — The primary interface for interacting with memory profiles. Accessed through the `memory_namespaces` binding in your Worker code.
18+
- [`ingest()`](/agent-memory/api/ingest/) — Extract and store memories from conversations.
19+
- [`recall()`](/agent-memory/api/recall/) — Search memories and synthesize answers.
20+
- [`getSummary()`](/agent-memory/api/get-summary/) — Generate a Markdown profile summary.
21+
22+
- **REST API** — For managing namespaces (create, list, get, delete).
23+
- [Namespace management](/agent-memory/api/namespaces/) — CRUD operations for namespaces via the Cloudflare API.
24+
25+
<DirectoryListing />

‎src/content/docs/agent-memory/api/ingest.mdx‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
title: ingest()
3+
pcx_content_type: reference
4+
description: Extract and store memories from a conversation. Agent Memory identifies facts, events, instructions, and tasks automatically.
5+
products:
6+
- agent-memory
7+
sidebar:
8+
order: 1
9+
label: ingest()
10+
---
11+
12+
import { TypeScriptExample } from "~/components";
13+
14+
`ingest()` processes a conversation and extracts structured memories from it. The system identifies facts, events, instructions, and tasks automatically — you do not need to specify what to remember.
15+
16+
## Signature
17+
18+
```ts
19+
profile.ingest(messages: Iterable<Message>, options?: IngestOptions): Promise<void>
20+
```
21+
22+
## Parameters
23+
24+
### `messages`
25+
26+
An iterable (typically an array) of `Message` objects representing the conversation to process.
27+
28+
```ts
29+
type Message = {
30+
role: "system" | "user" | "assistant";
31+
content: string;
32+
timestamp?: Date | string;
33+
};
34+
```
35+
36+
| Field | Type | Required | Description |
37+
| --- | --- | --- | --- |
38+
| `role` | `"system"` \| `"user"` \| `"assistant"` | Yes | The role of the message sender. |
39+
| `content` | `string` | Yes | The message content. Maximum 32 KB (32,768 bytes UTF-8). |
40+
| `timestamp` | `Date` \| `string` | No | When the message was sent. Accepts a `Date` object or an ISO 8601 string (for example, `"2026-04-21T12:00:00Z"` or `"2026-04-21"`). |
41+
42+
#### Timestamp resolution
43+
44+
Agent Memory determines a message timestamp using the following priority:
45+
46+
1. **Explicit `timestamp` field** — If provided, this value is used.
47+
2. **Current time** — If `timestamp` not present, the current time is used.
48+
49+
Timestamps do not affect message identity. Two messages with the same `role` and `content` but different timestamps are treated as the same message.
50+
51+
### `options`
52+
53+
```ts
54+
type IngestOptions = {
55+
sessionId?: string | null;
56+
};
57+
```
58+
59+
| Field | Type | Default | Description |
60+
| --- | --- | --- | --- |
61+
| `sessionId` | `string` \| `null` | Auto-derived | An identifier for the conversation session. Maximum 64 characters. If omitted, a deterministic session ID is derived from the message content. |
62+
63+
## Return value
64+
65+
`ingest()` returns `Promise<void>`. It does not return the extracted memories.
66+
67+
### Idempotency
68+
69+
`ingest()` is safe to call multiple times with the same messages. Message identity is content-addressed (based on the session ID, role, and content), so re-ingesting the same conversation does not create duplicates.
70+
71+
### No-op behavior
72+
73+
If the AI does not identify any memorable content in the conversation, `ingest()` completes successfully without creating any memories. The raw messages are still stored for future keyword search.
74+
75+
## Examples
76+
77+
### Basic ingestion
78+
79+
<TypeScriptExample>
80+
81+
```ts
82+
const profile = await env.MEMORY.getProfile("alice");
83+
84+
await profile.ingest([
85+
{ role: "user", content: "I prefer dark mode and use VS Code." },
86+
{ role: "assistant", content: "Noted your preferences for dark mode and VS Code." },
87+
]);
88+
```
89+
90+
</TypeScriptExample>
91+
92+
### With a session ID
93+
94+
<TypeScriptExample>
95+
96+
```ts
97+
await profile.ingest(
98+
[
99+
{ role: "user", content: "Deploy the API to production." },
100+
{ role: "assistant", content: "Deployed v2.3.0 to production successfully." },
101+
],
102+
{ sessionId: "deployment-session-42" },
103+
);
104+
```
105+
106+
</TypeScriptExample>
107+
108+
### With explicit timestamps
109+
110+
<TypeScriptExample>
111+
112+
```ts
113+
await profile.ingest([
114+
{
115+
role: "user",
116+
content: "We decided to use PostgreSQL for the new service.",
117+
timestamp: "2026-04-15T14:30:00Z",
118+
},
119+
{
120+
role: "assistant",
121+
content: "Understood. I will recommend PostgreSQL for the new service going forward.",
122+
timestamp: "2026-04-15T14:30:05Z",
123+
},
124+
]);
125+
```
126+
127+
</TypeScriptExample>
128+
129+
## Limits
130+
131+
| Parameter | Limit |
132+
| --- | --- |
133+
| Messages per call | 500 |
134+
| Message content size | 32 KB (32,768 bytes UTF-8) |
135+
| Session ID length | 64 characters |
136+
137+
Refer to [Limits](/agent-memory/platform/limits/) for the complete list of constraints.

0 commit comments

Comments
 (0)