Claude Agent SDK: Adding Persistent Memory

A developer builds an internal code review agent using the Claude Agent SDK. The agent reviews pull requests, references the team's style guide, and gives feedback tailored to the codebase. It works well—within a single review session. But when the same developer submits another PR next week, the agent doesn't remember the conventions it learned, the patterns it flagged before, or the developer's coding style. Every review starts from zero.

The Claude Agent SDK is stateless by design. Every invocation is independent. This architectural choice has real advantages—reproducibility, clean debugging, no hidden state. But it means persistent memory is entirely your responsibility. In this guide, I'll walk you through how to architect a persistent memory layer for Claude-based agents, from simple key-value stores to production-grade memory platforms.

Why Statelessness Is Actually a Feature

The Claude SDK's stateless architecture forces you to own your context pipeline explicitly. There's no ConversationBufferMemory that works in demos and breaks in production. No session-scoped store that creates false confidence. You know from day one that you need memory infrastructure, and you design for it.

This is a genuine advantage for production systems. Every piece of context the agent sees is something you deliberately provided. When the agent gives a wrong answer, you can trace it to the exact context you injected—not to some accumulated memory artifact from prior sessions that you didn't control.

The disadvantage is that you start with nothing. The SDK handles tool calling, reasoning, and response generation. You handle everything else: user identity, conversation history, learned facts, temporal context, and retrieval. Claude Agent SDK Memory: Tool Use Without Context covers what the SDK provides and where the boundary sits.

What Persistent Memory Looks Like

User Identity and Profile

The first requirement is knowing who the user is. Before the agent processes a request, you need to resolve user identity and load their profile. This profile includes facts learned from prior interactions: their role, industry, preferences, technical level, and any specific context they've shared.

For the code review agent example, the user profile might include: primary language (TypeScript), preferred style (functional, minimal comments), codebase conventions (barrel exports, custom hook naming), and past feedback patterns (tends to over-abstract, benefits from concrete examples).

This profile gets injected into the system prompt at session start. The agent reads it as context and adapts its behavior accordingly. The SDK doesn't know where this context came from—it just processes it like any other input.

Conversation Summaries

Raw conversation history is noisy and expensive to inject. A 45-minute code review session might produce thousands of tokens of back-and-forth, but the actionable knowledge—the conventions identified, the issues flagged, the decisions made—might compress to a few hundred tokens.

Persistent memory should store compressed summaries of prior interactions, not full transcripts. Extract the key facts, decisions, and preferences from each session and store them as structured knowledge. When the user returns, inject the summaries, not the transcripts.

Temporal Versioning

Facts change over time. A user might prefer React today and Vue next month. Their team's coding standards might evolve. The codebase itself changes continuously. Persistent memory needs to version facts—storing new values without overwriting old ones, timestamping each version, and retrieving the correct version based on context.

Without temporal versioning, the agent will eventually reference outdated information. It'll suggest a pattern the team abandoned, or reference a dependency that was removed. Context windows are not memory explains why flat context injection makes this problem worse—the agent can't distinguish current facts from historical ones in an unstructured prompt.

Cross-Session Learning

Each interaction should make the agent smarter for the next one. If the code review agent learns that a particular developer frequently forgets error handling, it should proactively check for error handling in future reviews. If it learns that the team recently adopted a new testing framework, it should adjust its review criteria.

Cross-session learning requires extraction logic that identifies learnings from each session and stores them in a way that's retrievable for future sessions. This is where memory goes beyond simple persistence—it's not just storing what happened, but distilling what was learned.

The Claude SDK's stateless architecture actually makes cross-session learning cleaner to implement than in frameworks with built-in memory. Because you control the entire context pipeline, you can design the extraction and injection logic precisely for your domain. There's no framework-level memory system to conflict with or work around. The tradeoff is that you do more work upfront, but the result is a memory system that fits your exact needs rather than a generic abstraction that almost fits.

Architecture Options

Simple: Key-Value Profile Store

Store user profiles in a key-value database (Redis, DynamoDB, or even a JSON file). Before each Claude SDK invocation, load the profile and inject it into the system prompt. After each invocation, update the profile with any new facts.

This works for simple agents with limited user context. The implementation is straightforward—a few database calls around the SDK invocation. But it doesn't scale to complex context, has no temporal reasoning, and requires manual decisions about what to store and retrieve. As your user base grows and context accumulates, you'll find that key-value lookups return too much or too little—there's no semantic understanding of what's relevant to the current query.

For many teams, this is still the right starting point. It proves the value of memory quickly and helps you understand what types of context matter most for your specific use case before investing in more sophisticated infrastructure.

Intermediate: Vector Store + Extraction Pipeline

Use an LLM to extract structured facts from each conversation. Store those facts as embeddings in a vector database. Before each session, query the vector store for facts relevant to the user and the current query. Inject the retrieved facts into the system prompt.

