npm package: @luckydraw/cumulus
Description: RLM-based CLI chat wrapper for Claude with external history context management
Latest version: 0.29.1

# 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

```bash
npm install -g cumulus-cli
```

## Usage

```bash
# 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"](https://arxiv.org/abs/...) 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

```bash
# 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