@retaw106/mmc-pi 1.2.2 → 2.0.0

package/README.md

@@ -1,21 +1,21 @@
-# Magic Context — Pi / OMP extension
+# Magic Context — Pi extension (mmc)
 
-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).
+Cross-session memory and context management for the [Pi coding agent](https://github.com/earendil-works/pi-mono). The extension shares its SQLite database with the OpenCode 2 plugin [`@retaw106/mmc-oc`](https://www.npmjs.com/package/@retaw106/mmc-oc).
 
-Requires Pi `>= 0.74.0` or OMP `>= 17.1.7`.
+This is the `moon-magic-context` fork of [magic-context](https://github.com/cortexkit/magic-context): the core transform pipeline, historian, and FTS5 memory retrieval only. The upstream embedding/semantic-search stack, dashboard, CLI, and OMP support are not part of this fork.
+
+Requires `@earendil-works/pi-coding-agent` `>= 0.80.2`.
 
 ---
 
 ## 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 |
+| **`m[0]`/`m[1]` history injection** | Renders compressed history and project memories into two synthetic leading messages every turn so the agent never loses context — without busting the provider's prompt cache on stable turns |
+| **Project memories** | Persistent cross-session knowledge store with FTS5 full-text 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 |
 
@@ -23,90 +23,58 @@ Magic Context is a context engine that keeps long Pi sessions productive by:
 
 ## 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:
+Install the published package with 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:
+This adds the extension to `~/.pi/agent/settings.json`. Then create the config at `~/.pi/agent/mmc.jsonc` (see Configuration below) — hand-write it, or run the package's interactive `config-init` command (below). The historian model is required, or no summarization ever happens.
 
-```bash
-npx @retaw106/mmc-oc@latest doctor --harness omp
-```
+> 本 fork 没有上游的 `doctor` CLI（上游 `npx … setup` / `doctor` 在这里不存在）。mmc 各包自带 `config-init`（生成）与 `config-check`（只读自检）两个命令，随下一次发版以 npm bin 提供（当前 `latest` 尚未包含）；命令不映射 `doctor`/`--force`，也不新增宿主命令（见 Configuration 节）。
 
-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.
+To build from the monorepo instead (requires Bun `>= 1.4.0`): point Pi's `packages` array at `packages/pi-plugin` and run `bun run build` before starting Pi — the host loads the prebuilt `dist`.
 
 ---
 
 ## Configuration
 
-Magic Context reads the Pi host's own config (project overrides user):
+mmc 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"
+    "model": "provider/your-model"
   }
 }
 ```
 
-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.
+`historian.model` is required (no default) and takes a `provider/model` ID; optional `fallback_models`, and Pi reads `thinking_level` (OpenCode reads `variant`). Replace the placeholder with a model available in your host.
+
+For the full configuration reference, see `docs/guides/配置说明.md` in the monorepo — OpenCode and Pi share the same schema (`assets/magic-context.schema.json`, regenerated by the plugin build).
+
+### 生成与自检用户级配置（交互命令）
+
+两包各带两个交互命令，**随下一次发版以 npm bin 提供**（当前 `latest` 尚未包含）；以单一 bin 分发、按子命令分派，裸命令打印帮助、未知子命令被拒绝：
+
+```sh
+# Pi（本包）
+npx @retaw106/mmc-pi@latest config-init    # 生成首份用户级配置
+npx @retaw106/mmc-pi@latest config-check   # 只读自检（不写文件）
+# OpenCode 2 侧的同一组命令在 @retaw106/mmc-oc 包内，用法相同
+```
+
+两个命令都**交互选择目标宿主**（OpenCode / Pi），只作用于所选宿主的**用户级**配置。`config-init` 按既有规则解析用户配置路径（Pi 固定 `~/.pi/agent/`），若目标已存在 `.jsonc`/`.json` 则提示退出、不改动已有文件。逐项询问语言、historian 主模型、`maintenance.enabled`、`compaction.enabled`、全局 `cache_ttl`、全局 `execute_threshold_percentage`：每项均可留空（不写入该项）。其中 historian 主模型留空即不配置历史摘要模型（摘要需之后配置模型才会启用）；其余项留空沿用插件默认。只写显式设置项，产出带注释的精简 JSONC，预览确认后落盘；只涉及主模型，不含回退模型、reasoning、按模型映射或绝对 token 阈值。纯离线：不读凭据、不探测模型可调用性。`compaction.enabled=false` 只关闭 mmc 自身的上下文管理，**不会**自动启用宿主的原生压缩。
 
-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.
+`config-check` 强制交互式终端；只读所选宿主的用户级配置，不读项目级配置、不检查安装或数据库、不写任何文件。它校验格式、字段值、`{env:VAR}`/`{file:path}` 外部引用与 `$schema`；未知字段**警告但不失败**；配置缺失视为正常（沿用默认值）。不可读、失效链接、语法错误、字段值错误或外部引用错误 → 退出码 1。退出码：`0`＝无错误（可有警告），`1`＝有错误或取消，`2`＝非交互终端或用法错误。**不回显实际配置值。**
+
+从本仓源码运行（备选）：构建后直接以 Node 运行入口，例如 `node packages/pi-plugin/dist/config-init.js`。
 
 ---
 
@@ -125,42 +93,27 @@ All commands trigger `triggerTurn: false` (never sent to the LLM):
 
 ## Storage
 
-Magic Context stores everything in a single shared SQLite database at:
+mmc 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
+`MMC_STORAGE_DIR` to the absolute, complete shared mmc
 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.
-
----
+propagate one identical value to every process that shares the database; mmc
+never originates this variable from its default.
+Mixed-version processes on one directory still block migrations until all processes use a compatible build.
 
-## Cross-harness coherence
+This is the **same database** the OpenCode 2 plugin uses. Tables are scoped by:
+- `harness` column (`'pi'` or `'opencode2'`; legacy rows may carry `'opencode'`) for session-scoped data
+- `project_path` (resolved git root) for project-scoped data (memories)
 
-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:
+Memories are shared across both harnesses for the same project; per-session tagging stays correctly attributed.
 
-```
-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.
+Storage failures are fatal — mmc will refuse to register hooks rather than run with ephemeral state, since that would let context grow unbounded across restarts.
 
 ---
 
