Back to writings

The Claude Code Memory Crisis: Engineering Persistent Context Systems for Long-Running Development Workflows

7 min read

You're three hours deep into a complex refactoring. Claude Code has been tracking architectural decisions, remembering your codebase patterns, maintaining context across dozens of turns. Then suddenly—the responses get generic. Previous decisions are forgotten. Code quality degrades. You've hit the context wall.

This isn't a limitation of Claude's intelligence. The real problem is architectural: most development workflows aren't designed to handle persistent context across sessions.

I've built systems that run for days without hitting this wall. Here's how.

Understanding the Context Crisis

The problem is real and documented. One Reddit user documented watching their context window die before writing a single prompt—67,000 tokens gone from connecting just four MCP servers to Claude Code, and it's not an isolated case.

This happens because everything consumes context simultaneously: your conversation history, file contents, tool outputs, MCP server definitions, and the working memory Claude needs to reason effectively. Most Claude models have a 200K token context window, but Claude Sonnet 4.5 via API offers a massive 1M token context window, perfect for entire codebases. That sounds infinite until you realize how fast it fills.

The deeper issue: when most context space is consumed by conversation history, file contents, and tool outputs, the model has minimal room for the computational processes that produce high-quality responses. It's like RAM on your computer—you can run at 95% utilization, but that last 5% gets consumed by overhead, leaving nothing for actual computation.

The CLAUDE.md Pattern: Persistent Project Memory

The simplest, most effective pattern I've found is the CLAUDE.md file. This isn't a documentation file—it's a context injection system that persists across sessions.

Here's what goes in CLAUDE.md:

# Project Context

## Architecture
- Monorepo structure with packages/ and apps/
- Uses TypeScript strict mode
- Database: Supabase with row-level security
- Deployment: Vercel with preview environments

## Key Decisions
- Repository pattern for all data access
- React Query for server state management
- Tailwind CSS for styling
- Never use any/unknown in TypeScript

## Critical Files
- `src/types/index.ts` - All type definitions
- `src/services/` - Business logic layer
- `src/components/` - React components
- `src/hooks/` - Custom hooks
- `prisma/schema.prisma` - Database schema

## Code Style
- 2-space indentation
- Prefer composition over inheritance
- Always add JSDoc for public APIs
- Use snake_case for API endpoints

## Known Constraints
- API rate limits: 100 req/min per user
- Max file upload: 10MB
- Database connection pool: 20 connections
- Memory limit in serverless: 1GB

Use a dedicated context file like CLAUDE.md to inject fundamental requirements every session, where core app features, tech stacks, and 'never-forgotten' project notes live. Move stable information out of the limited conversation window.

The magic: this information loads fresh every session, but it doesn't accumulate in conversation history. Claude sees it, uses it, but it doesn't take up your precious context budget as the session grows.

Subagent Architecture: Divide and Conquer

Long-running workflows benefit from delegation. Instead of one agent doing everything, you spawn specialized subagents for specific tasks.

Here's the pattern that works:

# Main agent handles orchestration
claude "Implement the payment processing feature"

# Inside that session, delegate specialized work:
# - Code review subagent checks quality
# - Test runner subagent validates functionality  
# - Security audit subagent reviews for vulnerabilities
# - Documentation subagent generates API docs

Each subagent gets its own fresh context window. The main agent only receives their final summaries—not all the intermediate reasoning, file reads, or tool outputs that would otherwise pollute the main context.

The key insight: farm out the work to specialized agents, which only return the final answers, keeping your main context clean. This is how you build AI agents that scale beyond a single session.

State Persistence: Context Editing and Memory Tools

Claude's context editing API gives you surgical control over what stays in memory. Instead of conversations growing indefinitely, you selectively clear old tool results while preserving critical decisions.

The strategy: clear tool results when conversation context grows beyond your configured threshold, automatically clearing the oldest tool results in chronological order while replacing them with placeholder text to let Claude know the tool result was removed.

Pair this with the memory tool for cross-session persistence:

// After completing a major milestone
await memory.save({
  key: "architecture_decisions",
  value: {
    auth_pattern: "JWT with refresh tokens",
    api_style: "REST with OpenAPI spec",
    db_strategy: "Supabase with RLS",
    completed_features: ["auth", "user profiles", "billing"]
  }
});

// Next session, retrieve it
const decisions = await memory.retrieve("architecture_decisions");

Context management creates a system that enables longer conversations by automatically removing stale tool results from context and boosts accuracy by saving critical information to memory—bringing that learning across successive sessions.

Practical Implementation: Session Management

Here's how I structure long-running development workflows:

Session 1: Architecture & Planning

  • Load CLAUDE.md
  • Ask Claude to review the codebase and create a plan
  • Save the plan to memory
  • Spend context on understanding, not implementation

Session 2: Implementation

  • Load CLAUDE.md and retrieve the plan from memory
  • Implement specific features with focused scope
  • Use subagents for validation and testing
  • Clear old tool results as context fills

Session 3+: Iteration & Refinement

  • Load CLAUDE.md, retrieve prior decisions and completed work
  • Focus on remaining tasks
  • Use context editing to maintain working space

This approach means your effective context window never depletes because you're constantly clearing stale data while preserving critical information.

Monitoring and Prevention

Watch the context meter actively—at 70%, it's time to act and consider using compact operations before starting new major tasks.

Set up simple monitoring:

// Track context usage
const contextUsage = await claude.countTokens(messages);
if (contextUsage > maxTokens * 0.7) {
  // Time to save state and consider a new session
  await saveSessionState();
}

Related Patterns

If you're building production-ready AI agents with Claude, you'll want to understand the broader architectural patterns. Recent product updates like the Sonnet 4 1-million-token context window and Claude's extended thinking controls make context management both more powerful and more important: you can process whole repositories in a single session—but only if you structure prompts, files, and session state deliberately.

For deeper architectural patterns, check out From Prototype to Production: Claude MCP Architecture Patterns That Actually Scale and Building Production-Ready AI Agents with Claude: From Prototype to Enterprise Deployment.

If you're specifically working with MCP integrations, The Disruptive Rise of MCP (Model Context Protocol): Integration Patterns and Implementation Strategy covers how to manage tool definitions without consuming your entire context budget.

The Takeaway

The Claude Code memory crisis isn't unsolvable—it's a design problem. You solve it by:

  1. Persisting stable context in CLAUDE.md (loaded fresh, not accumulated)
  2. Delegating work through subagents (each gets their own window)
  3. Managing state with context editing and memory tools (clearing stale data, preserving decisions)
  4. Monitoring actively (act at 70%, not 95%)

Once you architect for persistent context, you can run development workflows for days without degradation. The sessions don't get slower. The decisions don't get forgotten. The code quality doesn't degrade.

That's the difference between a demo agent and a system that actually works.

Want to discuss your specific context management challenges? Get in touch—I'm building systems that handle this at scale.