Cloudflare Agent Memory Practical Guide: Why you should design memory structures before prompts as agents work longer

Publication date: 2026-04-25 | Category: Development information

This article explains what teams should lock in first when designing long-running agents, based on the Agent Memory released by Cloudflare at Agents Week in April 2026. The key is to separate “what to remember and what to discard” into operational layers, not “longer context”.

1. One-line problem definition

Summary: When agents start working for a few days or weeks, the memory structure becomes the bottleneck before model performance.

For a short chatbot, it is enough to continue a conversation for just a few turns, but coding agents, operating agents, and internal tool agents are different. They must keep in mind people preferences, architecture decisions, failure history, and ongoing tasks. However, cramming all of this into the prompt increases the cost, and as the context gets longer, important information is buried, resulting in so-called context rot.

Target audience is developers, platform engineers, and technical leads who want to create long-running agents or team assistant agents based on Cloudflare Workers. This article focuses on designing a memory layer that persists beyond sessions. Cases where only a simple FAQ chatbot, a file search type RAG is needed, or cases where the agent is completed within a single request are partially excluded from the scope of application.

2. First, conclusion

Summary: Agent Memory is suitable for dealing with "team memories accumulated during work", not "knowledge base".

My judgment is clear. If you're building a long-running agent on top of Cloudflare, and the same agent needs to reuse people preferences, operating rules, and recent decisions across multiple sessions, Agent Memory is definitely worth looking into now. On the other hand, if most of the work is completed within a single session, or if the information to be stored is centered around document files, it is better to first use the short memory of the Session API or a separate search layer.

To put it simply, Agent Memory is not a tool to make the prompt longer, but a tool that keeps the prompt short and retrieves only the necessary memories. So, teams that set “memory promotion criteria” first do better than teams that “save everything”.

3. Decomposition of core structure

Summary: The core of this architecture is to divide the conversation history, extraction pipeline, and retrievable memory into different layers.

Based on the Cloudflare document, Agent Memory can be broadly understood as four layers.

1. Session/Conversation Layer: Original conversations and tool calls are kept in the session history. This is more of a ledger that preserves “what happened”.
2. Extraction·Verification Layer: At the time of context compression, facts, instructions, events, and tasks are extracted from the conversation and duplicates are removed. Cloudflare calls this process ingestion.
3. Memory storage layer: Agent Memory stores, classifies, and searches memories by combining Durable Objects, Vectorize, and Workers AI. Rather than storing the original file, we leave a structured memory of the session.
4. Recall Layer: Agents deal with memory with limited tools such as recall, remember, forget, list. You don't have to design your own database queries.

The reason this layer separation is important is because the roles are different. The conversation log leaves evidence, the memory layer leaves only information that can be reused for future work, and the retrieval layer retrieves only what is needed now. Cloudflare also explains that Agent Memory and AI Search have different purposes. Document search is left to AI Search, and persistent memory extracted from the session is left to Agent Memory.

4. Description of design intent

Summary: Cloudflare chose the direction of “don’t make the model worry about the storage strategy”

What I value most here is the API design philosophy. Many teams try to solve memory problems with database access. But then the model has to think about query strategy, filter conditions, and storage format within the prompt, wasting tokens. Agent Memory intentionally prevents this. Tools for dealing with memory are narrowly limited: recall, remember, forget, list.

The advantages of this choice are threefold. First, it focuses the model on “what it should do.” Second, the platform standardizes storage formats and search strategies, improving operability. Third, rules such as verification, deduplication, and supersession can be changed centrally later.

An alternative is to give up. Free data exploration, custom schemas, and specialized search strategies can be less flexible. In other words, Agent Memory is closer to operational default than the research sandbox. This makes it a good "first choice for production teams," but not a complete answer for teams doing highly custom memory research.

5. Evidence and Comparison

Summary: Agent Memory's competitors are not just other memory services, but also include prompt fixation and session scratchpad.

Cloudflare released Agent Memory as a private beta on April 17, 2026, and in an internal case released on April 20, it was revealed that 3,683 internal users used the AI ​​coding tool as of the same week, and processed 20.18M AI Gateway requests and 241.37B tokens per month. These numbers can be seen as evidence that memory capabilities are not just a demo, but are tied to the operation of a real, large-scale development organization.

• Cost criteria: Session API Scratchpad has the lowest initial cost, but the prompt load increases in the long run. Agent Memory is closer to lowering long-term token costs instead of adding a memory promotion pipeline.
• By time: Workers-based teams can acquire Agent Memory the fastest. Conversely, if you are already running LangGraph or a third-party memory service, you must consider the switching cost.
• Accuracy criteria: We do not store any memories, and the rules for choosing which information to promote determine accuracy. Operating rules are more important than memory systems.
• Operation criteria: If you want to bundle inference, memory, and security within the same network and the same developer platform, Cloudflare has a big advantage.

6. Actual operation flow / step-by-step execution method

Summary: Starting is more about deciding “when to ingest and when to recall” rather than saving.

1. Divide the memory profile first.
   You must separate the profiles by individual, team, and project. For example, it is better to divide them according to purpose, such as frontend-team, incident-bot, customer-success.
2. Attach an ingest at the point of compaction.
   When truncating a long conversation, don't just save the summary, you should run memory extraction at that point. Otherwise the old context will evaporate.
3. Insert recall right before execution.
   Do not recall unconditionally at every turn, but call it only at steps where mistakes need to be reduced, such as code writing, distribution, and customer response.
