Magic Context Documentation

Magic Context is a plugin for OpenCode and Pi (>= 0.74.0) designed to provide coding agents with persistent memory and automated context management. It solves the problem of 'starting from zero' in new sessions by capturing decisions, constraints, and conventions into project memory.

Core Capabilities

• Persistent Memory: Project memories persist across different sessions and across both OpenCode and Pi harnesses.
• Automated Context Management: A background 'historian agent' compresses older conversation parts into tiered compartments without interrupting the user's flow or requiring manual compaction pauses.
• Full Recall: Instead of discarding old data, Magic Context compresses and indexes it. The agent can expand compressed compartments back to the original transcript or search across memories and git commits.

Key Agent Tools

• ctx_expand: Used to expand a compressed compartment back to its original transcript on demand.
• ctx_search: Allows the agent to search across memories, compressed session history, and indexed git commits in a single call.

Magic Context is an @opencode-ai/plugin designed to manage long LLM sessions by rewriting message arrays and system prompts. It ensures session history stays within context windows without losing critical information.

Key architectural features include:

• Durable SQLite State: Uses a persistent database at ~/.local/share/cortexkit/magic-context/context.db to store session and project-scoped data. It fails closed if storage is unavailable to prevent context overflow.
• Cache Stability (Replay-everything): To maintain Anthropic prompt cache stability, every message mutation (such as reasoning clearing, structural noise stripping, or compression) is applied deterministically on every transform pass. This ensures wire bytes remain identical across requests.
• Out-of-band Processing: Heavy LLM work is performed by hidden subagents (historian, historian-editor, dreamer, sidekick) so the main transform pipeline remains lightweight and does not perform LLM calls itself.
• Multi-Runtime Support: Supports Bun (bun:sqlite), Node (node:sqlite), and Electron. It also features an experimental Rust runtime mode (transform_mode: "rust") for high-performance processing via a subconscious daemon (subc).

The Dreamer is an optional background agent that performs off-hours maintenance to ensure memory quality and keep project documentation current. It operates by spinning up ephemeral child sessions, each dedicated to a specific maintenance task.

Execution Model

• Scheduled Runs: Each task runs on its own independent cron schedule. A process-wide timer checks these schedules and executes due tasks.
• Manual Triggers: You can trigger tasks manually using CLI commands:
  • /ctx-dream: Runs all enabled tasks immediately.
  • /ctx-dream <task>: Runs one specific task immediately.
• Concurrency & Safety: Tasks like map-memories, verify, curate, and the primer tasks share a per-project memory lease to prevent collisions. Other tasks run independently. If a task times out, it banks its progress so the next run can continue where it left off.
• Circuit Breaker: To prevent excessive costs or errors, the Dreamer aborts remaining tasks after three consecutive identical-error failures, marking a circuit-breaker entry in the run history.

The core of the system is the transform pass, which is an invocation of experimental.chat.messages.transform. This process is executed once per LLM round-trip (per step within a turn) and is wrapped defensively to ensure that if a transient SQLITE_BUSY error occurs, the messages are returned unmodified so the prompt loop can proceed.

Pass Lifecycle Order

1. Resolve usage + scheduler decision: Determine if the pass should execute or defer.
2. Emergency overflow recovery: Triggered if usage is $\ge 95%$.
3. Compartment trigger check: Checks the in-memory args.messages tail. If eligible, the historian is fired asynchronously.
4. Prepare compartment injection: Decides on m[0]/m[1] materialization.
5. Tag messages: Replays dropped-status, caveman, reasoning, placeholder, and image strips.
6. Compartment phase: Injects the <session-history> (m[0]/m[1]) into message[0].
7. Postprocess: Executes mutation gates (pending-op drain, heuristic cleanup, nudges, synthetic-todowrite, auto-search) via transform-postprocess-phase.ts.

Magic Context provides an 'infinite session' experience by managing the context window in the background, preventing the need for manual compaction pauses. Key mechanisms include:

• Historian Compartmentalization: A background process that compresses raw history into layered compartments (chronological summaries). Each compartment has an importance score to keep the active window small without losing context. This can run on cheaper or local models.
• Decay Rendering: Uses deterministic rules (no LLM required) to show compartments with the necessary precision based on the model's context window. Old history fades smoothly rather than being abruptly dropped.
• Agent-driven Reduction: When enabled, the agent can call ctx_reduce to mark old tool outputs or long messages for deletion. These are queued and applied in cache-safe moments to avoid invalidating the prefix prompt cache.
• Cache-stable Compaction: Designed so that background work never invalidates the cached prefix prompt, preserving cache efficiency throughout the session.
• Caveman Text Compression (Optional/Disabled by default): A deterministic age-based rule that progressively compresses the oldest user and assistant text when agent-driven reduction is disabled.