cortexkit/magic-context

Magic Context – Self‑managing memory for coding agents

What it is – A plugin (part of the CortexKit suite) that gives AI‑powered coding assistants a long‑term “hippocampus”. It automatically captures useful knowledge from a project’s chat history, consolidates it in the background, and makes it searchable across sessions and tools (OpenCode, Pi, Oh‑My‑Pi). The goal is to eliminate the usual compaction pauses that force agents to forget what they learned mid‑task.

Key capabilities

• Capture – While the agent works, a historian scans the conversation, extracts durable facts (design decisions, constraints, config values, naming conventions) and stores them as project memories.
• Consolidate – An optional dreamer runs (usually overnight) to verify memories against the current codebase, merge duplicates, prune stale entries, and keep documentation up‑to‑date.
• Recall – On every turn the system injects the most relevant memories into the prompt. Developers can also invoke ctx_search, ctx_expand, ctx_note, etc., to retrieve or edit memories, search git commits, or defer notes.
• Context‑window handling – The historian creates tiered compartments that summarize older messages with importance scores, keeping the active prompt small while preserving the full thread. Cache‑aware reduction ensures the model’s prompt cache isn’t invalidated.
• Cross‑harness support – Works with the three main CortexKit harnesses (OpenCode, Pi, Oh‑My‑Pi) and disables any competing context‑management plugins automatically.

Installation & setup

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/cortexkit/magic-context/master/scripts/install.sh | bash
# Windows PowerShell
irm https://raw.githubusercontent.com/cortexkit/magic-context/master/scripts/install.ps1 | iex
# Or any OS via npx
npx @cortexkit/magic-context@latest setup

The wizard detects which harness you use, adds the appropriate plugin (@cortexkit/opencode-magic-context, @cortexkit/pi-magic-context, etc.), disables the host’s built‑in compaction, and helps you pick models for the historian, dreamer, and sidekick.

Configuration – A JSONC file (magic-context.jsonc) lets you specify per‑harness model IDs for the historian (required) and optionally for the dreamer and sidekick. You can also enable/disable embeddings, temporal awareness, and automatic search hints.

Typical workflow

1. Run the setup wizard (or add the plugin manually to your harness config).
2. The historian starts summarizing chat history and promoting durable facts to project memory.
3. Optionally enable the dreamer (/ctx-dream) to run overnight maintenance.
4. During a session, the agent automatically receives relevant memories; you can also query them with ctx_search or edit them with ctx_memory.

Commands you’ll use

Command	What it does
/ctx-status	Shows current memory stats, pending drops, historian progress, etc.
/ctx-flush	Forces all queued reductions/compressions to run immediately
/ctx-recomp	Rebuilds compartments from raw history (useful if state looks corrupted)
/ctx-dream	Triggers the dreamer’s maintenance cycle on demand
/ctx-search (tool)	Semantic/keyword search across memories, chat, git commits, notes
/ctx-note	Create a deferred note that the dreamer can surface later

Why it matters – Without Magic Context, each coding‑agent session starts with a blank slate and suffers periodic “compaction” pauses that drop context. Magic Context lets a single session run for weeks or months, preserving project knowledge and reducing token cost, while keeping the agent’s prompt cache stable.

Where to learn more – Full docs are at https://docs.cortexkit.io/magic-context, and a Discord community is linked in the README for support.