docs: v0.22.0 release notes

Author: ualtinok

.alfonso/release-notes/v0.22.0.md

@@ -0,0 +1,95 @@
+# v0.22.0 — 🎊Historian v2🎊, a self-tuning history cache, and node:sqlite
+
+This is the **largest release** since Magic Context launched. The history engine has been rebuilt from the ground up, the SQLite backend no longer needs a native module, two recall features are now on by default, and the Pi plugin reaches full behavioral parity with OpenCode.
+
+> **Upgrading an existing session?** Sessions compacted by the old historian keep working, but you'll be prompted once to upgrade them to the new format for better fidelity and cache stability. See [Upgrading](#upgrade) below.
+
+## Headline: Historian v2 and a self-tuning history cache > pure magic...
+
+The old design summarized history into a single flat block and ran a separate LLM "compressor" pass to keep it small. That's gone. The new engine is deterministic, cheaper, and far more cache-friendly.
+
+**Tiered compartments.** Every compartment the historian writes now carries four paraphrase tiers — from a verbose `P1` (treated like "the last 12 hours," kept near-verbatim) down to a `P4` anchor (just enough to recognize and re-find it). The historian also scores each compartment's *importance* as a decay rate: how long this needs to stay in high-fidelity memory.
+
+**Deterministic decay rendering — no more compressor LLM.** Instead of paying a model to re-compress old history, a math function picks the right tier for each compartment on every render, from its age, its importance, and how much history budget you currently have. As a compartment ages or as budget tightens, it gracefully demotes `P1 → P2 → P3 → P4`, oldest-first. When your model's context window is large, history renders richer; when it's tight, it renders leaner — automatically, with zero LLM cost.
+
+**A two-slot history layout that keeps your cache warm.** History now renders into two synthetic message slots:
+
+- **A stable baseline** holding project docs, your user profile, and the decayed compartment history — treated like a frozen prefix that does *not* change on routine turns, so its prompt-cache bytes persist.
+- **A small volatile delta** holding only what's new since the last baseline refresh — new compartments, new memories, and your pinned key files.
+
+The practical effect: on a steady working day, the large stable prefix stays cached until TTL expires or system promopt changes, and only the small delta moves. Fewer surprise cache-misses, much lower cost on long sessions.
+
+**Memory edits no longer bust your cache.** When the agent (or you) edits, archives, or merges a memory mid-session, that change now surfaces as a compact correction in the volatile delta instead of forcing the entire stable baseline to re-render. The agent sees the corrected state immediately; the expensive prefix stays put until the next natural refresh.
+
+## No more native SQLite module
+
+The non-Bun runtimes (Pi on Node, OpenCode Desktop on Electron) used to depend on `better-sqlite3` — a native module that needed a per-platform prebuild and, on Desktop, a runtime binary download with an ABI probe. That whole path is gone. Magic Context now uses the built-in `node:sqlite` on Node and Electron, and `bun:sqlite` under Bun.
+
+No native module, no prebuild, no download, nothing to go wrong on install. If you ever hit `better_sqlite3.node` load failures or Electron ABI mismatches, those are eliminated.
+
+## Two recall features now on by default
+
+Both were previously opt-in experiments and are now stable and **on by default**. Each can be turned off independently.
+
+- **Temporal awareness** — the agent sees elapsed-time markers (e.g. `+2h 15m`) between messages and dated compartments, so it understands *when* things happened. Opt out with `temporal_awareness: { enabled: false }`.
+- **Auto-search hints** — each turn, a background `ctx_search` quietly whispers a compact "vague recall" when something relevant exists in your memories, past conversation, or git history. No full content is injected — just a nudge to look. Opt out with `memory: { auto_search: { enabled: false } }`.
+
+## Experimental config graduated
+
+The `experimental.*` namespace is retired. Settings moved to stable homes, and `doctor` migrates your existing config automatically (your opt-ins and opt-outs are preserved):
+
+| Old | New | Default |
+|---|---|---|
+| `experimental.temporal_awareness` | `temporal_awareness` | **on** |
+| `experimental.auto_search` | `memory.auto_search` | **on** |
+| `experimental.git_commit_indexing` | `memory.git_commit_indexing` | off |
+| `experimental.caveman_text_compression` | `caveman_text_compression` | off |
+
+## Collapsible sidebar
+
+The TUI sidebar can now be collapsed (click the header). Collapsed, it keeps the context progress bar plus three compact summary lines — Historian state, Memories, and Status (compartment / queued-op / note counts) — for a glanceable view that takes minimal vertical space.
+
+## Pi reaches full parity with OpenCode
+
+The Pi plugin went through an extensive parity sweep and now mirrors OpenCode's behavior across the board: the two-slot history layout, deterministic decay rendering, memory supersede-delta, the upgrade flow, detached (non-blocking) recomp/upgrade, model-fallback chains, and stable message-identity handling. A tracked `PARITY.md` now documents every *intentional* difference between the two harnesses so they don't drift.
+
+## Performance
+
+- **Transform hot path.** A per-pass work-metrics computation was scanning the full assistant-message history on every turn; on large sessions that alone cost ~250ms per pass. It's now lazy and incremental — computed only when the sidebar asks for it. On a large session the post-transform phase dropped from ~240ms to a few milliseconds.
+- **Dashboard.** Database and filesystem reads moved off the UI thread, the project dropdown is cached for instant History re-entry, and the session list no longer scans the full message table just to show a count. Navigating the dashboard is now snappy even on large databases.
+- **Tunable SQLite.** New optional `sqlite.cache_size_mb` and `sqlite.mmap_size_mb` knobs, plus a periodic `PRAGMA optimize`.
+
+## Dashboard
+
+- Compartment view upgraded to the v2 model — per-tier (`P1`–`P4`) inspection, importance, and episode-type badges.
+- New expandable **Memory Changes** drill-down on dreamer runs — see exactly which memories were written, archived, or merged.
+- Token breakdown corrected to measure the actual injected bytes (Docs and User Profile are now their own categories).
+
+## Security and correctness hardening
+
+This release folded in a large multi-round audit sweep across both harnesses and the dashboard. Highlights:
+
+- **Memory config bypass fixed** — disabling the memory store no longer leaks memories into the prompt via a fallback path.
+- **Local RPC server now requires a per-process bearer token** and drops wildcard CORS, so a stray local process can't drive the side-effecting endpoints.
+- **Resumed-session project resolution** — note nudges and auto-search now resolve the *session's* project, not the launch directory, so `opencode -s` from another repo behaves correctly.
+- More than 50 additional bugfixes across the plugin, Pi, and dashboard — migration collision handling, the upgrade flow, key-file selection, dashboard memory editing, and many more.
+
+## Upgrade
+
+This release adds database migrations that apply automatically on first start. Your data is migrated in place.
+
+```bash
+# OpenCode
+npx @cortexkit/magic-context@latest doctor
+
+# Pi (requires Pi >= 0.74)
+npx @cortexkit/magic-context@latest setup --harness pi
+```
+
+**Upgrading old compartments.** Sessions that were compacted by the previous historian remain fully usable, but their compartments are in the old flat format. When you open such a session you'll be prompted once to upgrade it — this reprocesses its history with the new historian into the tiered format (it can take a while on large sessions, and runs without blocking your work). You can also trigger it manually:
+
+```
+/ctx-session-upgrade
+```
+
+Upgrading is optional but recommended — un-upgraded sessions render in a degraded single-tier mode.