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

# 1. Install Redis Stack
brew install redis-stack/redis-stack/redis-stack  # macOS
redis-stack-server

# 2. Install the MCP server
git clone <repository-url> claude-infinite-context
cd claude-infinite-context
npm install
npm run build

# 3. Configure environment
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY

# 4. Add to Claude Code config (~/.config/claude-code/config.json)
{
  "mcpServers": {
    "infinite-context": {
      "command": "node",
      "args": ["/absolute/path/to/claude-infinite-context/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-key-here",
        "REDIS_URL": "redis://localhost:6379",
        "PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}

# 5. Verify installation
./test-basic.sh

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

Checkpoint Before /clear: Save your current context to Redis
AI-Powered Summarization: Uses Google Gemini (with optional Claude fallback) to intelligently merge old state with new context, preserving what's important
Resume After /clear: Load the compressed state back into your fresh context
Optimistic Locking: Prevents race conditions if multiple sessions run concurrently
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:

redis-cli JSON.GET test
# ✅ Returns (nil) → You have Redis Stack
# ❌ Returns ERR unknown command → Install Redis Stack below

macOS (Homebrew):

brew tap redis-stack/redis-stack
brew install redis-stack
redis-stack-server

Docker:

docker run -d -p 6379:6379 --name redis-stack redis/redis-stack:latest

Linux:

curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list
sudo apt-get update
sudo apt-get install redis-stack-server
redis-stack-server

Step 2: Clone and Install the MCP Server

# Clone or download the repository
git clone <repository-url> claude-infinite-context
cd claude-infinite-context

# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

Step 3: Verify Installation

./test-basic.sh
# Should show: ✅ All tests passed!

Step 4: Configure Environment

cp .env.example .env
nano .env

Edit .env and configure your API keys:

# Required: Google Gemini API Key
GEMINI_API_KEY="your-gemini-api-key-here"

# Optional: Anthropic API Key (fallback)
ANTHROPIC_API_KEY="sk-ant-your-key-here"

# Optional: Gemini Model (defaults to gemini-3-pro-preview)
GEMINI_MODEL="gemini-3-pro-preview"

# Redis connection (defaults shown)
REDIS_URL="redis://localhost:6379"

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:

{
  "mcpServers": {
    "infinite-context": {
      "command": "node",
      "args": ["/absolute/path/to/claude-infinite-context/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key",
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "GEMINI_MODEL": "gemini-3-pro-preview",
        "REDIS_URL": "redis://localhost:6379",
        "PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}

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

Start a new project
```
cd /your/project
claude-code
```
The MCP server automatically creates .claude_session_id in your project root.
Work normally until you approach token limit (~150k tokens)
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.
Clear context
```
/clear
```
This clears Claude's working memory but your project state remains safely stored in Redis.
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:

> I've made a lot of progress. Checkpoint this work before I clear context.

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:

> Resume where we left off

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:

> Show me the infinite context status

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:

> Rollback to the previous checkpoint

Parameters:

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

Manual Testing

You can test the server manually:

# Start the server
npm run dev

# In another terminal, send a test request
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node dist/index.js

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:

Context Analysis: The AI reads your old project state and new work context
Smart Compression: Identifies what's important vs. what can be safely compressed
Intelligent Merging: Combines new information with existing knowledge
Task Migration: Moves completed work from "current task" to "recent changes" history
File Tracking: Updates which files are actively being worked on
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:

{
  meta: {
    version: number,              // Incremented on each update (optimistic locking)
    last_checkpoint: string,      // ISO timestamp
    last_access: string,          // ISO timestamp
    session_id: string,           // UUID from .claude_session_id
    token_budget_used: number     // Current token count
  },
  project_context: {
    overview: string,             // Max ~200 tokens
    architecture: string,         // Key architectural decisions
    recent_changes: Array<{       // Ring buffer: last 10 changes
      timestamp: string,
      summary: string,
      files: string[]
    }>
  },
  active_context: {
    current_task: string,         // What's being worked on now
    active_files: string[],       // Currently relevant files
    active_decisions: Array<{     // Pending or decided questions
      question: string,
      status: "pending" | "decided",
      decision?: string
    }>
  }
}

Optimistic Locking (Race Condition Prevention)

Uses Redis WATCH/MULTI/EXEC for atomic updates:

WATCH the state key
Read current state
Apply transformation (merge with LLM)
Increment version field
EXEC transaction
If another process modified the state during this time, transaction fails
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:

Read old state from Redis
Send both old state and new context to Gemini (or Claude as fallback) with a structured prompt
Receive updated JSON matching the project state schema
Validate with Zod schema validation
Verify data integrity (session_id preserved, no critical fields dropped)
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:

./test-basic.sh

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:

mkdir -p /tmp/test-project
cd /tmp/test-project
claude-code

Test the workflow:

1. Show me the infinite context status
   → Should create .claude_session_id and show empty state

2. Create a test file called hello.js
   → Claude creates the file

3. Checkpoint this work
   → Should save to Redis: "Checkpoint saved successfully (version 1)"

4. /clear
   → Context cleared

5. Resume where we left off
   → Should load state with hello.js mentioned

6. What files are we working on?
   → Claude should remember hello.js without reading it again

Verify in Redis

# List all project states
redis-cli KEYS "project:*"

# View your project's state
redis-cli JSON.GET project:state:<session-id>

# View checkpoint history
redis-cli LRANGE project:history:<session-id> 0 -1

Troubleshooting

"ERR unknown command 'JSON.GET'"

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

Fix:

# Stop regular Redis
brew services stop redis  # macOS
# or
sudo systemctl stop redis  # Linux

# Install and start Redis Stack
brew install redis-stack/redis-stack/redis-stack  # macOS
redis-stack-server

# Or use Docker
docker run -d -p 6379:6379 redis/redis-stack:latest

Verify:

redis-cli JSON.GET test
# Should return: (nil)
# NOT: ERR unknown command

"Failed to connect to Redis"

Cause: Redis Stack isn't running.

Fix:

# macOS
redis-stack-server

# Docker
docker start redis-stack
# Or create new:
docker run -d -p 6379:6379 --name redis-stack redis/redis-stack:latest

"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:

redis-cli
> DEL project:state:<your-session-id>
> DEL project:history:<your-session-id>

"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:

Retry with exponential backoff (up to 2 retries)
If Gemini fails, try Anthropic (if API key configured)
If all AI providers fail, use simple append strategy

Debugging: Check logs for detailed error information:

LOG_LEVEL=DEBUG npm run dev  # Verbose logging to console

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:

Check status to see state size
Consider manually editing overview/architecture to be more concise
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:

Regular cleanup: Periodically review status and ensure old, irrelevant information is being naturally pruned
Focused context: When checkpointing, provide concise but complete context summaries
Let AI work: The system is designed to automatically compress and prioritize information
Monitor growth: If state exceeds ~10k tokens consistently, consider what information might be redundant

Multi-Project Workflow

When working on multiple projects:

# Each project gets its own session
cd /path/to/project-a
claude-code  # Creates unique .claude_session_id

cd /path/to/project-b
claude-code  # Creates different .claude_session_id

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

claude-infinite-context/
├── src/
│   ├── index.ts                # MCP server entry point
│   ├── config/
│   │   └── env.ts              # Environment configuration with Zod validation
│   ├── core/
│   │   ├── ProjectBrain.ts     # Main orchestrator for state management
│   │   ├── RedisClient.ts      # Redis client with optimistic locking
│   │   └── SummaryMerger.ts    # AI-based merge logic (Gemini + Claude)
│   ├── types/
│   │   └── schema.ts           # Zod schemas + TypeScript types
│   └── utils/
│       ├── sessionId.ts        # .claude_session_id file management
│       ├── validation.ts       # File path validation
│       ├── time.ts             # Timestamp utilities
│       └── logger.ts           # Structured JSON logging
├── dist/                       # Compiled JavaScript (generated by build)
├── node_modules/               # Dependencies (generated by npm install)
├── package.json                # Dependencies and scripts
├── tsconfig.json               # TypeScript configuration
├── .env.example                # Environment variable template
├── .env                        # Your local environment (gitignored)
├── test-basic.sh              # Installation verification script
└── README.md                   # This documentation

Scripts

npm run dev      # Run with auto-reload (tsx watch)
npm run build    # Compile TypeScript to dist/
npm run start    # Run compiled version
npm test         # Run tests (if configured)

Logging

Set LOG_LEVEL=DEBUG in .env for verbose logging:

LOG_LEVEL=DEBUG npm run dev

Logs are structured JSON for easy parsing:

{"timestamp":"2025-01-27T10:30:00.000Z","level":"INFO","message":"Checkpoint completed","data":{"version":5,"duration":1234}}

Advanced Usage

Multiple Projects

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

cd /project-a
claude-code  # Creates .claude_session_id with UUID-A

cd /project-b
claude-code  # Creates .claude_session_id with UUID-B

Redis stores state separately:

project:state:UUID-A
project:state:UUID-B

Manual State Inspection

redis-cli

# List all project states
> KEYS project:state:*

# View a specific state
> JSON.GET project:state:<session-id>

# View checkpoint history
> LRANGE project:history:<session-id> 0 -1

Backing Up State

# Export state to file
redis-cli JSON.GET project:state:<session-id> > backup.json

# Restore from file
redis-cli JSON.SET project:state:<session-id> $ "$(cat backup.json)"

Customizing AI Behavior

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

Model Configuration:

const DEFAULT_GEMINI_MODEL = 'gemini-3-pro-preview';  // Primary model
const ANTHROPIC_MODEL = 'claude-3-5-sonnet-20241022'; // Fallback model

Generation Parameters:

const MAX_TOKENS = 8000;      // Maximum output tokens
const TEMPERATURE = 0.3;      // Creativity vs consistency (0.0-1.0)

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

// Use Anthropic as primary
await this.merger.merge(oldState, context, tokenCount, 'anthropic');

// Use Gemini as primary (default)
await this.merger.merge(oldState, context, tokenCount, 'gemini');

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

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.
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.
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>
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.
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.
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

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

# 1. Install Redis Stack
brew install redis-stack/redis-stack/redis-stack  # macOS
redis-stack-server

# 2. Install the MCP server
git clone <repository-url> claude-infinite-context
cd claude-infinite-context
npm install
npm run build

# 3. Configure environment
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY

# 4. Add to Claude Code config (~/.config/claude-code/config.json)
{
  "mcpServers": {
    "infinite-context": {
      "command": "node",
      "args": ["/absolute/path/to/claude-infinite-context/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-key-here",
        "REDIS_URL": "redis://localhost:6379",
        "PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}

# 5. Verify installation
./test-basic.sh

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

Checkpoint Before /clear: Save your current context to Redis
AI-Powered Summarization: Uses Google Gemini (with optional Claude fallback) to intelligently merge old state with new context, preserving what's important
Resume After /clear: Load the compressed state back into your fresh context
Optimistic Locking: Prevents race conditions if multiple sessions run concurrently
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:

redis-cli JSON.GET test
# ✅ Returns (nil) → You have Redis Stack
# ❌ Returns ERR unknown command → Install Redis Stack below

macOS (Homebrew):

brew tap redis-stack/redis-stack
brew install redis-stack
redis-stack-server

Docker:

docker run -d -p 6379:6379 --name redis-stack redis/redis-stack:latest

Linux:

curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list
sudo apt-get update
sudo apt-get install redis-stack-server
redis-stack-server

Step 2: Clone and Install the MCP Server

# Clone or download the repository
git clone <repository-url> claude-infinite-context
cd claude-infinite-context

# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

Step 3: Verify Installation

./test-basic.sh
# Should show: ✅ All tests passed!

Step 4: Configure Environment

cp .env.example .env
nano .env

Edit .env and configure your API keys:

# Required: Google Gemini API Key
GEMINI_API_KEY="your-gemini-api-key-here"

# Optional: Anthropic API Key (fallback)
ANTHROPIC_API_KEY="sk-ant-your-key-here"

# Optional: Gemini Model (defaults to gemini-3-pro-preview)
GEMINI_MODEL="gemini-3-pro-preview"

# Redis connection (defaults shown)
REDIS_URL="redis://localhost:6379"

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:

{
  "mcpServers": {
    "infinite-context": {
      "command": "node",
      "args": ["/absolute/path/to/claude-infinite-context/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key",
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "GEMINI_MODEL": "gemini-3-pro-preview",
        "REDIS_URL": "redis://localhost:6379",
        "PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}

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

Start a new project
```
cd /your/project
claude-code
```
The MCP server automatically creates .claude_session_id in your project root.
Work normally until you approach token limit (~150k tokens)
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.
Clear context
```
/clear
```
This clears Claude's working memory but your project state remains safely stored in Redis.
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:

> I've made a lot of progress. Checkpoint this work before I clear context.

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:

> Resume where we left off

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:

> Show me the infinite context status

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:

> Rollback to the previous checkpoint

Parameters:

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

Manual Testing

You can test the server manually:

# Start the server
npm run dev

# In another terminal, send a test request
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node dist/index.js

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:

Context Analysis: The AI reads your old project state and new work context
Smart Compression: Identifies what's important vs. what can be safely compressed
Intelligent Merging: Combines new information with existing knowledge
Task Migration: Moves completed work from "current task" to "recent changes" history
File Tracking: Updates which files are actively being worked on
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:

{
  meta: {
    version: number,              // Incremented on each update (optimistic locking)
    last_checkpoint: string,      // ISO timestamp
    last_access: string,          // ISO timestamp
    session_id: string,           // UUID from .claude_session_id
    token_budget_used: number     // Current token count
  },
  project_context: {
    overview: string,             // Max ~200 tokens
    architecture: string,         // Key architectural decisions
    recent_changes: Array<{       // Ring buffer: last 10 changes
      timestamp: string,
      summary: string,
      files: string[]
    }>
  },
  active_context: {
    current_task: string,         // What's being worked on now
    active_files: string[],       // Currently relevant files
    active_decisions: Array<{     // Pending or decided questions
      question: string,
      status: "pending" | "decided",
      decision?: string
    }>
  }
}

Optimistic Locking (Race Condition Prevention)

Uses Redis WATCH/MULTI/EXEC for atomic updates:

WATCH the state key
Read current state
Apply transformation (merge with LLM)
Increment version field
EXEC transaction
If another process modified the state during this time, transaction fails
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:

Read old state from Redis
Send both old state and new context to Gemini (or Claude as fallback) with a structured prompt
Receive updated JSON matching the project state schema
Validate with Zod schema validation
Verify data integrity (session_id preserved, no critical fields dropped)
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:

./test-basic.sh

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:

mkdir -p /tmp/test-project
cd /tmp/test-project
claude-code

Test the workflow:

1. Show me the infinite context status
   → Should create .claude_session_id and show empty state

2. Create a test file called hello.js
   → Claude creates the file

3. Checkpoint this work
   → Should save to Redis: "Checkpoint saved successfully (version 1)"

4. /clear
   → Context cleared

5. Resume where we left off
   → Should load state with hello.js mentioned

6. What files are we working on?
   → Claude should remember hello.js without reading it again

Verify in Redis

# List all project states
redis-cli KEYS "project:*"

# View your project's state
redis-cli JSON.GET project:state:<session-id>

# View checkpoint history
redis-cli LRANGE project:history:<session-id> 0 -1

Troubleshooting

"ERR unknown command 'JSON.GET'"

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

Fix:

# Stop regular Redis
brew services stop redis  # macOS
# or
sudo systemctl stop redis  # Linux

# Install and start Redis Stack
brew install redis-stack/redis-stack/redis-stack  # macOS
redis-stack-server

# Or use Docker
docker run -d -p 6379:6379 redis/redis-stack:latest

Verify:

redis-cli JSON.GET test
# Should return: (nil)
# NOT: ERR unknown command

"Failed to connect to Redis"

Cause: Redis Stack isn't running.

Fix:

# macOS
redis-stack-server

# Docker
docker start redis-stack
# Or create new:
docker run -d -p 6379:6379 --name redis-stack redis/redis-stack:latest

"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:

redis-cli
> DEL project:state:<your-session-id>
> DEL project:history:<your-session-id>

"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:

Retry with exponential backoff (up to 2 retries)
If Gemini fails, try Anthropic (if API key configured)
If all AI providers fail, use simple append strategy

Debugging: Check logs for detailed error information:

LOG_LEVEL=DEBUG npm run dev  # Verbose logging to console

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:

Check status to see state size
Consider manually editing overview/architecture to be more concise
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:

Regular cleanup: Periodically review status and ensure old, irrelevant information is being naturally pruned
Focused context: When checkpointing, provide concise but complete context summaries
Let AI work: The system is designed to automatically compress and prioritize information
Monitor growth: If state exceeds ~10k tokens consistently, consider what information might be redundant

Multi-Project Workflow

When working on multiple projects:

# Each project gets its own session
cd /path/to/project-a
claude-code  # Creates unique .claude_session_id

cd /path/to/project-b
claude-code  # Creates different .claude_session_id

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

claude-infinite-context/
├── src/
│   ├── index.ts                # MCP server entry point
│   ├── config/
│   │   └── env.ts              # Environment configuration with Zod validation
│   ├── core/
│   │   ├── ProjectBrain.ts     # Main orchestrator for state management
│   │   ├── RedisClient.ts      # Redis client with optimistic locking
│   │   └── SummaryMerger.ts    # AI-based merge logic (Gemini + Claude)
│   ├── types/
│   │   └── schema.ts           # Zod schemas + TypeScript types
│   └── utils/
│       ├── sessionId.ts        # .claude_session_id file management
│       ├── validation.ts       # File path validation
│       ├── time.ts             # Timestamp utilities
│       └── logger.ts           # Structured JSON logging
├── dist/                       # Compiled JavaScript (generated by build)
├── node_modules/               # Dependencies (generated by npm install)
├── package.json                # Dependencies and scripts
├── tsconfig.json               # TypeScript configuration
├── .env.example                # Environment variable template
├── .env                        # Your local environment (gitignored)
├── test-basic.sh              # Installation verification script
└── README.md                   # This documentation

Scripts

npm run dev      # Run with auto-reload (tsx watch)
npm run build    # Compile TypeScript to dist/
npm run start    # Run compiled version
npm test         # Run tests (if configured)

Logging

Set LOG_LEVEL=DEBUG in .env for verbose logging:

LOG_LEVEL=DEBUG npm run dev

Logs are structured JSON for easy parsing:

{"timestamp":"2025-01-27T10:30:00.000Z","level":"INFO","message":"Checkpoint completed","data":{"version":5,"duration":1234}}

Advanced Usage

Multiple Projects

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

cd /project-a
claude-code  # Creates .claude_session_id with UUID-A

cd /project-b
claude-code  # Creates .claude_session_id with UUID-B

Redis stores state separately:

project:state:UUID-A
project:state:UUID-B

Manual State Inspection

redis-cli

# List all project states
> KEYS project:state:*

# View a specific state
> JSON.GET project:state:<session-id>

# View checkpoint history
> LRANGE project:history:<session-id> 0 -1

Backing Up State

# Export state to file
redis-cli JSON.GET project:state:<session-id> > backup.json

# Restore from file
redis-cli JSON.SET project:state:<session-id> $ "$(cat backup.json)"

Customizing AI Behavior

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

Model Configuration:

const DEFAULT_GEMINI_MODEL = 'gemini-3-pro-preview';  // Primary model
const ANTHROPIC_MODEL = 'claude-3-5-sonnet-20241022'; // Fallback model

Generation Parameters:

const MAX_TOKENS = 8000;      // Maximum output tokens
const TEMPERATURE = 0.3;      // Creativity vs consistency (0.0-1.0)

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

// Use Anthropic as primary
await this.merger.merge(oldState, context, tokenCount, 'anthropic');

// Use Gemini as primary (default)
await this.merger.merge(oldState, context, tokenCount, 'gemini');

Limitations

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.
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.
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>
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.
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.
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