@cortexkit/opencode-magic-context 0.21.8 → 0.22.1

package/README.md

@@ -1,8 +1,8 @@
 <h1 align="center">Magic Context</h1>
 
 <p align="center">
-  <strong>Cache-aware infinite context, cross-session memory, and background history compression for AI coding agents.</strong><br>
-  Keeps your agent's memory intact — no matter how long the session runs.
+  <strong>Unbounded context. Memory that manages itself. One session, for life.</strong><br>
+  The hippocampus for coding agents, part of CortexKit.
 </p>
 
 <p align="center">
@@ -11,26 +11,21 @@
   <a href="https://www.npmjs.com/package/@cortexkit/pi-magic-context"><img src="https://img.shields.io/npm/v/@cortexkit/pi-magic-context?label=pi&color=purple&style=flat-square" alt="npm @cortexkit/pi-magic-context"></a>
   <a href="https://discord.gg/DSa65w8wuf"><img src="https://img.shields.io/discord/1488852091056295957?style=flat-square&logo=discord&logoColor=white&label=Discord&color=5865F2" alt="Discord"></a>
   <a href="https://github.com/cortexkit/magic-context/stargazers"><img src="https://img.shields.io/github/stars/cortexkit/magic-context?style=flat-square&color=yellow" alt="stars"></a>
-  <a href="https://github.com/cortexkit/magic-context/commits"><img src="https://img.shields.io/github/last-commit/cortexkit/magic-context?style=flat-square&color=green" alt="last commit"></a>
   <a href="https://github.com/cortexkit/magic-context/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT License"></a>
 </p>
 
 <p align="center">
-  Available for <a href="https://opencode.ai/">OpenCode</a> and the <a href="https://pi.dev">Pi coding agent</a>. Memories, embeddings, dreamer state, and project knowledge are <strong>shared across both</strong> — write a memory in OpenCode, retrieve it in Pi (and vice versa).
+  <em>You don't hire a developer for one task and fire them when they ship.<br>Stop doing it to your agent.</em>
 </p>
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/cortexkit/magic-context/master/packages/plugin/docs/animation/out/optimized2.gif" alt="Magic Context in action" width="720">
-</p>
-
-<p align="center">
-  <a href="#get-started">Get Started</a> ·
   <a href="#what-is-magic-context">What is Magic Context?</a> ·
-  <a href="#what-your-agent-gets">What Your Agent Gets</a> ·
-  <a href="#how-it-works">How It Works</a> ·
-  <a href="#magic-context-app">🖥️ Desktop App</a> ·
-  <a href="#commands">Commands</a> ·
-  <a href="#configuration">Configuration</a> ·
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#part-of-cortexkit">CortexKit</a> ·
+  <a href="#-context-management">Context</a> ·
+  <a href="#-capture">Capture</a> ·
+  <a href="#-consolidate">Consolidate</a> ·
+  <a href="#-recall">Recall</a> ·
   <a href="https://discord.gg/DSa65w8wuf">💬 Discord</a>
 </p>
 
@@ -38,53 +33,25 @@
 
 ## What is Magic Context?
 
-Your agent **should never stop working** to manage its own context. Magic Context is an OpenCode plugin that handles context and memory management entirely in the background:
-
-**1.** Transparent context compaction via a **background historian** — the main agent keeps working while a separate model compresses older conversation. All operations are **cache-aware** and deferred to avoid wasting cached prefixes.
-
-**2.** **Cross-session project memory** — architecture decisions, constraints, and preferences persist across conversations.
-
-**3.** Overnight dreamer agent that consolidates, deduplicates, and promotes memories into canonical facts, plus maintains codebase documentation.
-
-**4.** On-demand sidekick that augments prompts with relevant project context.
-
-**5.** TUI sidebar with live context breakdown, token usage, historian status, and memory counts — right inside the terminal.
-
-## Best way to use Magic Context?  
-
-Keep using the **same session** for **weeks**, **months**, or even **years**. **One session** per **project**!
-
----
-
-### ✨ Recent Highlights
-
-**Subagents now self-manage context (v0.15)** — subagent sessions now run age-based tool drops, reasoning clearing, and structural stripping at the execute threshold — the same way primary sessions with `ctx_reduce_enabled: false` behave. Previously they had no automatic reduction and grew silently until overflow. Nudges, historian/compartment runs, and the `<session-history>` block remain primary-only — subagents stay lean and parent-driven.
+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.
 
