@connorhatcher/om-pi

Observational Memory extension for pi-coding-agent.

It provides:

• custom session_before_compact summarization powered by @connorhatcher/obversational-memory stateless pipelines
• custom session_before_tree branch summaries
• sync/async auto-compaction trigger flows keyed by mode
• ephemeral memory injection through the context hook (custom message, no system prompt overwrite)
• lightweight status/control commands

Under the hood, compact hooks now use:

• DelegateLLMClient to bridge pi completeSimple callbacks into OM
• mapPiMessagesToOm to convert pi entries into core Message[]
• runCompactionCycle for observer/reflection orchestration

Install

pi install npm:@connorhatcher/om-pi

Commands

• /obs-memory-status shows mode, thresholds, raw-tail estimate, and observer/reflector pipeline counters
• /obs-auto-compact <args> updates auto-compaction settings (keyed or positional)
  • keyed examples: mode=sync enabled=on observer=30k retain=8k
  • positional examples: sync on 30k 8k
• /obs-mode [manual|sync|async] toggles mode (or sets explicitly)
• /obs-view [obs|raw|<maxLines>] shows latest OM-native observations for the current branch
• /obs-reflect queues a forced reflection pass and triggers compaction

Mode behavior:

• manual: no auto compaction trigger; use /obs-reflect (or other manual trigger paths)
• sync: auto trigger at agent_end when thresholds are crossed
• async: enables buffered scheduling/activation paths (including blockAfter safety behavior)

Legacy aliases are still accepted and normalized:

• blocking -> manual
• buffered -> sync

Notes:

• OM context injection uses an ephemeral custom message in context and does not mutate the base system prompt.
• Runtime state is persisted in pi session custom entries and rehydrated on session lifecycle events.
• om-pi reads observations from compaction details.observations and does not parse legacy markdown sections.
• If latest compaction details are missing OM-native observations, om-pi warns and skips injection/view instead of legacy fallback parsing.

Flags

Typical runtime knobs used by this extension are:

• --obs-mode
• --obs-observer-threshold
• --obs-reflector-threshold
• --obs-raw-tail-retain
• --obs-auto-compact
• --obs-debug

If your pi runtime does not expose these flags directly, use the slash commands above.

Local config file

om-pi can read local defaults from .pi/config.json.

Example:

{
  "om-pi": {
    "enabled": true,
    "mode": "sync",
    "observerThreshold": 1000,
    "reflectorThreshold": 1500,
    "rawTailRetain": 8000,
    "debug": true
  }
}

Supported keys in the om-pi (or omPi) section:

• enabled / autoCompact
• mode (manual|sync|async, plus legacy aliases)
• observerThreshold / observer / observation.messageTokens
• reflectorThreshold / reflector / reflection.observationTokens
• rawTailRetain / retain ("off" => 0)
• observation.bufferTokens / observationBufferTokens / obsBufferTokens
• observation.bufferActivation / observationBufferActivation / obsBufferActivation
• observation.blockAfter / observationBlockAfter / obsBlockAfter
• reflection.bufferActivation / reflectionBufferActivation
• reflection.blockAfter / reflectionBlockAfter
• experimentalAsyncBuffering / obsAsyncBuffering
• shareTokenBudget
• debug

Compatibility note:

• When shareTokenBudget=true, om-pi applies a soft fallback to disable async buffering (observation.bufferTokens=false effective) so sessions continue without hard failure.

CLI flags still take precedence over .pi/config.json.

Fallback-Safe Behavior

Hook handlers intentionally return undefined when preconditions are missing or work fails. This lets pi fall back to its default behavior instead of blocking the session flow.

Cases that intentionally fall back:

• no active model
• API key resolution fails
• summarization call errors/aborts

Non-Goals (v1)

• No strict 1:1 command parity with the reference plugin