@retaw106/mmc-pi 0.0.0-stage → 1.2.2

package/README.md

@@ -1,3 +1,202 @@
-# Temporary Holding Version
+# Magic Context — Pi / OMP extension
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Cross-session memory and context management for [Pi coding agent](https://github.com/earendil-works/pi-mono) and [Oh My Pi (OMP)](https://github.com/can1357/oh-my-pi). The same extension package runs on both hosts and shares its SQLite database with the [OpenCode plugin](https://www.npmjs.com/package/@cortexkit/opencode-magic-context).
+
+Requires Pi `>= 0.74.0` or OMP `>= 17.1.7`.
+
+---
+
+## What it does
+
+Magic Context is a context engine that keeps long Pi sessions productive by:
+
+| Feature | What it does |
+|---|---|
+| **Tagging + drops** | Tags every assistant/user/tool message with `§N§ ` so you can drop specific turns later via `mmc_reduce` |
+| **Historian** | Background subagent compresses old conversation into compartments + facts at threshold pressure or commit boundaries |
+| **`<session-history>` injection** | Prepends compressed history into the system prompt every turn so the agent never loses context |
+| **Project memories** | Persistent cross-session knowledge store with embedding-based semantic search |
+| **Auto-search hint** | When user prompts mention previously-discussed topics, appends a compact memory hint |
+| **Cross-harness sharing** | Memories written from OpenCode appear in Pi (and vice versa) for the same project |
+
+---
+
+## Installation
+
+The fastest path is the unified Magic Context CLI — `--harness pi` selects the Pi-specific setup pipeline (registers the extension with Pi, writes a sensible `mmc.jsonc`, and verifies your model picks):
+
+```bash
+npx @retaw106/mmc-oc@latest setup --harness pi
+```
+
+This handles everything for you:
+1. Adds `npm:@retaw106/mmc-pi` to Pi's `packages` array in `~/.pi/agent/settings.json` (the same place `pi install` writes to)
+2. Creates `~/.pi/agent/mmc.jsonc` with defaults
+3. Prompts you for historian and embedding model choices
+4. Warns about provider-specific gotchas (e.g. GitHub Copilot reasoning models need an explicit `thinking_level`)
+
+If you'd rather register the Pi extension package directly with Pi (skipping the wizard), use Pi's own installer:
+
+```bash
+pi install npm:@retaw106/mmc-pi
+```
+
+This adds the extension to `~/.pi/agent/settings.json` but won't write `mmc.jsonc` for you — create it manually at `~/.pi/agent/mmc.jsonc` (see Configuration below).
+
+To check installation health later:
+
+```bash
+npx @retaw106/mmc-oc@latest doctor --harness pi
+```
+
+### Oh My Pi (OMP)
+
+Use the OMP-specific setup path. It installs the package through OMP's plugin manager, disables OMP native compaction and automatic memory to prevent duplicate context managers, and verifies the effective project plugin state:
+
+```bash
+npx @retaw106/mmc-oc@latest setup --harness omp
+```
+
+Manual installation is also supported:
+
+```bash
+omp plugin install @retaw106/mmc-pi
+omp config set compaction.enabled false
+omp config set memory.backend off
+```
+
+Verify with:
+
+```bash
+npx @retaw106/mmc-oc@latest doctor --harness omp
+```
+
+OMP's legacy Pi loader maps `@earendil-works/*` imports to its bundled `@oh-my-pi/*` runtime. Magic Context identifies OMP from `@oh-my-pi/pi-utils`'s in-process `APP_NAME` through the running host's module graph, not from an executable basename, so compiled and symlinked launches behave the same. It also re-invokes the current host executable for historian and dreamer children, so OMP children remain OMP processes.
+
+---
+
+## Configuration
+
+Magic Context reads the Pi host's own config (project overrides user):
+
+1. `$cwd/.mmc/mmc.jsonc`
+2. `~/.pi/agent/mmc.jsonc`
+
+Session discovery follows the active host. Relative `pi.subagent_extensions` are deliberately isolated by host: plain Pi resolves them from `~/.pi/agent`, while a positively identified OMP process uses `PI_CODING_AGENT_DIR` when set and otherwise derives the active `~/.omp` config/profile agent directory.
+
+### Minimal config
+
+```jsonc
+{
+  "$schema": "https://raw.githubusercontent.com/cortexkit/magic-context/master/assets/magic-context.schema.json",
+  "enabled": true,
+  "historian": {
+    "pi": {
+      "model": "anthropic/claude-haiku-4-5"
+    },
+    "omp": {
+      "model": { "model": "opencode/claude-haiku-4-5", "thinking_level": "auto" }
+    }
+  },
+  "embedding": {
+    "provider": "local"
+  }
+}
+```
+
+OMP uses `historian.omp ?? historian.pi`; leaving the OMP block absent preserves existing Pi-compatible configuration. OMP supports `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `inherit`, and `auto` thinking levels.
+
+For the full configuration reference (including auto-search and experimental features), see [CONFIGURATION.md](https://github.com/cortexkit/magic-context/blob/master/CONFIGURATION.md) in the main repository — OpenCode, Pi, and OMP share the same schema.
+
+---
+
+## Slash commands
+
+All commands trigger `triggerTurn: false` (never sent to the LLM):
+
+| Command | What it does |
+|---|---|
+| `/mmc-status` | Live token breakdown + queued ops + cache state |
+| `/mmc-flush` | Force-process pending ops queue |
+| `/mmc-recomp` | Rebuild compartments from raw history (heavy operation) |
+| `/mmc-wrapup [messages_to_keep]` | Compact older live history while keeping the newest N messages raw |
+
+---
+
+## Storage
+
+Magic Context stores everything in a single shared SQLite database at:
+
+```
+~/.local/share/mmc/context.db
+```
+
+When a host isolates `XDG_DATA_HOME` per process, set
+`MMC_STORAGE_DIR` to the absolute, complete shared Magic Context
+storage directory. The explicit path takes precedence over the XDG-derived path
+and does not change Pi's own configuration or session directories. The host must
+propagate one identical value to every process that shares the database; Magic
+Context never originates this variable from its default. This affects the
+harness-side database only, not `subc` daemon state. Mixed-version processes on
+one directory still block migrations until all processes use a compatible build.
+
+This is the **same database** the OpenCode plugin and OMP extension use. Tables are scoped by:
+- `harness` column (`'pi'` or `'opencode'`) for session-scoped data; OMP intentionally uses `'pi'`
+- `project_path` (resolved git root) for project-scoped data (memories, embeddings)
+
+Memories are shared across all three harnesses for the same project; per-session tagging stays correctly attributed.
+
+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.
+
+---
+
+## Cross-harness coherence
+
+For semantic search to work across harnesses, every host must use the **same embedding model**. Magic Context detects a mismatch on Pi or OMP startup and warns:
+
+```
+WARN embedding model mismatch detected for project ...:
+stored vectors use "openai-compatible:Qwen/Qwen3-Embedding-8B" but Pi is configured with "local:Xenova/all-MiniLM-L6-v2".
+Cross-harness search will return zero results until vectors are re-embedded.
+```
+
+Configure `embedding` once in the shared `~/.config/mmc/mmc.jsonc`; OpenCode, Pi, and OMP all read it. Use `$cwd/.mmc/mmc.jsonc` only when that project intentionally needs an override.
+
+---
+
+## Tools available to the agent
+
+| Tool | Action set | Purpose |
+|---|---|---|
+| `mmc_search` | n/a | Search memories + raw session history; returns ranked results with previews |
+| `mmc_memory` | `write`, `delete` | Manage project memories explicitly |
+| `mmc_note` | `read`, `write`, `update`, `dismiss` | Defer intentions for later — listed in the glance on demand |
+| `mmc_expand` | `start`/`end`, `message`, `verbose` | Recover complete messages or expand a compressed conversation range |
+| `mmc_reduce` | `drop` | Queue tagged turns for cache-safe removal from the live context |
+
+`mmc_note`, `mmc_expand`, and `mmc_reduce` are session-scoped and are exposed in primary Pi/OMP sessions. Magic Context omits them from ephemeral `--no-session` child processes, where they would otherwise target the hidden child session; `mmc_reduce` is additionally omitted when compaction is disabled.
+
+---
+
+## Architecture & implementation
+
+This package is part of the [magic-context monorepo](https://github.com/cortexkit/magic-context). Pi and OMP share the same adapter layer and core implementation:
+
+| Pi-specific module | Responsibility |
+|---|---|
+| `context-handler.ts` | Pi `pi.on("context", ...)` adapter — tags, drops, runs nudges and auto-search |
+| `subagent-runner.ts` | Re-invokes the current Pi/OMP host with `--print --mode json --no-session`; resolves relative allowlisted extensions from plain Pi's `~/.pi/agent` or an identified OMP host's active agent directory; and applies per-agent tool isolation |
+| `tools/` | Pi `pi.registerTool` wrappers around the shared tool implementations |
+| `commands/` | Pi `pi.registerCommand` wrappers for the four `/mmc-*` slash commands |
+| `system-prompt.ts` | Pi `before_agent_start` injector for the `## Magic Context` guidance block and sticky date (v2 never emits data blocks such as `<project-docs>`/`<user-profile>`/`<key-files>`) |
+| `config/` | Shared MMC config loader with legacy Pi migration fallback |
+
+The unified [`@retaw106/mmc-oc`](https://www.npmjs.com/package/@retaw106%2Fmmc-oc) CLI exposes separate `pi` and `omp` setup/doctor pipelines while both use this runtime adapter.
+
+For deeper architectural detail, see the main repo's [ARCHITECTURE.md](https://github.com/cortexkit/magic-context/blob/master/ARCHITECTURE.md).
+
+---
+
+## License
+
+MIT — see [LICENSE](https://github.com/cortexkit/magic-context/blob/master/LICENSE).

package/dist/historian-calibration-extension.js

@@ -0,0 +1,62 @@
+// src/historian-calibration-extension.ts
+var HISTORIAN_TEMPERATURE_ENV = "MMC_HISTORIAN_TEMPERATURE";
+var HISTORIAN_MAX_OUTPUT_TOKENS_ENV = "MMC_HISTORIAN_MAX_OUTPUT_TOKENS";
+function finiteNumber(value) {
+  if (value === undefined || value.trim().length === 0)
+    return;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
+}
+function calibrateHistorianProviderPayload(payload, temperature, maxOutputTokens) {
+  if (typeof payload !== "object" || payload === null || Array.isArray(payload))
+    return payload;
+  if (temperature === undefined && maxOutputTokens === undefined)
+    return payload;
+  const calibrated = { ...payload };
+  const generationConfig = calibrated.generationConfig;
+  if (typeof generationConfig === "object" && generationConfig !== null && !Array.isArray(generationConfig)) {
+    calibrated.generationConfig = {
+      ...generationConfig,
+      ...temperature !== undefined ? { temperature } : {},
+      ...maxOutputTokens !== undefined ? { maxOutputTokens } : {}
+    };
+    return calibrated;
+  }
+  const inferenceConfig = calibrated.inferenceConfig;
+  if (typeof inferenceConfig === "object" && inferenceConfig !== null && !Array.isArray(inferenceConfig)) {
+    calibrated.inferenceConfig = {
+      ...inferenceConfig,
+      ...temperature !== undefined ? { temperature } : {},
+      ...maxOutputTokens !== undefined ? { maxTokens: maxOutputTokens } : {}
+    };
+    return calibrated;
+  }
+  if (temperature !== undefined) {
+    calibrated.temperature = temperature;
+  }
+  if (maxOutputTokens !== undefined) {
+    if ("max_output_tokens" in calibrated) {
+      calibrated.max_output_tokens = maxOutputTokens;
+    } else if ("max_completion_tokens" in calibrated) {
+      calibrated.max_completion_tokens = maxOutputTokens;
+    } else if ("max_tokens" in calibrated) {
+      calibrated.max_tokens = maxOutputTokens;
+    } else if ("maxTokens" in calibrated) {
+      calibrated.maxTokens = maxOutputTokens;
+    }
+  }
+  return calibrated;
+}
+function historianCalibrationExtension(pi) {
+  const temperature = finiteNumber(process.env[HISTORIAN_TEMPERATURE_ENV]);
+  const maxOutputTokens = finiteNumber(process.env[HISTORIAN_MAX_OUTPUT_TOKENS_ENV]);
+  if (temperature === undefined && maxOutputTokens === undefined)
+    return;
+  pi.on("before_provider_request", (event) => calibrateHistorianProviderPayload(event.payload, temperature, maxOutputTokens));
+}
+export {
+  HISTORIAN_MAX_OUTPUT_TOKENS_ENV,
+  HISTORIAN_TEMPERATURE_ENV,
+  calibrateHistorianProviderPayload,
+  historianCalibrationExtension as default
+};