Magic Context — Pi extension (mmc)

Cross-session memory and context management for the Pi coding agent. The extension shares its SQLite database with the OpenCode 2 plugin @retaw106/mmc-oc.

This is the moon-magic-context fork of 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

| 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 | | 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 |

Installation

Install the published package with Pi's own installer:

pi install npm:@retaw106/mmc-pi

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.

本 fork 没有上游的 doctor CLI（上游 npx … setup / doctor 在这里不存在）。mmc 各包自带 config-init（生成）与 config-check（只读自检）两个命令，随下一次发版以 npm bin 提供（当前 latest 尚未包含）；命令不映射 doctor/--force，也不新增宿主命令（见 Configuration 节）。

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

mmc reads the Pi host's own config (project overrides user):

1. $cwd/.mmc/mmc.jsonc
2. ~/.pi/agent/mmc.jsonc

Minimal config

{
  "enabled": true,
  "historian": {
    "model": "provider/your-model"
  }
}

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 分发、按子命令分派，裸命令打印帮助、未知子命令被拒绝：

# 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 自身的上下文管理，不会自动启用宿主的原生压缩。

config-check 强制交互式终端；只读所选宿主的用户级配置，不读项目级配置、不检查安装或数据库、不写任何文件。它校验格式、字段值、{env:VAR}/{file:path} 外部引用与 $schema；未知字段警告但不失败；配置缺失视为正常（沿用默认值）。不可读、失效链接、语法错误、字段值错误或外部引用错误 → 退出码 1。退出码：0＝无错误（可有警告），1＝有错误或取消，2＝非交互终端或用法错误。不回显实际配置值。

从本仓源码运行（备选）：构建后直接以 Node 运行入口，例如 node packages/pi-plugin/dist/config-init.js。

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

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 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; mmc never originates this variable from its default. Mixed-version processes on one directory still block migrations until all processes use a compatible build.

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)

Memories are shared across both harnesses for the same project; per-session tagging stays correctly attributed.

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.

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 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 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 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 | | config/ | Fork copy of the plugin config loader (divergences from the shared loader are registered in the monorepo root UPSTREAM.md) |

The OpenCode 2 plugin @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 in the monorepo root.