|
| 1 | +# Magic Context — Pi extension |
| 2 | + |
| 3 | +Cross-session memory and context management for [Pi coding agent](https://github.com/mariozechner/pi-mono). Shares the same SQLite database as the [OpenCode plugin](https://www.npmjs.com/package/@cortexkit/opencode-magic-context), so memories, embeddings, dreamer state, and project knowledge follow you across both harnesses. |
| 4 | + |
| 5 | +> **Status:** v0.1.0 — first release. Production-ready for interactive Pi sessions; `pi --print` mode has a known limitation (see below). |
| 6 | +
|
| 7 | +--- |
| 8 | + |
| 9 | +## What it does |
| 10 | + |
| 11 | +Magic Context is a context engine that keeps long Pi sessions productive by: |
| 12 | + |
| 13 | +| Feature | What it does | |
| 14 | +|---|---| |
| 15 | +| **Tagging + drops** | Tags every assistant/user/tool message with `§N§ ` so you can drop specific turns later via `ctx_reduce` | |
| 16 | +| **Historian** | Background subagent compresses old conversation into compartments + facts at threshold pressure or commit boundaries | |
| 17 | +| **`<session-history>` injection** | Prepends compressed history into the system prompt every turn so the agent never loses context | |
| 18 | +| **Project memories** | Persistent cross-session knowledge store with embedding-based semantic search | |
| 19 | +| **Dreamer** | Scheduled background subagent that consolidates, verifies, archives, and improves stored memories | |
| 20 | +| **`/ctx-aug`** | On-demand sidekick that augments the next turn with relevant memories | |
| 21 | +| **Auto-search hint** | When user prompts mention previously-discussed topics, appends a compact memory hint | |
| 22 | +| **Note nudges** | Surface deferred intentions at natural work boundaries (commit, todo completion, historian publication) | |
| 23 | +| **Cross-harness sharing** | Memories written from OpenCode appear in Pi (and vice versa) for the same project | |
| 24 | + |
| 25 | +--- |
| 26 | + |
| 27 | +## Installation |
| 28 | + |
| 29 | +```bash |
| 30 | +# Install via npm |
| 31 | +npm install -g @cortexkit/pi-magic-context |
| 32 | + |
| 33 | +# Or via Bun |
| 34 | +bun add -g @cortexkit/pi-magic-context |
| 35 | +``` |
| 36 | + |
| 37 | +Add the extension to your Pi config (`~/.pi/agent/settings.json`): |
| 38 | + |
| 39 | +```jsonc |
| 40 | +{ |
| 41 | + "extensions": [ |
| 42 | + "@cortexkit/pi-magic-context" |
| 43 | + ] |
| 44 | +} |
| 45 | +``` |
| 46 | + |
| 47 | +Then run the interactive setup wizard: |
| 48 | + |
| 49 | +```bash |
| 50 | +magic-context-pi setup |
| 51 | +``` |
| 52 | + |
| 53 | +The wizard will: |
| 54 | +1. Create `~/.pi/agent/magic-context.jsonc` with sensible defaults |
| 55 | +2. Prompt you for historian, sidekick, and embedding model preferences |
| 56 | +3. Verify your model picks resolve correctly via Pi's CLI |
| 57 | + |
| 58 | +To check installation health later: |
| 59 | + |
| 60 | +```bash |
| 61 | +magic-context-pi doctor |
| 62 | +``` |
| 63 | + |
| 64 | +--- |
| 65 | + |
| 66 | +## Configuration |
| 67 | + |
| 68 | +Magic Context reads two config files (in this priority order): |
| 69 | + |
| 70 | +1. `$cwd/.pi/magic-context.jsonc` (project-level overrides) |
| 71 | +2. `~/.pi/agent/magic-context.jsonc` (user-level defaults) |
| 72 | + |
| 73 | +Both are merged through a Zod schema. Invalid fields fall back to defaults — bad config never disables the plugin entirely. |
| 74 | + |
| 75 | +### Minimal config |
| 76 | + |
| 77 | +```jsonc |
| 78 | +{ |
| 79 | + "$schema": "https://raw.githubusercontent.com/cortexkit/opencode-magic-context/master/assets/magic-context.schema.json", |
| 80 | + "enabled": true, |
| 81 | + "historian": { |
| 82 | + "model": "anthropic/claude-haiku-4-5" |
| 83 | + }, |
| 84 | + "embedding": { |
| 85 | + "provider": "local" |
| 86 | + } |
| 87 | +} |
| 88 | +``` |
| 89 | + |
| 90 | +For the full configuration reference (including dreamer, sidekick, auto-search, and experimental features), see [CONFIGURATION.md](https://github.com/cortexkit/opencode-magic-context/blob/master/CONFIGURATION.md) in the main repository — the schema is shared between both plugins. |
| 91 | + |
| 92 | +--- |
| 93 | + |
| 94 | +## Slash commands |
| 95 | + |
| 96 | +All commands trigger `triggerTurn: false` (never sent to the LLM): |
| 97 | + |
| 98 | +| Command | What it does | |
| 99 | +|---|---| |
| 100 | +| `/ctx-status` | Live token breakdown + queued ops + cache state | |
| 101 | +| `/ctx-flush` | Force-process pending ops queue | |
| 102 | +| `/ctx-recomp` | Rebuild compartments from raw history (heavy operation) | |
| 103 | +| `/ctx-dream` | Trigger a dream run on demand | |
| 104 | +| `/ctx-aug` | Augment your next prompt with sidekick-retrieved memories | |
| 105 | + |
| 106 | +--- |
| 107 | + |
| 108 | +## Storage |
| 109 | + |
| 110 | +Magic Context stores everything in a single shared SQLite database at: |
| 111 | + |
| 112 | +``` |
| 113 | +~/.local/share/cortexkit/magic-context/context.db |
| 114 | +``` |
| 115 | + |
| 116 | +This is the **same database** the OpenCode plugin uses. Tables are scoped by: |
| 117 | +- `harness` column (`'pi'` or `'opencode'`) for session-scoped data (tags, compartments, facts, notes) |
| 118 | +- `project_path` (resolved git root) for project-scoped data (memories, embeddings, dreamer runs) |
| 119 | + |
| 120 | +So memories and dreamer state are shared across both harnesses for the same project; per-session tagging stays correctly attributed. |
| 121 | + |
| 122 | +Storage failures are fatal — Magic Context will refuse to register hooks rather than run with ephemeral state, since that would let context grow unbounded across restarts. |
| 123 | + |
| 124 | +--- |
| 125 | + |
| 126 | +## Cross-harness coherence |
| 127 | + |
| 128 | +For semantic search to work across harnesses, both plugins must use the **same embedding model**. Magic Context detects mismatch on Pi startup and warns: |
| 129 | + |
| 130 | +``` |
| 131 | +WARN embedding model mismatch detected for project ...: |
| 132 | +stored vectors use "openai-compatible:Qwen/Qwen3-Embedding-8B" but Pi is configured with "local:Xenova/all-MiniLM-L6-v2". |
| 133 | +Cross-harness search will return zero results until vectors are re-embedded. |
| 134 | +``` |
| 135 | + |
| 136 | +Easiest fix: configure `embedding` once in `~/.pi/agent/magic-context.jsonc` (Pi) and `~/.config/opencode/magic-context.jsonc` (OpenCode) with identical settings. |
| 137 | + |
| 138 | +--- |
| 139 | + |
| 140 | +## Tools available to the agent |
| 141 | + |
| 142 | +| Tool | Action set | Purpose | |
| 143 | +|---|---|---| |
| 144 | +| `ctx_search` | n/a | Search memories + raw session history; returns ranked results with previews | |
| 145 | +| `ctx_memory` | `write`, `delete` | Manage project memories explicitly (most writes happen via dreamer instead) | |
| 146 | +| `ctx_note` | `read`, `write`, `update`, `dismiss` | Defer intentions for later — surfaced via note nudges at work boundaries | |
| 147 | + |
| 148 | +`ctx_expand` and `ctx_reduce` from the OpenCode plugin are **intentionally not exposed on Pi** — they depend on raw OpenCode message ordinals, while Pi has its own message identity model. Drops still happen automatically via threshold-driven historian; you don't need an explicit `ctx_reduce` to trigger reduction. |
| 149 | + |
| 150 | +--- |
| 151 | + |
| 152 | +## Known limitation: `pi --print` mode |
| 153 | + |
| 154 | +Pi's `--print` mode is single-turn: the process exits immediately after `agent_end`. Magic Context fires historian as a background subagent (so the LLM call never blocks on summarization), but Pi's `agent_end` event uses synchronous listener fanout — the parent process exits while our async `await` is still pending, killing the spawned historian subprocess mid-run. |
| 155 | + |
| 156 | +**Production users running interactive `pi` are unaffected.** The historian started on turn N completes during turn N+1's user-think time, the same pattern OpenCode uses. |
| 157 | + |
| 158 | +For `--print` mode, the upstream fix is in progress: pi-coding-agent commit `9022a5b5 fix(agent): await subscribed event handlers` (shipped in `^0.70.5`). Once you're on that version, `--print` mode also works end-to-end. |
| 159 | + |
| 160 | +--- |
| 161 | + |
| 162 | +## Architecture & implementation |
| 163 | + |
| 164 | +This package is part of the [opencode-magic-context monorepo](https://github.com/cortexkit/opencode-magic-context). The Pi extension shares the core implementation (~7,500 lines) with the OpenCode plugin via the `@magic-context/core` workspace dependency, exposing only the Pi-specific adapter layer: |
| 165 | + |
| 166 | +| Pi-specific module | Responsibility | |
| 167 | +|---|---| |
| 168 | +| `context-handler.ts` | Pi `pi.on("context", ...)` adapter — tags, drops, runs nudges and auto-search | |
| 169 | +| `subagent-runner.ts` | Spawns `pi --print --mode json --no-extensions ...` for historian/sidekick/dreamer | |
| 170 | +| `tools/` | Pi `pi.registerTool` wrappers around the shared tool implementations | |
| 171 | +| `commands/` | Pi `pi.registerCommand` wrappers for the five `/ctx-*` slash commands | |
| 172 | +| `dreamer/` | Pi-side adapter for the shared dreamer scheduler | |
| 173 | +| `system-prompt.ts` | Pi `before_agent_start` injector for `<session-history>`, `<project-memory>`, `<project-docs>` | |
| 174 | +| `config/` | Pi-convention config loader (`$cwd/.pi/magic-context.jsonc` + `~/.pi/agent/magic-context.jsonc`) | |
| 175 | +| `cli/` | `magic-context-pi setup` and `magic-context-pi doctor` | |
| 176 | + |
| 177 | +For deeper architectural detail, see the main repo's [ARCHITECTURE.md](https://github.com/cortexkit/opencode-magic-context/blob/master/ARCHITECTURE.md). |
| 178 | + |
| 179 | +--- |
| 180 | + |
| 181 | +## License |
| 182 | + |
| 183 | +MIT — see [LICENSE](https://github.com/cortexkit/opencode-magic-context/blob/master/LICENSE). |
0 commit comments