-**Lean sessions when `ctx_reduce_enabled: false` (v0.15)** — when you opt out of agent-driven reduction, the `§N§` tag prefix on user/assistant text and tool output is no longer injected, saving several thousand tokens per long session. The injected prompt guidance also switches to the no-reduce variant so the agent isn't told about a tool it can't use. DB tag records still exist (heuristic cleanup, persistence, and replay all depend on them); only the agent-visible prefix is skipped.
+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.
 
-**User Memories (v0.14)** — enabled by default under `dreamer.user_memories`. Historian extracts behavioral observations about you alongside its normal compartment output (communication style, expertise level, review focus, working patterns). Recurring observations are promoted by the dreamer to stable user memories that appear in all sessions via `<user-profile>`. Set `dreamer.user_memories.enabled: false` to opt out. Requires dreamer.
+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:
 
-**Key File Pinning (v0.14)** — under `dreamer.pin_key_files`, still opt-in. Dreamer analyzes which files your agent reads most frequently across the session. Core orientation files (architecture, config, types) that get re-read after every context drop are pinned into the system prompt as `<key-files>`, so the agent always has them without needing to re-read from disk. Files are read fresh on each cache-busting pass. Enable with `dreamer.pin_key_files.enabled: true`.
+- **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, a dreamer agent does what sleep does for you: it merges duplicates, verifies memories against the codebase, retires the stale, and promotes 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.
 
-> Migrating from an earlier version? Running `npx @cortexkit/magic-context@latest doctor` rewrites old `experimental.user_memories.*` and `experimental.pin_key_files.*` keys into their new `dreamer.*` homes, preserving any `enabled` state you had.
+Two promises: your agent **never stops to manage its context** (no compaction pauses, no broken flow) and it **never forgets**.
 
