Claude Infinite Context

A Model Context Protocol (MCP) server that overcomes Claude Code's 200k token context limit by implementing persistent long-term memory using Redis and AI-powered state summarization.

Quick Start

Get API Keys: Google AI Studio (Gemini - required) | Anthropic Console (Claude - optional fallback)

Architecture

The Problem

Claude Code operates with a 200k token context window. Once you hit this limit, you need to run /clear which wipes all context, forcing you to start over. This system solves that problem.

The Solution: "Rolling Snowball" Memory

Instead of trying to store infinite conversation history (which would grow unbounded), this system uses a "Rolling Snowball" approach:

• Working Memory (RAM): Your current 200k token context window in Claude Code

• Long-Term State (Redis): A compressed project "brain" that persists across sessions

• LLM-Based Merge: Uses Claude to intelligently merge old state + new context into an updated summary

Think of it like a developer's mental model of a project:

• You don't remember every line of code you've ever written

• You remember the architecture, recent changes, current task, and key decisions

• This system does the same thing, automatically

Key Concepts

1. Checkpoint Before : Save your current context to Redis

2. AI-Powered Summarization: Uses Google Gemini (with optional Claude fallback) to intelligently merge old state with new context, preserving what's important

3. Resume After : Load the compressed state back into your fresh context

4. Optimistic Locking: Prevents race conditions if multiple sessions run concurrently

5. Version History: Keep last 5 checkpoints for rollback

Installation

Prerequisites

• Node.js 18+ (for ES modules support)

• Redis Stack (not regular Redis - requires RedisJSON module)

• Google Gemini API Key (required for AI-powered state merging)

• Anthropic API Key (optional - used as fallback if Gemini fails)

Step 1: Install Redis Stack

Why Redis Stack? This project needs RedisJSON module for storing structured data. Regular Redis won't work.

Verify if you have it:

macOS (Homebrew):

Docker:

Linux:

Step 2: Clone and Install the MCP Server

Step 3: Verify Installation

Step 4: Configure Environment

Edit .env and configure your API keys:

Getting API Keys:

• Gemini API Key: Get from Google AI Studio

• Anthropic API Key: Get from Anthropic Console

Configuration

Add this to your ~/.config/claude-code/config.json:

Important Configuration Notes:

• Replace /absolute/path/to/claude-infinite-context with the actual absolute path where you installed the server

• GEMINI_API_KEY is required for AI-powered state merging

• ANTHROPIC_API_KEY is optional but recommended as a fallback

• PROJECT_ROOT uses ${workspaceFolder} which automatically resolves to your current project directory

• Available Gemini models: gemini-3-pro-preview (latest), gemini-2.5-pro (stable), gemini-2.5-flash (fast)

Usage

Typical Workflow

1. Start a new project

   cd /your/project claude-code

   The MCP server automatically creates .claude_session_id in your project root.

2. Work normally until you approach token limit (~150k tokens)

3. Checkpoint before clearing

   > Checkpoint my current work with context summary

   Claude Code will call the checkpoint tool, which uses Gemini AI to intelligently merge your new context with the existing project state stored in Redis.

4. Clear context

   /clear

   This clears Claude's working memory but your project state remains safely stored in Redis.

5. Resume from checkpoint

   > Resume where we left off

   Claude Code will call the resume tool to load your compressed project state, allowing you to continue seamlessly with full context of your previous work.

Available Tools

The MCP server exposes these tools to Claude:

checkpoint

Saves current context to Redis.

When to use: Before running /clear, or periodically during long sessions.

Example:

Parameters:

• context (string): Summary of recent work, decisions, active files

• token_count (number): Current token usage

resume

Loads the last checkpoint.

When to use: After running /clear, or when starting a new session.

Example:

Returns: Formatted project state with overview, architecture, current task, active files, recent changes, and pending decisions.

status

Shows current state metadata.

When to use: To check version, token usage, active files, or checkpoint history.

Example:

Returns: Session ID, version, timestamps, token usage, active files, decisions, and checkpoint history.

rollback

Reverts to a previous checkpoint version.

When to use: If a merge produced incorrect results or you want to undo recent changes.

Example:

Parameters:

• steps (number, default: 1): How many versions to roll back

Manual Testing

You can test the server manually:

How It Works

AI-Powered State Management

This system uses a dual-AI approach for intelligent context compression:

Why Gemini as Primary?

• Gemini 3 Pro offers excellent performance at lower cost

• Fast response times for state merging operations

• Strong structured output capabilities (JSON generation)

• Large context window for processing complex project states