4. remember Set criteria in human language.
   Example: Only “architectural decisions”, “recurring error sources”, “user preferences”, “security exception approvals” into long-term memory. You are promoted.
5. Put forget and supersession rules.
   Operation policy changes. If you don't delete or replace old guidelines, old memories will taint your current rules.

export default {
  async fetch(request, env) {
    const profile = await env.MEMORY.getProfile("frontend-team");

    await profile.ingest([
{ role: "user", content: "The frontend only uses pnpm." },
{ role: "assistant", content: "Okay, I'll leave out the npm script examples." },
{ role: "user", content: "Before deployment, a Lighthouse mobile score of 90 or higher is considered the standard." }
    ], { sessionId: "deploy-0425" });

const recall = await profile.recall("Please tell me the front-end deployment standards for this team");
    return Response.json({ memory: recall.result });
  }
}

In practice, when to call is more important than this code. My recommended order is “short note during session → ingest during compaction → recall right before important execution → forget when changing policy”.

7. Pitfalls

Summary: When you have a memory system, you usually make two mistakes: saving too much or, conversely, trusting without verification.

1. Pitfall: Promote all conversations to long-term memory
   Prevention: Memory promotion criteria into 4-6 categories Limit:
   Recovery: Review the last two weeks of memory to delete duplicate/one-off items, and return task information to session TODO.
2. Pitfall: Confusing file search with memory
   Prevention: The original text of the document is AI Search/RAG, persistent information extracted from the session is Memory. Separate roles:
   Recovery: Classify search failure cases and label them as “document issues” or “memory issues”
3. Pit: Old policy overwrites new policy
   Prevention: When policy changes, supersession rules and delete permissions are disabled. Set:
   Recover: Trust only memories with a change date, or add a recency filter to recall results.
4. Pitfall: Model uses memory as absolute truth
   Prevention: Distribution, security, and money-related operations are not confirmed by memory alone, but original text. Forces evidence to be looked up again.
   Recovery: Places a "memory + source verification" double gate for high-risk operations.

8. Strengths and Limitations

Summary: The strength of Agent Memory is that it is an operational default, and the limitation is that it is not yet a general-purpose memory research platform.

• Strength 1: Short introduction path as it is tied within the same platform as Workers, AI Gateway, and Agents SDK.
• Strength 2: Narrow interface like recall/remember/forget/list, so the model does not waste tokens on storage strategies.
• Strength 3: The use case for team shared memory is clear. The structure in which the coding agent and the code review bot share the same memory is especially practical.
• Limit 1: As it is a closed beta as of April 2026, it is not subject to immediate adoption by all teams.
• Limitations 2: Network perimeter and vendor dependencies can be burdensome for stack-centric teams outside of Cloudflare.
• Limitation 3: Full-text document search, large-scale knowledge base exploration, and complex custom inference should be used with a separate search layer.

So my recommendation is this. Teams that will run agents on Cloudflare should now design file retrieval and memory retrieval separately, and multicloud teams should first document memory promotion rules and then select tools. Rules come before tools.

9. Points to study more deeply

Summary: More important study points than attaching memory are compaction, recency, and sharing range.

• compaction design: At what point should you decide to reduce a session and promote it to memory?
• memory profile design: You must first decide to which extent you want to share memories: individual/team/project.
• Recency rules: Date and supersession rules are required for highly time-sensitive information, such as policy changes, exception approvals, and rollback records.
You must learn the structure of using
• Search Search:Agent Memory and AI Search together. The key point is that memory is a by-product of the session, and retrieval is based on the original text.
• Cost observation: If you do not measure recall frequency, storage amount, and unnecessary memory ratio, your memory will eventually become another prompt obesity.

10. Reference

• Cloudflare Blog - Agents that remember: introducing Agent Memory (Published date: 2026-04-17, Confirmed date: 2026-04-25)
• Cloudflare Blog - The AI ​​engineering stack we built internally — on the platform we ship (Published date: 2026-04-20, Confirmed date: 2026-04-25)
• Cloudflare Blog - Cloudflare’s AI Platform: an inference layer designed for agents (Published date: 2026-04-16, Confirmed date: 2026-04-25)
• Cloudflare Developers - Memory (Confirmation date: 2026-04-25)
• Mem0 Docs - Platform Overview (Confirmation date: 2026-04-25)
• Cloudflare Blog - Building the agentic cloud: everything we launched during Agents Week 2026 (Published date: 2026-04-20, Confirmed date: 2026-04-25)

11. Action Checklist + Author's Perspective

Summary: What to check before introduction is the memory boundary and verification rules rather than the number of functions.

• Information categories to be promoted to long-term memory are limited to 4 to 6
• Defined memory profile boundaries for each individual/team/project
• Ingest is connected to run automatically during compaction
• The standard for recall was set to be called only in high-risk stages
• Documented forget or supersession procedure when changing policy
• Original text verification gate was added to distribution, security, and monetary operations
• The document search layer and memory layer were designed separately

Definition of Done: If the agent reliably reuses the same team rules across sessions, incorrect past memories do not contaminate high-risk tasks, and recall results can be verified with operational logs, the first round of introduction is considered complete.

My recommendation is not to be a “team that accumulates a lot of memories,” but to be a team that selects and promotes memories. For teams already using the Cloudflare stack, Agent Memory is one of the most viable options this year. However, if the agent is still focused on short sessions, finish separating the Session API notes and searches first. If you reverse that order, the memory system will retain the problem longer rather than solve it.