This approach handles larger context volumes and provides semantic retrieval. But vector retrieval alone lacks temporal reasoning—it returns the most semantically similar facts, not the most recent or most relevant. You'll need additional logic to handle fact versioning, conflict resolution, and retrieval quality. Stateful AI agents covers the architectural patterns this requires.

Production: Managed Memory Platform

Connect the Claude SDK to a managed memory platform that handles extraction, persistence, temporal reasoning, self-improving retrieval, and multi-source ingestion. The platform automatically processes each conversation, maintains user profiles, and serves relevant context at session start.

Platforms like HydraDB provide this as a managed service. On the LongMemEval-s benchmark (ICLR 2025)—500 question-conversation stacks with \~115K tokens per stack—managed memory platforms consistently outperform ad-hoc implementations, particularly on temporal reasoning (90.97% vs 62.4% for baseline approaches) and preference understanding (96.67% vs 20.0% for context-only baselines).

The integration pattern with the Claude SDK is clean: call the platform's retrieval API before each invocation, inject the returned context, run the SDK, then call the platform's update API with the conversation. The SDK remains stateless. The platform handles state.

Implementation Guide

Step 1: Identify What to Remember

Not everything in a conversation matters for future sessions. Focus on storing facts that are user-specific, stable enough to be useful later, and not easily re-derivable. Good candidates: user preferences, domain context, past decisions, recurring patterns. Bad candidates: session-specific debugging steps, one-time questions, transient emotional states.

Step 2: Build the Context Pipeline

Before each SDK invocation:

1. Resolve user identity from the request

2. Query your memory store for relevant context

3. Format retrieved context as a system prompt prefix

4. Pass the enriched prompt to the Claude SDK

After each SDK invocation:

1. Extract key facts from the conversation

2. Store new facts with timestamps and user association

3. Update or version any changed facts

Step 3: Handle Temporal Conflicts

When a new fact contradicts an existing one, don't overwrite—version. Store the new fact alongside the old one with a timestamp. When retrieving context, prefer the most recent version unless the query specifically asks about history. This preserves the ability to reason about change over time.

Step 4: Monitor and Improve

Track which retrieved facts the agent actually uses in its responses. Track which responses get positive feedback and which get corrections. Use this signal to improve retrieval quality over time—up-weight facts that lead to good outcomes, flag facts that lead to corrections.

Read more on how to extend LLM memory for SaaS products in 2026

FAQ

Does statelessness make the Claude SDK harder to add memory to?

Counterintuitively, no. Statelessness means there's no existing memory system to work around. You design the memory architecture from scratch, tailored to your use case. Frameworks with built-in memory often create more friction because you have to work within their abstractions.

How much context should I inject per session?

Aim for 500-2,000 tokens of user context in the system prompt. More than that starts competing with the user's actual request for the agent's attention. Less than that may miss important context. The key is relevance—inject only what matters for the likely conversation, not everything you know.

Can I use Claude's extended context window instead of memory?

A 200K-token window lets you inject a lot of history, but it's not a substitute for memory. Reading 200K tokens of history on every request is slow, expensive, and noisy. Structured memory that retrieves the right 1,000 tokens is faster, cheaper, and more accurate than dumping 200,000 tokens of raw history. Why agent frameworks ship without real memoryexplains this tradeoff in depth.

What's the minimum viable memory for a Claude-based agent?

At minimum: store the user's name, role, and top 5 preferences in a key-value store. Load them into the system prompt on each session. This takes an hour to implement and immediately makes the agent feel more personalized. It's not production-grade, but it demonstrates the value of memory and justifies investing in a proper implementation.

How do I handle memory when the agent uses tools that modify external state?

Tool calls that write to databases, send emails, or modify files create side effects that should also be captured in memory. If the agent helped a user configure their CI pipeline last Tuesday, the memory layer should know that—both what was configured and when. Without this, the agent might suggest the same configuration again, or worse, suggest conflicting changes. Track tool-side-effect facts alongside conversational facts, and tag them with the tool that produced them so you can trace back to the original action.

Does the Claude SDK's streaming affect memory extraction?

Streaming responses improve user experience but complicate memory extraction. The full response isn't available until the stream completes, so fact extraction has to happen after the stream is finished—not during. Buffer the complete response, then run your extraction pipeline asynchronously. This adds a small delay to the memory update cycle, but it's negligible compared to the cost of extracting facts from partial responses and getting them wrong. Most teams process memory updates as background jobs rather than blocking the response stream.

Conclusion

The Claude Agent SDK gives you a clean, stateless execution layer for building AI agents. Persistent memory is your responsibility, and that's by design. The stateless architecture forces you to think explicitly about what context matters, how it's stored, and how it's retrieved—decisions that produce better memory systems than frameworks that hide these choices behind abstractions.

Start simple—a key-value profile store that injects user context into the system prompt. Graduate to vector retrieval when your context volume grows. Move to a managed platform when temporal reasoning and self-improvement become requirements. The SDK's clean architecture makes each transition straightforward because you're always in control of the context pipeline.

Memory turns a capable agent into a trusted one. The Claude SDK handles capability. Memory handles trust. Build both.