Why Claude as Fallback?

• Provides redundancy and reliability

• Excellent at understanding code context and preserving technical details

• High-quality JSON generation and instruction following

• Ensures system continues working even if Gemini is unavailable

Intelligent Merge Process:

When you checkpoint your work, the system doesn't just dump everything into storage. Instead:

1. Context Analysis: The AI reads your old project state and new work context

2. Smart Compression: Identifies what's important vs. what can be safely compressed

3. Intelligent Merging: Combines new information with existing knowledge

4. Task Migration: Moves completed work from "current task" to "recent changes" history

5. File Tracking: Updates which files are actively being worked on

6. Decision Recording: Tracks architectural decisions and their outcomes

Result: You get a continuously updated "project memory" that preserves critical context while staying under token limits.

Data Schema

The project state stored in Redis has this structure:

Optimistic Locking (Race Condition Prevention)

Uses Redis WATCH/MULTI/EXEC for atomic updates:

1. WATCH the state key

2. Read current state

3. Apply transformation (merge with LLM)

4. Increment version field

5. EXEC transaction

6. If another process modified the state during this time, transaction fails

7. Retry with exponential backoff (max 3 attempts)

This ensures that concurrent sessions don't overwrite each other's changes.

AI-Powered Summary Merger

When you checkpoint, the system uses AI to intelligently merge your context:

1. Read old state from Redis

2. Send both old state and new context to Gemini (or Claude as fallback) with a structured prompt

3. Receive updated JSON matching the project state schema

4. Validate with Zod schema validation

5. Verify data integrity (session_id preserved, no critical fields dropped)

6. Save to Redis with optimistic locking

AI Provider Selection:

• Primary: Google Gemini (configurable model, default: gemini-3-pro-preview)

• Fallback: Anthropic Claude (claude-3-5-sonnet-20241022) if Gemini fails or is unavailable

• Retry Logic: Up to 2 retries with exponential backoff for transient failures

• Ultimate Fallback: Simple append strategy if all AI providers fail

Merge Intelligence:

• Preserves all critical data (session IDs, file paths, timestamps)

• Moves completed tasks from active context to recent_changes history

• Updates active_files based on files mentioned in new context

• Maintains detailed, comprehensive summaries (not overly compressed)

• Keeps ring buffer of last 10 recent changes

• Updates decision status (pending → decided)

• Returns only valid JSON matching the schema

Configuration:

• Model: Change via GEMINI_MODEL environment variable

• Temperature: 0.3 (balanced creativity/consistency)

• Max tokens: 8000 output tokens

• Customizable in src/core/SummaryMerger.ts

Session Management

Each project gets a .claude_session_id file containing a UUID. This:

• Links the project directory to its Redis state

• Allows multiple projects to coexist

• Persists across /clear commands

• Enables session locking (detects concurrent usage)

Checkpoint History

The last 5 checkpoint versions are stored in a Redis list:

• Each entry includes: version, timestamp, merge duration, token count, full state

• Allows rollback if a merge produces bad results

• Helps debug issues (see what changed between versions)

Testing

Quick Verification

Run the automated test script:

This verifies:

• Redis Stack is running with JSON module

• Node.js version is compatible

• Build completed successfully

• MCP server starts and lists all 4 tools

• All source files and dependencies are present

Manual Testing with Claude Code

After configuration:

Test the workflow:

Verify in Redis

Troubleshooting

"ERR unknown command 'JSON.GET'"

Cause: You're running regular Redis instead of Redis Stack.

Fix:

Verify:

"Failed to connect to Redis"

Cause: Redis Stack isn't running.

Fix:

"Session already locked by another process"

Cause: Another Claude Code session is using the same project.

Fix: Close the other session, or wait 5 minutes for the lock to expire. The server will proceed with a warning.

"Invalid project state schema"

Cause: Redis data is corrupted or from an incompatible version.

Fix: Delete the state and start fresh:

"AI merge failed" or "LLM merge failed"

Cause: Network issue, API error, invalid API key, or the AI returned invalid JSON.

Fix: The system automatically retries and falls back through these strategies:

1. Retry with exponential backoff (up to 2 retries)

2. If Gemini fails, try Anthropic (if API key configured)

3. If all AI providers fail, use simple append strategy

Debugging: Check logs for detailed error information:

Common causes:

• Invalid or expired API keys

• Network connectivity issues

• API rate limiting

• Insufficient API credits

Token usage still grows over time

Expected behavior: The checkpoint compresses context, but Claude still needs to read the full state on resume. If you notice the state itself growing too large:

