pi-mcb

pi-mcb is an extension for the Pi AI coding agent. MCB stands for Memory and Compaction Bridge. The extension acts as a unified bridge between two distinct processes: deterministic context compaction (which trims conversation history) and observational memory (which retains durable facts and reflections). By bridging these together, it ensures the agent maintains long-term memory while keeping active context windows fast and lean.

pi-mcb combines two complementary long-session features behind one compaction hook:

• Deterministic structural compaction: creates a fast, zero-LLM summary of goals, changes, commits, blockers, preferences, and the recent transcript.
• Observational memory: background Observer, Reflector, and Dropper workers preserve timestamped facts and durable reflections across compactions.
• Unified recall: the agent can retrieve memory evidence, search prior session history, expand entries, and inspect file content.

The extension owns the compaction hook and emits one summary containing both the structural recap and memory projection. This avoids the competing session_before_compact hooks that occur when standalone compaction and observational-memory extensions are installed together.

Install

# From this checkout
pi install npm:pi-mcb

Do not load pi-blackhole, pi-observational-memory, or another compaction extension alongside pi-mcb. They can each register compaction hooks and/or a recall tool. pi-mcb warns when it detects one, but cannot safely resolve the conflict for you. Remove them, then restart Pi or run /reload from active session.

For updating the extension when a new release is available you can do

pi update npm:pi-mcb

and removing it can be done using

pi remove npm:pi-mcb

Commands

| Command | Purpose | | --- | --- | | /mcb | Run deterministic compaction. Optional trailing text becomes a follow-up prompt. | | /mcb status / /mcb help | Show current mode or the compact command guide. | | /mcb settings | Open the settings overlay. | | /mcb om-on / /mcb om-off | Enable or disable background observational memory. | | /mcb cleanup | Remove orphaned manual-mode pending files. | | /mcb-memory [view|full] [page:N] [copy] | Show pipeline status or inspect paginated visible/full memory; copying is explicit. | | /mcb-recall <query> [send] | Search history locally. Append send only when results should enter agent context and trigger a turn. |

The agent-facing recall tool accepts a memory id, #N entry expansion, #N:path file drill-down, plain text/regex search, mode:file, mode:touched, mode:semantic (via local dense vector embeddings), and scope:all.

Configuration

On first interactive load, pi-mcb offers safe presets (recommended Pi-visible tail, aggressive tail, or compaction-only) and then creates:

~/.pi/agent/pi-mcb/pi-mcb-config.json

You can easily edit most of these configuration options—including your base, observer, reflector, and dropper model strings—directly inside Pi using the interactive TUI Settings Menu by running /mcb settings.

Useful defaults:

{
  "compaction": "auto",
  "compactionEngine": "mcb",
  "tailBehavior": "minimal",
  "memory": true,
  "observeAfterTokens": 15000,
  "reflectAfterTokens": 25000,
  "compactAfterTokens": 81000
}

• compaction: auto, manual, or off.
• compactionEngine: mcb uses the deterministic summary; pi-default leaves normal Pi compaction in charge.
• memory: independently enables the Observer/Reflector/Dropper layer.
• semanticRecall: (opt-in) enables local vector embeddings for conceptual memory search (requires manually installing @huggingface/transformers).
• Per-worker model overrides, fallback chains, cooldowns, input budgets, and environment overrides are available in CONFIG.md.

Design

Compaction itself never calls a model. Memory workers run before compaction, when their token clocks are due. At compaction, pi-mcb renders the prepared observations/reflections and appends them to the deterministic summary. Failed worker models fall through their configured fallback chain and use a persisted cooldown to avoid repeated failures.

Manual mode stores pending worker results per session and flushes them when /mcb is run.

Credits and License

This project is a renamed, independently packaged derivative of pi-blackhole, which already unified pi-vcc and pi-observational-memory. Their MIT-licensed work provides the compaction, observational-memory, and recall foundations. See LICENSE.