![\"npm](\"https://img.shields.io/npm/v/@cortexkit/magic-context?label=cli&color=orange&style=flat-square\")
\n ![\"npm](\"https://img.shields.io/npm/v/@cortexkit/opencode-magic-context?label=opencode&color=blue&style=flat-square\")
\n ![\"npm](\"https://img.shields.io/npm/v/@cortexkit/pi-magic-context?label=pi&color=purple&style=flat-square\")
\n ![\"Discord\"](\"https://img.shields.io/discord/1488852091056295957?style=flat-square&logo=discord&logoColor=white&label=Discord&color=5865F2\")
\n ![\"stars\"](\"https://img.shields.io/github/stars/cortexkit/magic-context?style=flat-square&color=yellow\")
\n ![\"MIT](\"https://img.shields.io/badge/license-MIT-green?style=flat-square\"){kind=icon}
\n\n English |\n 简体中文 |\n 繁體中文 |\n 한국어 |\n Deutsch |\n Español |\n Français |\n Italiano |\n Dansk |\n 日本語 |\n Polski |\n Русский |\n Bosanski |\n العربية |\n Norsk |\n Português (Brasil) |\n ไทย |\n Türkçe |\n Українська |\n বাংলা |\n Ελληνικά |\n Tiếng Việt\n
\n\n\n Unbounded context. Memory that manages itself. One session, for life.
\n The hippocampus for coding agents, part of CortexKit.\n
\n
\n You don't hire a developer for one task and fire them when they ship.
Stop doing it to your agent.\n
\n What is Magic Context? ·\n Quick Start ·\n CortexKit ·\n Context ·\n Capture ·\n Consolidate ·\n Recall ·\n Docs ·\n Configuration ·\n Dashboard ·\n 💬 Discord\n
\n\n---\n\n## What is Magic Context?\n\nYou 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.\n\nCoding 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.\n\nMagic 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:\n\n- **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.\n- **Consolidate.** Overnight, dreamer agents do what sleep does for you: verify memories against the codebase, curate duplicates and stale entries, and promote what recurs.\n- **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, Pi, and OMP.\n\nTwo promises: your agent **never stops to manage its context** (no compaction pauses, no broken flow) and it **never forgets**.\n\nRun one session per project and keep it going for weeks, months, or years. It remembers everything you've built together.\n\n---\n\n## Quick start\n\nRun the interactive setup wizard. It detects your models, configures everything, and handles compatibility.\n\n**macOS / Linux:**\n```bash\ncurl -fsSL https://raw.githubusercontent.com/cortexkit/magic-context/master/scripts/install.sh | bash\n```\n\n**Windows (PowerShell):**\n```powershell\nirm https://raw.githubusercontent.com/cortexkit/magic-context/master/scripts/install.ps1 | iex\n```\n\n**Or run directly (any OS):**\n```bash\nnpx @cortexkit/magic-context@latest setup\n```\n\nThe wizard auto-detects which harnesses you have (OpenCode, Pi, OMP, or any combination), adds the plugin, disables built-in compaction, helps you pick models for the historian and dreamer, and resolves conflicts with other context-management plugins. Target one with `--harness opencode`, `--harness pi`, or `--harness omp`.\n\n> **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.\n\n### Manual setup (OpenCode)\n\nIf you cannot run the wizard, add this to `opencode.jsonc`:\n\n```jsonc\n{\n \"plugin\": [\"@cortexkit/opencode-magic-context@latest\"],\n \"compaction\": { \"auto\": false, \"prune\": false }\n}\n```\n\n> **Plugin updates:** A bare plugin entry is pinned to the downloaded exact version before restart so OpenCode does not remove the active package mid-session. Magic Context records the exact spec written by its updater and advances that updater-owned pin on later checks. Any other exact spec is treated as pinned by you and is not changed. Because provenance is keyed to the exact spec string, manually changing the entry to the same spec the updater last wrote is indistinguishable from the updater's pin and will be advanced. To opt out, set `auto_update: false` or pin any other exact version. To deliberately stay unpinned, write `@latest` explicitly (OpenCode may remove an unpinned active package mid-session).\n\nThen create `magic-context.jsonc` with the OpenCode historian setting:\n\n```jsonc\n{\n \"$schema\": \"https://raw.githubusercontent.com/cortexkit/magic-context/master/assets/magic-context.schema.json\",\n \"historian\": {\n \"opencode\": { \"model\": \"provider/model-id\" }\n }\n}\n```\n\n- **Required:** `historian.opencode.model` must be a real `provider/model-id`. Without it, the plugin loads but historian runs fail, older history is not summarized, and repeated failures show a `Magic Context — history comparting needs attention` notice.\n- **Optional:** the `dreamer` model/disable block. Omit it to leave periodic memory consolidation off.\n- **Optional:** `embedding`. Omit it to use the local `Xenova/all-MiniLM-L6-v2`; turning embeddings off removes semantic/embedding-backed search, but keyword search and context management continue.\n\n### Flat model-config migration (before/after)\n\nExisting flat model settings migrate automatically on the first config read. The\nflat form below is shown only as a migration **before** example; write the\nper-harness **after** form for all new configuration.\n\n**Before (flat shape — migration only):**\n\n```jsonc\n{\n \"historian\": {\n \"model\": \"provider/model-id\",\n \"thinking_level\": \"medium\"\n }\n}\n```\n\n**After (per-harness shape):**\n\n```jsonc\n{\n \"historian\": {\n \"opencode\": { \"model\": \"provider/model-id\" },\n \"pi\": {\n \"model\": \"provider/model-id\",\n \"thinking_level\": \"medium\"\n },\n \"omp\": {\n \"model\": \"opencode/provider-model-id\",\n \"thinking_level\": \"auto\"\n }\n }\n}\n```\n\nOMP uses Pi-native `thinking_level` qualifiers. If `historian.omp` or `dreamer.omp` is absent, OMP falls back to the matching `pi` block, so existing Pi-compatible configurations need no migration. An explicit OMP block is authoritative even when it omits a model.\n\nUser-level config is `~/.config/cortexkit/magic-context.jsonc` on macOS/Linux and `%USERPROFILE%\\.config\\cortexkit\\magic-context.jsonc` on Windows (or `$XDG_CONFIG_HOME/cortexkit/magic-context.jsonc` when set). OpenCode Desktop users can use the dashboard's config editor or hand-edit that file; Desktop does not include the CLI setup wizard.\n\n**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.\n\n**Oh My Pi (OMP):** `npx @cortexkit/magic-context@latest setup --harness omp` (requires OMP `>= 17.1.7`). Setup installs the Pi-compatible extension through `omp plugin`, disables OMP native compaction and automatic memory, and honors OMP profiles, `PI_CODING_AGENT_DIR`, and initialized XDG layouts.\n\n**Troubleshooting:** `npx @cortexkit/magic-context@latest doctor` auto-detects your harnesses, checks host-specific conflicts, verifies plugin registration and database integrity, and fixes what it can. Add `--issue` to file a ready-to-submit bug report.\n\nWorks 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, Pi, or OMP sessions from before it was installed.\n\n\n ⬇️ Download for macOS · Windows · Linux\n
\n\n- **Memory browser**: search, filter, and edit project memories by category and project.\n- **Session history**: browse compartments and notes for any session with timeline navigation.\n- **Cache diagnostics**: real-time cache hit/miss timeline and bust-cause detection.\n- **Dreamer management**: view dream-run history, trigger runs, inspect task results.\n- **Configuration editor**: form-based editing for every setting, including model fallback chains.\n- **Log viewer**: live-tailing logs with search.\n\nIt reads directly from Magic Context's SQLite database. No extra server, no API. Auto-updates built in.\n\n---\n\n## Configuration\n\nSettings live in `magic-context.jsonc`. Most settings have sensible defaults, but the active harness's historian model (`historian.opencode.model`, `historian.pi.model`, or `historian.omp.model`) is required for history compacting; project config merges on top of user-wide settings. For the full reference — cache TTL tuning, per-model execute thresholds, historian and dreamer model selection, embedding providers, memory settings, and prompt-surface presets (`full`/`light`) — see **[CONFIGURATION.md](./CONFIGURATION.md)** or the **[configuration reference on docs.cortexkit.io](https://docs.cortexkit.io/magic-context/reference/configuration/)**.\n\n> **Note on per-model settings:** `prompt_surface.models` always routes the injected guidance block. OpenCode 1.x, Pi, and OMP register tool descriptions once per process (they follow `prompt_surface.default`). OpenCode 2 rewrites the five `ctx_*` descriptions per request from the draft model.\n\n**Config locations** (one shared CortexKit location, project overrides user):\n1. `