English | 简体中文 | 繁體中文 | 한국어 | Deutsch | Español | Français | Italiano | Dansk | 日本語 | Polski | Русский | Bosanski | العربية | Norsk | Português (Brasil) | ไทย | Türkçe | Українська | বাংলা | Ελληνικά | Tiếng Việt

Magic Context

Unbounded context. Memory that manages itself. One session, for life.
The hippocampus for coding agents, part of CortexKit.

You don't hire a developer for one task and fire them when they ship.
Stop doing it to your agent.

What is Magic Context? · Quick Start · CortexKit · Context · Capture · Consolidate · Recall · Docs · Configuration · Dashboard · 💬 Discord

What is Magic Context?

You don't hire a developer to fix one bug and fire them the moment it ships. You keep the good ones. They learn the codebase, remember why decisions were made, and get sharper every week.

Coding agents work the opposite way. Every task is a fresh hire with no memory of your project, and at the end of each session you fire them and start from zero. Mid-task they even hit "compaction" pauses that break the flow and quietly drop what they knew. It is anterograde amnesia, the same thing that happens when the hippocampus is damaged.

Magic Context gives them one. It is the hippocampus for coding agents, the part of the brain that forms memories, consolidates them, and recalls them, entirely in the background. One session stops being a disposable contractor and becomes a long-term teammate who was there for the whole project:

• Capture. As the historian compresses your history, it lifts the durable knowledge (decisions, constraints, conventions) into project memory. You get a memory system for free, from work you are already doing.
• Consolidate. Overnight, dreamer agents do what sleep does for you: verify memories against the codebase, curate duplicates and stale entries, and promote what recurs.
• Recall. The right memories surface automatically every turn, and the agent can search across memories, past conversations, and git history on demand. Across sessions, and across OpenCode and Pi.

Two promises: your agent never stops to manage its context (no compaction pauses, no broken flow) and it never forgets.

Run one session per project and keep it going for weeks, months, or years. It remembers everything you've built together.

Quick start

Run the interactive setup wizard. It detects your models, configures everything, and handles compatibility.

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 run directly (any OS):

npx @cortexkit/magic-context@latest setup

The wizard auto-detects which harnesses you have (OpenCode, Pi, or both), adds the plugin, disables built-in compaction, helps you pick models for the historian, dreamer, and sidekick, and resolves conflicts with other context-management plugins. Target a specific harness with --harness opencode or --harness pi.

Why disable built-in compaction? Magic Context manages context itself. The host's compaction would interfere with its cache-aware deferred operations and double-compress.

Manual setup (OpenCode): add the plugin and turn compaction off in opencode.json, then drop a magic-context.jsonc in <project>/.cortexkit/ (or ~/.config/cortexkit/ for user-wide defaults). See the configuration reference.

{
  "plugin": ["@cortexkit/opencode-magic-context"],
  "compaction": { "auto": false, "prune": false }
}

Pi: npx @cortexkit/magic-context@latest setup --harness pi (requires Pi >= 0.74.0). The Pi extension shares the same database as OpenCode; project memories and embeddings pool across both.

Troubleshooting: npx @cortexkit/magic-context@latest doctor auto-detects your harnesses, checks for conflicts (compaction, OMO hooks, DCP), verifies the plugin and TUI sidebar, runs an integrity check on the database, and fixes what it can. Add --issue to file a ready-to-submit bug report.

Works the same on a brand-new or a long-running project: install, restart the harness, and Magic Context captures context from that point forward. It does not backfill OpenCode or Pi sessions from before it was installed.

Magic Context owns context management end to end, so it disables itself if another plugin is already doing that job. Running two context managers at once would double-compress your history and thrash the prompt cache. On startup it checks for the following; setup and doctor help you resolve each, and until they're resolved Magic Context stays off (fail-safe) and tells you why:

• OpenCode built-in compaction (compaction.auto / compaction.prune) — Magic Context replaces it. Setup turns it off.
• DCP (opencode-dcp) — a separate context-pruning plugin. The two cannot run together; remove it from your plugin list.
• oh-my-opencode (OMO) — setup offers to disable the three hooks that overlap:
  • preemptive-compaction — triggers compaction that conflicts with the historian.
  • context-window-monitor — injects usage warnings that overlap with Magic Context's nudges.
  • anthropic-context-window-limit-recovery — triggers emergency compaction that bypasses the historian.

Run npx @cortexkit/magic-context@latest doctor any time to re-check and auto-fix.

Part of CortexKit

A brain isn't one organ. Neither is a capable coding agent.

CortexKit is a family of plugins, each modeled on a different region of the brain. Install one and your agent gets sharper. Install all three and it has a brain.

