Claude Infinite Context

# 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 ```bash # 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](https://aistudio.google.com/apikey) (Gemini - required) | [Anthropic Console](https://console.anthropic.com/) (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 `/clear`**: 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 `/clear`**: 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:** ```bash redis-cli JSON.GET test # ✅ Returns (nil) → You have Redis Stack # ❌ Returns ERR unknown command → Install Redis Stack below ``` **macOS (Homebrew):** ```bash brew tap redis-stack/redis-stack brew install redis-stack redis-stack-server ``` **Docker:** ```bash docker run -d -p 6379:6379 --name redis-stack redis/redis-stack:latest ``` **Linux:** ```bash 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 ```bash # 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 ```bash ./test-basic.sh # Should show: ✅ All tests passed! ``` ### Step 4: Configure Environment ```bash cp .env.example .env nano .env ``` Edit `.env` and configure your API keys: ```bash # 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](https://aistudio.google.com/apikey) - **Anthropic API Key**: Get from [Anthropic Console](https://console.anthropic.com/) ## Configuration Add this to your `~/.config/claude-code/config.json`: ```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 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**: ``` > 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: ```bash # 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: 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: ```typescript { 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: 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: ```bash ./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: ```bash 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 ```bash # 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**: ```bash # 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**: ```bash redis-cli JSON.GET test # Should return: (nil) # NOT: ERR unknown command ``` ### "Failed to connect to Redis" **Cause**: Redis Stack isn't running. **Fix**: ```bash # 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: ```bash 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: 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: ```bash 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: 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: ```bash # 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 ```bash 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: ```bash LOG_LEVEL=DEBUG npm run dev ``` Logs are structured JSON for easy parsing: ```json {"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: ```bash 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 ```bash 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 ```bash # 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:** ```typescript const DEFAULT_GEMINI_MODEL = 'gemini-3-pro-preview'; // Primary model const ANTHROPIC_MODEL = 'claude-3-5-sonnet-20241022'; // Fallback model ``` **Generation Parameters:** ```typescript 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`: ```typescript // 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 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](https://claude.com/claude-code), Anthropic's official CLI tool for Claude AI. **Powered by:** - [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) - Anthropic's protocol for AI-app integrations - [Google Gemini](https://ai.google.dev/) - Primary AI provider for intelligent state merging - [Anthropic Claude](https://www.anthropic.com/claude) - Fallback AI provider and the assistant you're interfacing with - [Redis Stack](https://redis.io/docs/stack/) - In-memory database with JSON support