@@ -174,29 +127,27 @@ Configure `embedding` once in the shared `~/.config/mmc/mmc.jsonc`; OpenCode, Pi
 | `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.
+`mmc_note`, `mmc_expand`, and `mmc_reduce` are session-scoped and are exposed in primary Pi sessions. mmc 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:
+This package is part of the moon-magic-context monorepo (`packages/pi-plugin`). Pi shares the adapter layer and core implementation with the OpenCode 2 plugin:
 
 | 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 |
+| `subagent-runner.ts` | Re-invokes the Pi host with `--print --mode json --no-session` for hidden child sessions, with 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.
+| `system-prompt.ts` | Pi `before_agent_start` injector for the `## Magic Context` guidance block and sticky date |
+| `config/` | Fork copy of the plugin config loader (divergences from the shared loader are registered in the monorepo root `UPSTREAM.md`) |
 
-For deeper architectural detail, see the main repo's [ARCHITECTURE.md](https://github.com/cortexkit/magic-context/blob/master/ARCHITECTURE.md).
+The OpenCode 2 plugin [`@retaw106/mmc-oc`](https://www.npmjs.com/package/@retaw106/mmc-oc) lives in the same monorepo (`packages/plugin`). For deeper architectural detail, see `ARCHITECTURE.md` in the monorepo root.
 
 ---
 
 ## License
 
-MIT — see [LICENSE](https://github.com/cortexkit/magic-context/blob/master/LICENSE).
+MIT — see `LICENSE` in the monorepo root.