1. Check status to see state size

2. Consider manually editing overview/architecture to be more concise

3. Old completed decisions can be removed from active_decisions

Files in active_files no longer exist

Handled automatically: The system validates files on checkpoint and resume, filtering out missing files. Orphaned files are logged as warnings.

Best Practices

When to Checkpoint

Good times to checkpoint:

• Before running /clear when approaching 150k+ tokens

• After completing a major feature or refactoring

• Before switching to a different task or codebase area

• At the end of a work session

• After making important architectural decisions

Avoid checkpointing:

• Too frequently (increases API costs unnecessarily)

• With minimal context (wait until you have substantial new work to save)

• In the middle of debugging sessions (checkpoint after fixing the issue)

Optimizing State Size

Keep your project state efficient by:

1. Regular cleanup: Periodically review status and ensure old, irrelevant information is being naturally pruned

2. Focused context: When checkpointing, provide concise but complete context summaries

3. Let AI work: The system is designed to automatically compress and prioritize information

4. Monitor growth: If state exceeds ~10k tokens consistently, consider what information might be redundant

Multi-Project Workflow

When working on multiple projects:

Sessions are isolated - checkpoints in one project don't affect others.

API Cost Management

To minimize API costs:

• Checkpoint strategically: Don't checkpoint trivial changes

• Use Gemini: It's the default and more cost-effective than Anthropic

• Monitor usage: Check your API dashboard periodically

• Consider model selection: gemini-2.5-flash is faster and cheaper than gemini-3-pro-preview but may be less accurate

Development

Project Structure

Scripts

Logging

Set LOG_LEVEL=DEBUG in .env for verbose logging:

Logs are structured JSON for easy parsing:

Advanced Usage

Multiple Projects

Each project gets its own session ID. You can work on multiple projects simultaneously:

Redis stores state separately:

• project:state:UUID-A

• project:state:UUID-B

Manual State Inspection

Backing Up State

Customizing AI Behavior

The AI-powered merge can be customized by editing src/core/SummaryMerger.ts:

Model Configuration:

Generation Parameters:

Provider Selection: You can prefer Anthropic over Gemini by modifying the merge() method call in ProjectBrain.ts:

Prompt Engineering: Edit the buildMergePrompt() method to customize how the AI processes your context. The prompt includes schema definitions, preservation rules, and output format requirements.

Limitations

1. State size: The compressed state should ideally stay under ~10k tokens. If it grows significantly larger, checkpoint and resume operations become less efficient and may consume more of your context budget.

2. AI accuracy: The merge quality depends on the AI model's ability to accurately summarize and preserve important information. Periodically review your state using the status tool to ensure critical information isn't being lost.

3. Session locking: If you force-quit Claude Code, the session lock may persist for up to 5 minutes. Either wait for the lock to expire or manually delete it: redis-cli DEL project:lock:<session-id>

4. Not a backup system: This system stores state in Redis, which is primarily an in-memory database. If Redis crashes or restarts without persistence enabled, your state may be lost. For production use, enable Redis persistence with redis-cli CONFIG SET save "900 1 300 10" or use redis-cli SAVE to manually persist to disk.

5. API dependencies: The system requires working API access to either Gemini or Anthropic. Network issues or API outages will trigger the fallback mechanisms, ultimately falling back to simple append strategy if all AI providers fail.

6. Token costs: Each checkpoint operation calls the Gemini API (or Anthropic as fallback), which incurs API usage costs. For large projects with frequent checkpoints, monitor your API usage.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests to the project repository.

Before contributing:

• Ensure all tests pass with ./test-basic.sh

• Follow the existing TypeScript code style

• Update documentation for any API or configuration changes

• Test with both Gemini and Anthropic providers

Technology Stack

• Runtime: Node.js 18+ with ES modules

• Language: TypeScript 5.7+

• MCP SDK: @modelcontextprotocol/sdk v1.0.4

• Database: Redis Stack (with RedisJSON module)

• AI Providers:

  • Google Gemini API (@google/generative-ai)

  • Anthropic Claude API (@anthropic-ai/sdk)

• Validation: Zod for schema validation

• Testing: Vitest

Credits

Built for use with Claude Code, Anthropic's official CLI tool for Claude AI.

Powered by:

• Model Context Protocol (MCP) - Anthropic's protocol for AI-app integrations

• Google Gemini - Primary AI provider for intelligent state merging

• Anthropic Claude - Fallback AI provider and the assistant you're interfacing with

• Redis Stack - In-memory database with JSON support