Magic Context is 1 of the 3 plugins you'll ever need. It remembers; AFT perceives and acts; Alfonso decides. They share one CortexKit store, so memory pools across harnesses and tools.

⚡ Context management

An unbounded session that manages itself. The context window fills up as you work, and the usual fix, compaction, stops the agent cold to re-read everything. Magic Context handles it continuously in the background, so the session just keeps going.

• Historian compartmentalization: a background historian compresses old raw history into tiered compartments, chronological summaries that stand in for older messages. Each carries an importance score, so the live window stays small without losing the thread. Summarizing doesn't need your primary's coding muscle, so you can run the historian on a cheap or even fully local model while your main agent stays top-tier.
• Decay rendering: compartments render at the right fidelity for the moment, by a deterministic, no-LLM rule that self-tunes to the model's context window. Old history fades gracefully instead of dropping off a cliff, and because it is deterministic, the same history always renders the same way.
• The agent hints what to drop, or it doesn't: with agent-driven reduction on, the agent calls ctx_reduce to mark stale tool outputs or long messages for removal. Drops are queued and cache-aware, applied only at cache-safe moments so reduction never thrashes the cache. Switch it off and the agent stays out of context management entirely: stale output is shed automatically by age, with optional caveman compression of the oldest text.
• Cache-stable layout: all of this is structured so background work never invalidates the cached prefix of your prompt. Your cache survives the whole session.

The result: one session runs for months, with no compaction pauses and low cost on cache-priced providers. You can watch it happen in OpenCode's TUI, where a live sidebar shows the context breakdown by source, historian status, and memory counts, updating after every message.

Optional (off by default): caveman text compression progressively compresses the oldest user and assistant text by a deterministic age-tiered rule, for sessions that run with agent-driven reduction off.

🧠 Capture

Memory, for free. To compress your history, the historian has to read all of it. So in the same pass it lifts out the knowledge worth keeping forever, decisions, constraints, conventions, config values, and promotes it into project memory, categorized and carried into every future session. Your memory builds itself from the work you are already doing.

The agent can also record memories explicitly, though most are captured automatically for it:

• ctx_memory: write or delete cross-session knowledge directly, in a small category taxonomy (PROJECT_RULES, ARCHITECTURE, CONSTRAINTS, CONFIG_VALUES, NAMING).

ctx_memory(action="write", category="ARCHITECTURE", content="Event sourcing for orders.")

Temporal awareness (on by default) gives the agent a sense of time, with gap markers like +2h 15m between messages and dated compartments, so it can reason about how long ago something happened. Set temporal_awareness: false to turn it off.

🌙 Consolidate

What sleep does for memory. An optional dreamer agent runs overnight to keep memory quality high, spinning up ephemeral child sessions for each task:

• Verify: incrementally check memories against the current codebase (paths, configs, patterns) and fix/remove stale facts.
• Curate: scan the whole memory pool to merge duplicates, tighten wording, and archive low-value or redundant entries.
• Classify: score each memory's importance, scope, and safe shareability without disturbing the live prompt cache.
• Maintain docs: keep ARCHITECTURE.md and STRUCTURE.md current from codebase changes.
• User memories: promote recurring observations about how you work (communication style, review focus, working patterns) into a <user-profile> that travels with every session.
• Smart notes: evaluate deferred notes whose surface_condition has come true and surface the ready ones.

Because it runs during idle time, the dreamer pairs well with local models, even slow ones. Nobody is waiting. Trigger a run any time with /ctx-dream.

🔎 Recall

The right memory at the right moment. Every turn, active project memories and the compacted session history are injected automatically and cache-stably. On demand, the agent reaches for:

• ctx_search: one query across three layers at once: project memories, raw conversation history, and indexed git commits. Semantic embeddings with full-text fallback.

  ctx_search(query="why did we pick event sourcing for orders")

• ctx_expand: pull a compressed history range back to the original U:/A: transcript when the agent needs the exact details.

• ctx_note: a scratchpad for deferred intentions. Notes resurface at natural boundaries (after commits, after historian runs, when todos finish). Smart notes carry an open-ended condition the dreamer watches for.

Recall works across sessions (a new session inherits everything) and across harnesses (write a memory in OpenCode, retrieve it in Pi).

Auto search hints (on by default) run a background ctx_search each turn and whisper a "vague recall" when something relevant exists — like almost remembering a note you took. It appends only compact fragments, never full content; set memory.auto_search.enabled: false to turn it off. Git commit indexing (opt-in) makes your project history semantically searchable as a fourth ctx_search source — enable with memory.git_commit_indexing.enabled: true.

Agent tools at a glance