Multi-Context Parallelism

Split a single conversation into N parallel contexts. Each context independently maintains its own message history. Non-active contexts are unloaded from memory (lazy-load on switch) and persisted to disk.

Why Multi-Context?

A single conversation grows linearly — every tool call, every response adds tokens. After a while, context becomes noisy. Multi-context gives you:

Context Management

Creating Contexts

/context new frontend-design
/context new backend-api
/context new bug-investigation

Each context gets its own name and independent message history. When the limit (max_contexts) is reached, the least recently used context is evicted automatically.

Switching Contexts

/context                    → Open context switch popup
/context 2                  → Switch to context #2

In TUI mode, /context with no argument opens a visual popup panel. Use ↑↓ to navigate, Enter to switch, Del to evict. Press Esc to close.

Renaming and Deleting

/context rename "UI-refactor"    → Rename current context
/context del 3                   → Evict context #3

LRU Eviction

When you create a new context and the slot is full (max_contexts, default 5), niuma_code evicts the least valuable context using a three-tier priority:

  1. Empty contexts — contexts with zero messages are evicted first (lowest value)
  2. Unnamed contexts — contexts with auto-generated summary (not user-named) are next
  3. Least recently used — among remaining candidates, the one with the oldest last_active_ts is evicted

The current active context can never be evicted (protected).

State Description
Active In memory, full history available
Inactive Unloaded from memory, metadata in manifest, messages on disk

Eviction is transparent — evicted contexts' message files ({sid}.json) are preserved on disk and can be restored on demand when switched back to.

Context Summary

When you switch away from a context, niuma_code captures a summary from the last user question (first 20 characters) as the context's display label. This is a pure in-memory truncation — no LLM call, zero latency.

Switching from "backend-api" to "frontend-design"
  → Summary captured: "Fix the auth middleware..."
  → Switched to frontend-design

If you explicitly name a context (via /context new <name> or /context rename <name>), the name is pinned and won't be overwritten by the auto-summary.

/messages Command

The /messages command opens a visual popup for managing conversation history within the current context:

Action Shortcut
Navigate ↑↓
Multi-select Space
Delete selected Delete or d
Move unit Alt+↑ / Alt+↓
Merge selected m (LLM-summarizes user/assistant sides)
Clear recall injections c (double-press to confirm)
Save changes Ctrl+S
Close Esc

Messages are organized by conversation units (each unit starts with a user message and includes all subsequent assistant responses until the next user message). Editing operations are preview-only until you press Ctrl+S to persist.

Configuration

Configure in settings.json under the llm section:

{
    "llm": {
        "max_contexts": 5,
        "resume_latest_context": false
    }
}
Setting Default Description
max_contexts 5 Maximum active contexts before LRU eviction
resume_latest_context false true: restore last active context on restart; false: start fresh (old contexts preserved, switchable via /context)

Persistence

Context data is stored in the .session/ directory:

Only the active context's messages are loaded into memory at startup. Other contexts are lazy-loaded when switched to.

Example Workflow

/context new api-refactor
# Work on API refactoring...

/context new bug-fix
# Investigate and fix a bug...

/context 1
# Back to API refactoring — context preserved exactly as you left it

/context new testing
# Write tests — separate context keeps things clean

Each context maintains: