@hheei/hepi-mctx

Cross-session memory and context management for Pi coding agent.

Requires @earendil-works/pi-coding-agent and @earendil-works/pi-tui >= 0.74.0.

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 ctx_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 | | Dreamer | Scheduled background subagent that consolidates, verifies, archives, and improves stored memories | | /ctx-aug | On-demand sidekick that augments the next turn with relevant memories | | Auto-search hint | When user prompts mention previously-discussed topics, appends a compact memory hint | | Note nudges | Surface deferred intentions at natural work boundaries (commit, todo completion, historian publication) |

Installation

Install the Pi extension directly:

pi install npm:@hheei/hepi-mctx

This adds the extension to ~/.pi/agent/settings.json. Configure it with magic-context.jsonc as described below.

When @hheei/hepi-subagents creates a child session, Magic Context registers only read-only ctx_search. It does not start its context pipeline, historian, Dreamer, status line, session commands, or write-capable tools in that child. With inherit_context: true, an eligible parent contributes its cached MCTX compartment history plus only the branch tail after that cache's compartment boundary. Parent project docs, profile, memory, and mural blocks are not copied into the child; ctx_search remains its explicit read path. Without a valid MCTX cache, Subagents uses its normal parent-branch inheritance.

Magic Context runs its historian, sidekick, Dreamer, recomp, wrapup, and upgrade tasks through the in-memory @hheei/hepi-subagents execution profile. They do not spawn a second Pi process. Each task receives an explicit tool allowlist; Dreamer receives ctx_memory only through an explicit capability.

Configuration

Magic Context reads two config files (in this priority order):

1. $cwd/.pi/magic-context.jsonc (project-level overrides)
2. ~/.pi/agent/magic-context.jsonc (user-level defaults)

Both are merged through a Zod schema. Invalid fields fall back to defaults — bad config never disables the plugin entirely.

Minimal config

{
  "$schema": "https://raw.githubusercontent.com/cortexkit/magic-context/master/assets/magic-context.schema.json",
  "enabled": true,
  "historian": {
    "model": "anthropic/claude-haiku-4-5"
  },
  "embedding": {
    "provider": "auto"
  }
}

embedding.provider: "auto" is the default. It uses the shared Synapse embedding lane when a configured subc.connection_file or the standard local runtime connection file is available; otherwise it uses the local model without warning. Set "local" to always use the in-process model, or "synapse" to require the daemon lane with an explicit fallback provider.

When several Pi processes run at once, prefer "auto" with a working Synapse lane. A local embedding model is shared across projects within one Pi process, but each separate Pi process needs its own model runtime.

For the full configuration reference (including dreamer, sidekick, auto-search, and experimental features), see CONFIGURATION.md in the main repository — the schema is shared between both plugins.

Slash commands

All commands trigger triggerTurn: false (never sent to the LLM):

| Command | What it does | |---|---| | /ctx-status | Live token breakdown + queued ops + cache state | | /ctx-flush | Force-process pending ops queue | | /ctx-recomp | Rebuild compartments from raw history (heavy operation) | | /ctx-wrapup [messages_to_keep] | Compact older live history while keeping the newest N messages raw | | /ctx-dream | Trigger a dream run on demand | | /ctx-aug | Augment your next prompt with sidekick-retrieved memories |

When @hheei/hepi-basics is also installed, /handoff uses Magic Context's historian and ctx_reduce replay to seed a new child Pi session. Structured compartments migrate to the destination session, while the reduced protected tail is injected as the handoff message. The destination's normal context hook then materializes m[0]/m[1] from its own state. Without historian.model, the handoff still preserves the reduced tail and migrated compartments; it does not fall back to native Pi compaction.

Storage

Magic Context stores everything in a SQLite database at:

~/.local/share/cortexkit/magic-context/context.db

Tables are scoped by the resolved project path, keeping memories, embeddings, and dreamer runs independent between projects.

SQLite page cache defaults to 32 MiB per Pi process. Set sqlite.cache_size_mb in Magic Context configuration when a single large workspace benefits from a larger cache.

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.

Tools available to the agent

| Tool | Action set | Purpose | |---|---|---| | ctx_search | n/a | Search memories + raw session history; returns ranked results with previews | | ctx_memory | write, delete | Manage project memories explicitly (most writes happen via dreamer instead) | | ctx_note | read, write, update, dismiss | Defer intentions for later — surfaced via note nudges at work boundaries |

ctx_expand reads tagged session history. ctx_reduce marks processed content for later compaction without deleting it immediately.

Implementation

The Pi extension lives in packages/pi-plugin; its shared context, memory, compaction, and historian logic lives under packages/plugin/src in this same repository.

| Pi-specific module | Responsibility | |---|---| | context-handler.ts | Pi pi.on("context", ...) adapter — tags, drops, runs nudges and auto-search | | subagent-runner.ts | Spawns pi --print --mode json --no-session ... for historian/sidekick/dreamer subagents, keeps extension discovery on for provider/AFT extensions, sets MAGIC_CONTEXT_PI_SUBAGENT=1 so the full Magic Context entry no-ops, and applies a per-agent --tools/--no-tools allow-list plus a 2-second terminal drain | | tools/ | Pi pi.registerTool wrappers around the shared tool implementations | | commands/ | Pi pi.registerCommand wrappers for the five /ctx-* slash commands | | dreamer/ | Pi-side adapter for the shared dreamer scheduler | | system-prompt.ts | Pi before_agent_start injector for <session-history>, <project-memory>, <project-docs> | | config/ | Pi-convention config loader ($cwd/.pi/magic-context.jsonc + ~/.pi/agent/magic-context.jsonc) |

License

MIT — see LICENSE.