-### 🧪 New Experimental Features
-
-**Age-tier caveman text compression (v0.15)** — opt-in companion to `ctx_reduce_enabled: false`. Older user/assistant text parts are progressively compressed using deterministic [caveman rules](https://github.com/cortexkit/magic-context/blob/master/packages/plugin/src/hooks/magic-context/caveman.ts) — the oldest 20% go to ultra-compressed, next 20% to full, next 20% to lite, newest 40% untouched. Tier shifts always recompress from the pristine original, never from an already-cavemaned intermediate, so the result is stable across passes. Cache-safe by design. Enable with `experimental.caveman_text_compression: { enabled: true }`. Only active when `ctx_reduce_enabled: false`.
-
-**Temporal Awareness** — gives the agent real-time perception. Each user message gets a small `<!-- +5m -->`/`<!-- +2h 15m -->`/`<!-- +3d 4h -->` gap marker showing time since the previous message, and every compartment in `<session-history>` carries `start-date`/`end-date` attributes. Lets the agent reason correctly about how long a build ran, when a decision was made, or how stale a prior session is. Cache-safe — markers derive from immutable timestamps. Enable with `experimental.temporal_awareness: true`.
-
-**Git Commit Indexing** — indexes HEAD git commits (skipping merges) from the project and makes them searchable through `ctx_search`. Commits are embedded so semantic queries like "when did we change the auth pattern" or "why did we pick X over Y" surface the right work. HEAD-only, windowed to the last year by default, capped at 2000 commits per project with oldest evicted. Enable with `experimental.git_commit_indexing.enabled: true`.
-
-**Auto Search Hints** — before each turn, Magic Context runs a background `ctx_search` on your prompt. When highly relevant content exists, a compact "vague recall" hint is appended to your message with caveman-compressed fragments of the top matches — like a human feeling they almost remember something and going to check their notes. The agent then decides whether to run `ctx_search` for the full content. Cache-safe, fires on top-score ≥ 0.55 by default. Enable with `experimental.auto_search.enabled: true`.
+Run one session per project and keep it going for weeks, months, or years. It remembers everything you've built together.
 
 ---
 
-## Get Started
+## Quick start
 
-### Quick Setup (Recommended)
-
-Run the interactive setup wizard — it detects your models, configures everything, and handles compatibility:
+Run the interactive setup wizard. It detects your models, configures everything, and handles compatibility.
 
 **macOS / Linux:**
 ```bash
@@ -101,271 +68,132 @@ irm https://raw.githubusercontent.com/cortexkit/magic-context/master/scripts/ins
 npx @cortexkit/magic-context@latest setup
 ```
 
-The unified setup wizard auto-detects which harnesses you have installed (OpenCode, Pi, or both) and configures each one. Use `--harness opencode` or `--harness pi` to target a specific harness.
-
-The wizard will:
-1. Detect installed harnesses and available models
-2. Add the plugin and disable built-in compaction
-3. Help you pick models for historian, dreamer, and sidekick
-4. Handle oh-my-opencode compatibility if needed
+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`.
 
-### Manual Setup
+> **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.
 
-Add to your OpenCode config (`opencode.json` or `opencode.jsonc`):
+**Manual setup** (OpenCode): add the plugin and turn compaction off in `opencode.json`, then drop a `magic-context.jsonc` in your project root. See the [configuration reference](./CONFIGURATION.md).
 
 ```jsonc
 {
   "plugin": ["@cortexkit/opencode-magic-context"],
-  "compaction": {
-    "auto": false,
-    "prune": false
-  }
+  "compaction": { "auto": false, "prune": false }
 }
 ```
 
-> **Why disable compaction?** Magic Context manages context itself — built-in compaction interferes with its cache-aware deferred operations and would cause duplicate compression.
-
-Create `magic-context.jsonc` in your project root, `.opencode/`, or `~/.config/opencode/`:
+**Pi (beta):** `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.
 
-```jsonc
-{
-  "$schema": "https://raw.githubusercontent.com/cortexkit/magic-context/master/assets/magic-context.schema.json",
-  "enabled": true,
-
-  // Which model the historian uses for background compression, 
-  // Prefer providers that charge by request instead of tokens
-  "historian": {
-    "model": "github-copilot/gpt-5.4",
-    "fallback_models": ["opencode-go/glm-5"]
-  }
-}
-```
+**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.
 
-> **Tip:** The `$schema` key enables autocomplete and validation in VS Code and other editors.
+<details>
+<summary><strong>Compatibility with other context-management plugins</strong></summary>
 
-That's it. Everything else has sensible defaults. Project config merges on top of user-wide settings; `auto_update` is user-config-only so projects cannot disable plugin self-updates.
+<br>
 
-### Oh-My-OpenCode / Oh-My-OpenAgent Users
+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:
 
-If you use [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent) (formerly oh-my-opencode), disable the hooks that conflict with Magic Context in your `oh-my-openagent.json`:
+- **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.
 
-```json
-{
-  "disabled_hooks": [
-    "context-window-monitor",
-    "preemptive-compaction",
-    "anthropic-context-window-limit-recovery"
-  ]
-}
-```
+Run `npx @cortexkit/magic-context@latest doctor` any time to re-check and auto-fix.
 
-The setup wizard handles this automatically if it detects an oh-my-openagent or oh-my-opencode config.
-
-### Doctor (Troubleshooting)
-
-Already installed but something isn't working? Run the doctor to check and auto-fix configuration issues:
-
-```bash
-npx @cortexkit/magic-context@latest doctor
-```
-
-Doctor auto-detects installed harnesses and runs the right checks for each. Pass `--harness opencode` or `--harness pi` to target a specific harness when you have both installed.
-
-Doctor checks for conflicts (compaction, DCP, OMO hooks), ensures the TUI sidebar is configured (OpenCode), verifies the plugin is registered, validates the magic-context.jsonc, runs `PRAGMA integrity_check` on the shared SQLite DB, and checks the npm cache — fixing what it can automatically. The summary line reports `PASS X / WARN Y / FAIL Z` so you can scan results at a glance.
-
-Use `--force` to force-clear the plugin cache even when versions match (fixes broken transitive dependencies):
-
-```bash
-npx @cortexkit/magic-context@latest doctor --force
-```
-
-Hit a real bug? Use `--issue` to collect environment, sanitized config, and the last 400 log lines into a ready-to-submit report. It can also open the issue directly via `gh` if you have it installed:
-
-```bash
-npx @cortexkit/magic-context@latest doctor --issue
-```
+</details>
 
 ---
 
-## Pi coding agent (beta)
-
-Magic Context is also available as a [Pi](https://github.com/earendil-works/pi-mono) extension, sharing the **same SQLite database** as the OpenCode plugin. Project memories, embeddings, dreamer state, and key-file pins are pooled across both harnesses; per-session state (tags, compartments, facts, notes) stays harness-scoped.
+## Part of CortexKit
 
-> ⚠️ The Pi extension is published as **beta** while it accumulates real-world usage. Core flows are validated with end-to-end tests; report issues at [github.com/cortexkit/magic-context/issues](https://github.com/cortexkit/magic-context/issues).
+A brain isn't one organ. Neither is a capable coding agent.
 
-```bash
-# Setup wizard for Pi (uses the same unified CLI as OpenCode)
-npx @cortexkit/magic-context@latest setup --harness pi
-```
+**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.
 
-Requires Pi `>= 0.71.0`. The wizard handles registration with Pi (`packages` array in `~/.pi/agent/settings.json`), writes `~/.pi/agent/magic-context.jsonc`, and prompts for historian/dreamer/sidekick model picks. Pi-specific docs and config notes live in [`packages/pi-plugin/README.md`](https://github.com/cortexkit/magic-context/blob/master/packages/pi-plugin/README.md).
+| Plugin | Region | What it does |
+|---|---|---|
+| **Magic Context** *(you are here)* | Hippocampus & medial temporal lobe | Self-managing context and long-term memory. Keeps sessions running with no compaction pauses while it forms, consolidates, and recalls project knowledge across them. |
+| **[AFT](https://github.com/cortexkit/aft)** | Sensorimotor cortex | Perceives code structure and acts on it precisely. A proper IDE and OS for your agent. |
+| **Alfonso** *(coming soon)* | Prefrontal cortex | Executive control. Plans, decomposes work, chooses agents and models, and decides when to ask, verify, and commit. |
 
-For health checks:
-
-```bash
-npx @cortexkit/magic-context@latest doctor --harness pi
-```
+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.
 
 ---
 
-## What Your Agent Gets
-
-Magic Context injects structured context automatically and gives the agent five tools.
-
-### `ctx_reduce` — Shed weight
-
-After tool-heavy turns (large grep results, file reads, bash output), the agent calls `ctx_reduce` to mark stale content for removal. Drops are queued — not applied immediately — until the cache expires or context pressure forces it.
-
-```
-ctx_reduce(drop="3-5,12")     // Drop tags 3, 4, 5, and 12
-```
-
-Recent tags (last 20 by default) are protected. Drops targeting them stay queued until they age out.
-
-### `ctx_expand` — Decompress history
-
-When the agent needs to recall details from a compressed history range, it can expand specific compartment ranges back to the original conversation transcript.
-
-```
-ctx_expand(start=100, end=200)   // Expand raw messages 100-200
-```
-
-Returns the same compact `U:`/`A:` transcript format the historian sees, capped at ~15K tokens per request. Use `start`/`end` from compartment attributes visible in `<session-history>`.
+## ⚡ Context management
 
-### `ctx_note` — Deferred intentions
+*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.
 
-Session notes are the agent's scratchpad for things to tackle later — not task tracking (that's what todos are for), but deferred work and reminders that should surface at the right time.
+- **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.
 
-```
-ctx_note(action="write", content="After this fix, check if the compressor budget formula is correct")
-ctx_note(action="read")
-```
-
-Notes surface automatically at natural work boundaries: after commits, after historian runs, and after all todos complete.
-
-**Smart notes** are project-scoped notes with an open-ended `surface_condition` that the dreamer evaluates nightly. When the condition is met, the note surfaces in the next session:
-
-```
-ctx_note(action="write", content="Implement X because Y", surface_condition="When PR #42 is merged in this repo")
-ctx_note(action="dismiss", note_id=1)
-```
+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.
 
-Smart notes require dreamer enabled. Pending notes are invisible until the dreamer marks them ready. Use `dismiss` to clear a surfaced note.
+> *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.
 
-### `ctx_memory` — Persistent cross-session knowledge
+---
 
-Architecture decisions, naming conventions, user preferences — anything that should survive across conversations. Memories are project-scoped and automatically promoted from session facts by the historian.
+## 🧠 Capture
 
-```
-ctx_memory(action="write", category="ARCHITECTURE_DECISIONS", content="Event sourcing for orders.")
-ctx_memory(action="delete", id=42)
-```
+*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.
 
-### `ctx_search` — Unified search
+The agent can also record memories explicitly, though most are captured automatically for it:
 
-Search across all data layers with a single query — project memories, session facts, and raw conversation history. Results are ranked by source (memories first, then facts, then message hits).
+- **`ctx_memory`**: write or delete cross-session knowledge directly, in a small category taxonomy (`PROJECT_RULES`, `ARCHITECTURE`, `CONSTRAINTS`, `CONFIG_VALUES`, `NAMING`).
 
 ```
-ctx_search(query="authentication approach")
+ctx_memory(action="write", category="ARCHITECTURE", content="Event sourcing for orders.")
 ```
 
-Message results include ordinal numbers the agent can pass to `ctx_expand` to retrieve the surrounding conversation context.
-
-### Automatic context injection
-
-Every turn, Magic Context injects a `<session-history>` block containing:
-
-- **Project memories** — cross-session decisions, constraints, and preferences
-- **Compartments** — structured summaries replacing older raw history
-- **Session facts** — durable categorized facts from the current session
-
-This block is stable between historian runs. Memory writes persist immediately for search but don't change the injected block until the next historian run — so writes never bust the cache mid-conversation.
+> **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.
 
 ---
 
-## How It Works
-
-### Tagging
-
-Every message, tool output, and file attachment gets a monotonically increasing `§N§` tag. The agent sees these inline and uses them to reference specific content when calling `ctx_reduce`. Tags persist in the database and resume across restarts.
-
-### Queued reductions
-
-When the agent calls `ctx_reduce`, drops go into a pending queue — not applied immediately. Two conditions trigger execution:
-
-- **Cache expired** — enough time has passed that the cached prefix is likely stale (configurable per model, default 5 minutes)
-- **Threshold reached** — context usage hits `execute_threshold_percentage` (default 65%)
-
-Between triggers, the conversation continues unchanged. The agent doesn't need to think about timing.
-
-### Background historian
+## 🌙 Consolidate
 
-When local drops aren't buying enough headroom, Magic Context starts a historian — a separate lightweight model that reads an eligible prefix of raw history and produces:
+*What sleep does for memory.* An optional **dreamer** agent runs overnight to keep memory quality high, spinning up ephemeral child sessions for each task:
 
-- **Compartments** — chronological blocks that replace older raw messages
-- **Facts** — durable decisions, constraints, and preferences (categorized)
+- **Consolidate**: merge semantically similar memories into canonical facts.
+- **Verify**: check memories against the current codebase (paths, configs, patterns).
+- **Archive stale**: retire memories about removed features or old paths.
+- **Improve**: rewrite verbose memories into terse, operational form.
+- **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.
 
-The historian runs asynchronously. The main agent never waits for it. When the historian finishes, its output is materialized on the next transform pass.
+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`.
 
-A **separate compressor** pass fires when the rendered history block exceeds the configured history budget, merging the oldest compartments to keep the injected context lean.
-
-### Nudging
-
-As context usage grows, Magic Context sends rolling reminders suggesting the agent reduce. Cadence tightens as usage approaches the threshold — from gentle reminders to urgent warnings. If the agent recently called `ctx_reduce`, reminders are suppressed. At 85% Magic Context force-materializes queued drops and emergency cleanup; at 95% it blocks the turn until background historian completes.
-
-### Cross-session memory
-
-After each historian run, qualifying facts are promoted to the persistent memory store. On every subsequent turn, active memories are injected in `<session-history>`. New sessions inherit all project memories from previous sessions.
-
-Memories are searchable via `ctx_search` alongside session facts and raw conversation history, using semantic embeddings (local by default) with full-text search as fallback.
-
-### Dreamer
-
-An optional background agent that maintains memory quality overnight:
-
-- **Consolidate** — merge semantically similar memories into canonical facts
-- **Verify** — check memories against current codebase (configs, paths, code patterns)
-- **Archive stale** — retire memories referencing removed features or old paths
-- **Improve** — rewrite verbose memories into terse operational form
-- **Maintain docs** — update ARCHITECTURE.md and STRUCTURE.md from codebase changes
-- **Evaluate smart notes** — check pending smart note conditions and surface ready notes
-- **Review user memories** — promote recurring user behavior observations to stable memories
-
-The dreamer runs during a configurable schedule window and creates ephemeral OpenCode child sessions for each task. Since it runs during idle time (typically overnight), it works well with local models — even slower ones like `ollama/mlx-qwen3.5-27b-claude-4.6-opus-reasoning-distilled` are fine since there's no user waiting.
-
-When dreamer is enabled, ARCHITECTURE.md and STRUCTURE.md are automatically injected into the agent's system prompt (configurable via `inject_docs`). Content is cached per-session and refreshed on cache-busting passes.
+---
 
-### User Memories
+## 🔎 Recall
 
-Enabled by default under `dreamer.user_memories`. Historian extracts behavioral observations about the user alongside its normal compartment output — things like communication style, expertise level, review focus, and working patterns. These go into a candidate pool.
+*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:
 
-During dreamer runs, a dedicated review pass checks candidates for recurring patterns across sessions. Observations that appear at least `promotion_threshold` times (default 3) are promoted to stable user memories and injected into all sessions via `<user-profile>` in the system prompt.
+- **`ctx_search`**: one query across three layers at once: project **memories**, raw **conversation** history, and indexed **git commits**. Semantic embeddings with full-text fallback.
 
-Stable user memories are visible and manageable in the dashboard's User Memories page. Requires dreamer to be enabled for the promotion step — without dreamer, candidates accumulate but are never promoted. Set `dreamer.user_memories.enabled: false` to opt out.
+  ```
+  ctx_search(query="why did we pick event sourcing for orders")
+  ```
 
-### TUI Sidebar
+- **`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.
 
-When running in OpenCode's terminal UI, Magic Context shows a live sidebar panel with:
+Recall works **across sessions** (a new session inherits everything) and **across harnesses** (write a memory in OpenCode, retrieve it in Pi).
 
-- **Context breakdown bar** — visual token split across System Prompt, Compartments, Facts, Memories, Conversation, Tool Calls, Tool Definitions (measured from the `tool.definition` hook), and Overhead. Cool palette for structured injections, warm palette for user/tool traffic.
-- **Historian status** — idle, running, or compartment/fact counts
-- **Memory counts** — total project memories and how many are injected
-- **Dreamer status** — last run time
-- **Queue status** — pending operations count
+> **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`.
 
-The sidebar updates after every message. Commands (`/ctx-status`, `/ctx-flush`, `/ctx-aug`) also work directly in TUI mode via dialogs and toasts.
+### Agent tools at a glance
 
-The TUI plugin is configured automatically by the setup wizard and the `doctor` command. If you installed manually, add to your `tui.json` or `tui.jsonc`:
-
-```jsonc
-{
-  "plugin": ["@cortexkit/opencode-magic-context"]
-}
-```
-
-### Startup conflict detection
-
-On startup, Magic Context checks for common configuration problems — OpenCode's built-in compaction being enabled, DCP plugin being active alongside Magic Context, or conflicting oh-my-openagent hooks. When conflicts are detected, it warns the active session with a fix suggestion pointing to `npx @cortexkit/magic-context@latest doctor`.
+| Tool | Section | What it does |
+|------|-------|-------------|
+| `ctx_reduce` | Context | Queue stale tagged content for removal, cache-aware |
+| `ctx_memory` | Capture | Write or delete durable cross-session memories |
+| `ctx_search` | Recall | Search memories, conversation history, and git commits |
+| `ctx_expand` | Recall | Decompress a history range back to the transcript |
+| `ctx_note` | Recall | Deferred intentions and dreamer-evaluated smart notes |
 
 ---
 
@@ -373,37 +201,37 @@ On startup, Magic Context checks for common configuration problems — OpenCode'
 
 | Command | Description |
 |---------|-------------|
-| `/ctx-status` | Debug view: tags, pending drops, cache TTL, nudge state, historian progress, compartment coverage, history compression budget |
+| `/ctx-status` | Debug view: tags, pending drops, cache TTL, nudge state, historian progress, compartment coverage, history budget |
 | `/ctx-flush` | Force all queued operations immediately, bypassing cache TTL |
-| `/ctx-recomp` | Rebuild compartments and facts from raw history — use when stored state seems wrong |
-| `/ctx-aug` | Run sidekick augmentation on a prompt — retrieves relevant memories via a separate model |
-| `/ctx-dream` | Run dreamer maintenance on demand — consolidate, verify, archive, improve memories |
+| `/ctx-recomp` | Rebuild compartments from raw history (accepts a `start-end` range). Use when stored state seems wrong |
+| `/ctx-session-upgrade` | Upgrade this session to the latest history format: rebuild compartments and migrate project memories |
+| `/ctx-aug` | Run sidekick augmentation on a prompt: retrieve relevant memories via a separate model |
+| `/ctx-dream` | Run dreamer maintenance on demand: consolidate, verify, archive, improve |
 
 ---
 
-## Magic Context App
+## Desktop app
 
-A companion desktop app for browsing and managing Magic Context state outside of OpenCode.
+A companion desktop app for browsing and managing Magic Context state outside the terminal.
 
 <p align="center">
-   <a href="https://github.com/cortexkit/magic-context/releases/tag/dashboard-v0.4.8"><strong>⬇️ Download for macOS · Windows · Linux</strong></a></p>
+  <a href="https://github.com/cortexkit/magic-context/releases"><strong>⬇️ Download for macOS · Windows · Linux</strong></a>
+</p>
 
-**Features:**
-- **Memory Browser** — search, filter, and edit project memories with category and project filtering
-- **Session History** — browse compartments, facts, and notes for any session with timeline navigation
-- **Cache Diagnostics** — real-time cache hit/miss timeline, bust cause detection, per-session stats
-- **Dreamer Management** — view dream run history per project, trigger runs, inspect task results
-- **Configuration Editor** — form-based editing for all settings including model selection with fallback chains
-- **Log Viewer** — live-tailing log viewer with search
-- **System Tray** — quick access to dreamer status and controls
+- **Memory browser**: search, filter, and edit project memories by category and project.
+- **Session history**: browse compartments and notes for any session with timeline navigation.
+- **Cache diagnostics**: real-time cache hit/miss timeline and bust-cause detection.
+- **Dreamer management**: view dream-run history, trigger runs, inspect task results.
+- **Configuration editor**: form-based editing for every setting, including model fallback chains.
+- **Log viewer**: live-tailing logs with search.
 
-The app reads directly from Magic Context's SQLite database — no additional server or API required. Auto-updates are built in.
+It reads directly from Magic Context's SQLite database. No extra server, no API. Auto-updates built in.
 
 ---
 
 ## Configuration
 
-All settings live in `magic-context.jsonc` as flat top-level keys. See **[CONFIGURATION.md](./CONFIGURATION.md)** for the full reference — cache TTL tuning, per-model execute thresholds, historian model selection, embedding providers, memory settings, sidekick, and dreamer.
+Settings live in `magic-context.jsonc`. Everything has sensible defaults; project config merges on top of user-wide settings. See **[CONFIGURATION.md](./CONFIGURATION.md)** for the full reference: cache TTL tuning, per-model execute thresholds, historian and dreamer model selection, embedding providers, and memory settings.
 
 **Config locations** (merged in order, project overrides user):
 1. `<project-root>/magic-context.jsonc`
@@ -414,33 +242,17 @@ All settings live in `magic-context.jsonc` as flat top-level keys. See **[CONFIG
 
 ## Storage
 
-All durable states live in a local SQLite database. If the database can't be opened, Magic Context disables itself and notifies the user.
+All durable state lives in a local SQLite database under the shared CortexKit store (`~/.local/share/cortexkit/magic-context/context.db`, XDG-equivalent on Windows; legacy OpenCode-folder databases are migrated forward on first boot). If the database can't be opened, Magic Context disables itself and notifies you. Memories are keyed to a **stable project identity** derived from the repo, so they follow a project across worktrees, clones, and forks rather than being tied to a directory path.
 
-```
-~/.local/share/opencode/storage/plugin/magic-context/context.db
-```
+Magic Context also writes to a few other locations:
 
-| Table | Purpose |
-|-------|---------|
-| `tags` | Tag assignments — message ID, tag number, session, status |
-| `pending_ops` | Queued drop operations |
-| `source_contents` | Raw content snapshots for persisted reductions |
-| `compartments` | Historian-produced structured history blocks |
-| `session_facts` | Categorized durable facts from historian runs |
-| `notes` | Unified session notes and project-scoped smart notes |
-| `session_meta` | Per-session state — usage, nudge flags, anchors |
-| `memories` | Cross-session persistent memories |
-| `memory_embeddings` | Embedding vectors for semantic search |
-| `dream_state` | Dreamer lease locking and task progress |
-| `dream_queue` | Queued projects awaiting dream processing |
-| `dream_runs` | Per-project dream run history — task names, durations, memory changes |
-| `compression_depth` | Per-message compression depth for weighted compressor selection |
-| `message_history_fts` | FTS5 index of user/assistant message text for `ctx_search` |
-| `message_history_index` | Tracks last indexed ordinal per session for incremental FTS population |
-| `recomp_compartments` | Staging for `/ctx-recomp` partial progress |
-| `recomp_facts` | Staging for `/ctx-recomp` partial progress |
-| `user_memory_candidates` | User behavior observations from historian (experimental) |
-| `user_memories` | Promoted stable user memories injected into all sessions (experimental) |
+| Path | What | Persistence |
+|---|---|---|
+| `~/.local/share/cortexkit/magic-context/context.db` | SQLite database — tags, compartments, memories, all durable state (XDG-equivalent on Windows) | **Must persist.** Losing it loses your memory/history. |
+| `~/.local/share/cortexkit/magic-context/models/` | Local embedding model cache (~90 MB `Xenova/all-MiniLM-L6-v2` ONNX), downloaded on first use when local embeddings are enabled | Should persist, else re-downloaded each run. Not used when `memory.enabled: false` or an `openai_compatible`/`ollama` embedding backend is configured. |
+| `${TMPDIR}/opencode/magic-context/magic-context.log` (`pi/` for Pi) | Diagnostic log | Disposable. |
+
+**Sandboxed / ephemeral environments (Docker, CI, disposable containers):** mount the `~/.local/share/cortexkit/magic-context/` directory on a persistent volume so the database and model cache survive between runs. If only the model cache is ephemeral, the model is simply re-downloaded; if the database is ephemeral, memory and history don't accumulate. To avoid the ~90 MB model download entirely, set `memory.enabled: false` or point `embedding` at a remote `openai_compatible`/`ollama` backend.
 
 ---
 
@@ -461,32 +273,21 @@ All durable states live in a local SQLite database. If the database can't be ope
 **Requirements:** [Bun](https://bun.sh) ≥ 1.0
 
 ```sh
-bun install              # Install dependencies
-bun run build            # Build the plugin
-bun run typecheck        # Type-check without emitting
-bun test                 # Run tests
-bun run lint             # Lint (Biome)
-bun run lint:fix         # Lint with auto-fix
-bun run format           # Format (Biome)
-```
-
-**Utility scripts:**
-
-```sh
-bun packages/plugin/scripts/tail-view.ts             # Show post-compartment message tail
-bun packages/plugin/scripts/context-dump/index.ts     # Dump full context state for a session
-bun packages/plugin/scripts/backfill-embeddings.ts   # Backfill missing memory embeddings
+bun install         # Install dependencies
+bun run build       # Build the plugin
+bun run typecheck   # Type-check without emitting
+bun test            # Run tests
+bun run lint        # Lint (Biome)
+bun run format      # Format (Biome)
 ```
 
-Dream execution requires a live OpenCode server — the dreamer creates ephemeral child sessions. Use `/ctx-dream` inside OpenCode for on-demand maintenance.
+Dream execution requires a live OpenCode server (the dreamer creates ephemeral child sessions). Use `/ctx-dream` inside OpenCode for on-demand maintenance.
 
 ---
 
 ## Contributing
 
-Bug reports and pull requests are welcome. For larger changes, open an issue first to discuss the approach.
-
-Run `bun run format` before submitting — CI rejects unformatted code.
+Bug reports and pull requests are welcome. For larger changes, open an issue first to discuss the approach. Run `bun run format` before submitting; CI rejects unformatted code.
 
 ---