Cumulus

A CLI chat wrapper for Claude that implements the Recursive Language Model (RLM) pattern for unlimited conversation context.

The Problem

Standard LLM chat interfaces accumulate conversation history in the context window. As conversations grow:

• Context rot: Model performance degrades as context fills up
• Compaction: Old messages get summarized or dropped, losing detail
• Token limits: Eventually you hit the wall, no matter how large the window

The Solution

Cumulus treats conversation history as an external environment that Claude queries programmatically, rather than stuffing it all into context.

Traditional:  [msg1][msg2][msg3]...[msg847] → context rot, compaction, limits

Cumulus:      [fresh context] + tools to query [external history]
                     ↓
              Claude retrieves what it needs, when it needs it

Each message is a fresh Claude invocation. Claude uses MCP tools to retrieve relevant context from the complete conversation history stored in local files.

How It Works

┌─────────────────────────────────────────────────────────────┐
│  $ cumulus my-project                                       │
│  > Help me refactor the auth module we discussed yesterday  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                         Cumulus                              │
│  1. Append user message to history                          │
│  2. Spawn fresh: claude --print --mcp-config history.json   │
│  3. Claude uses search_history("auth module") tool          │
│  4. Claude retrieves relevant messages from history         │
│  5. Claude responds with full context awareness             │
│  6. Append response to history                              │
│  7. Next message: completely fresh context                  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  ~/.cumulus/threads/my-project.jsonl                        │
│  ────────────────────────────────────────                   │
│  Full conversation history, never truncated                 │
│  Claude queries via MCP tools as needed                     │
└─────────────────────────────────────────────────────────────┘

Key Features

• Unlimited history: Conversations can span thousands of messages without degradation
• Full Claude Code power: All tools work (Bash, Edit, Read, etc.) - cumulus just manages context
• Persistent threads: Pick up any conversation where you left off
• Selective retrieval: Claude decides what context it needs, reducing noise
• Cost efficient: Only retrieve relevant context, not everything

Installation

npm install -g cumulus-cli

Usage

# Start or continue a conversation thread
cumulus my-project

# List all threads
cumulus --list

# Delete a thread
cumulus --delete old-project

MCP Tools Available to Claude

When you chat through Cumulus, Claude has access to:

| Tool | Description | | ------------------- | ---------------------------------------------------- | | search_history | Find messages by keyword, semantic, or hybrid search | | read_messages | Read a specific range of messages | | peek_recent | See the last few messages | | get_history_stats | Get count and token estimate | | sub_query | Ask focused questions about history snippets | | get_summary | Get auto-generated summaries of conversation history |

Architecture

src/
├── lib/
│   └── history.ts      # JSONL storage for conversation history
├── mcp/
│   ├── server.ts       # MCP server exposing history tools
│   └── index.ts        # MCP entry point
└── cli/
    └── cumulus.ts      # Main CLI, chat loop, Claude invocation

Background

This project implements ideas from the paper "Recursive Language Models" which demonstrates that treating long prompts as external environment objects—rather than feeding them directly into the context window—dramatically improves performance on long-context tasks while maintaining reasonable costs.

Key insight: LLMs can programmatically examine, decompose, and query their context rather than processing it all at once. This enables effective reasoning over contexts 2+ orders of magnitude beyond the model's context window.

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Lint
npm run lint

Roadmap

Phase 1 (MVP)

• [x] Project setup with TypeScript/ESLint
• [x] HistoryStore for JSONL persistence
• [x] MCP server with history tools
• [x] CLI wrapper with pure RLM chat loop
• [x] Basic test suite

Phase 2 (Enhancements)

• [x] Semantic search with embeddings
• [x] Periodic summarization for very long histories

License

MIT