Pi Observational Memory (pi-observational-memory)

A Mastra-style Observational Memory (OM) extension for Pi.

This extension completely replaces Pi's legacy, lossy, single-block conversation summarization (/compact) with a transparent, highly-structured, two-layer memory model: Mastra-style Observational Memory + Recall-driven retrieval.

By running an Observer-Reflector agent pipeline, this package allows Pi to prune old, verbose raw message history from the active context while preserving structured observations, current tasks, and continuation guidelines. When precise details are needed, the main agent uses the om_recall tool to fetch raw conversations from a scrollable history index.

---

🧠 Philosophy and the 3-Agent Model

Legacy compaction compresses raw history into a single monolithic block of text, losing timestamps, status signals, temporal connections, and distinct user vs. agent traits. Observational Memory breaks memory down into a distinct psychological subsystem:

1. The Actor (Main Agent): Interacts with the user, performs tool calls, and references the current Observations block. It is only presented with active observations, current-task instructions, suggested-response guidelines, and a trailing window of raw, unobserved messages.
2. The Observer (Extraction Agent): Runs automatically when unobserved messages exceed a token threshold. It converts raw message blocks into chronological, priority-labeled (🔴, 🟡, 🟢, ✅) observations.
3. The Reflector (Consolidation Agent): Runs when the accumulated Observations block exceeds a memory threshold. It reorganizes, cleans up, and condenses older observations into high-density facts, scaling up through 5 instruction levels (0–4) if the output size does not meet the targeted compression ratio.

---

🛠 Features

• No Silent Fallbacks: Observer, Reflector, or model failures throw loud, descriptive errors (Observational Memory Observer failed: ...) rather than failing silently or leaving the context in an ambiguous state.
• Context Injection & Pruning: Injects structured observations, current-task, suggested-response, retrieval guidelines, and a continuation hint into the context. Prunes observed messages from the LLM context automatically to save tokens and avoid redundant text.
• Async Buffering: Extracts observations in the background at regular intervals (every 20% of the threshold) so that when the main threshold is hit, the accumulated memory is swapped/activated instantly with zero LLM-latency overhead.
• Adaptive Thresholds: The active message-observation threshold expands dynamically based on remaining memory capacity in the reflection pool, maximizing raw context usage safely.
• Recall-driven Retrieval: Exposes an om_recall tool to the Actor so it can retrieve full, raw message payloads from observed history when exact code, quotes, or numbers are needed.
• Vector Retrieval: Ranks relevant observations before context injection. Local hash/BOW retrieval is enabled by default; Gemini embeddings (gemini-embedding-001) are available through /om set retrieval gemini.
• Session or Project Scope: Stores memory either per session head or shared project memory via /om set scope session|project.
• Attachment Observation Modes: Supports auto, on, and off with image-only auto mode and size limits to avoid unsafe prompt bloat.
• Duplicate Suppression: Skips exact and near-duplicate observations before appending new memory.
• Custom Compaction Hook: Plugs directly into Pi's session_before_compact lifecycle event. Typing /compact or triggering auto-compaction launches the Observer/Reflector memory consolidation flow instead of Pi's legacy summary compaction.
• TUI Overlay Panel: Fully custom, responsive, multi-tab overlay (/om-memory) in interactive mode for inspecting memory. Features tabbed navigation, smooth scroll, and precise border framing.
• Durable Persistence: Serializes and loads state files safely under .pi/om/sessions/<session-id>.json or .pi/om/projects/project.json using atomic writes and .bak recovery. Outputs JSON-formatted diagnostic logs to .pi/om/debug/ for every operation.
• Secret Redaction: Redacts common API keys, npm/GitHub tokens, bearer tokens, passwords, and secret fields before writing state/debug artifacts or observer text.
• Stale Lock Recovery: Recovers old interrupted OM operation locks automatically so a crashed or killed process does not block future memory runs.
• Bounded Observer Context: Sends only a safe tail of previous observations to the Observer, preventing recursive prompt bloat while preserving full memory in the main runtime.

---

📋 Configuration & Settings

Use /om in Pi to inspect and update runtime settings. Settings are persisted in the OM state file under .pi/om/sessions/<session-id>.json or .pi/om/projects/project.json.

/om
/om set observation-threshold 30000
/om set reflection-threshold 40000
/om set block-after 36000
/om set buffer-tokens 6000
/om set buffer-activation 80%
/om set observation-model google/gemini-2.5-flash
/om set reflection-model google/gemini-2.5-flash
/om set caveman on
/om set attachments auto
/om set scope project
/om set retrieval local
/om set retrieval gemini
/om set retrieval-model gemini-embedding-001
/om set retrieval-top-k 6
/om set retrieval-threshold 12%
/om reset

• Observation Trigger Threshold: default 30,000 raw message tokens.
• Reflection Trigger Threshold: default 40,000 observation tokens.
• Default Models: google/gemini-2.5-flash with 0.3 temperature for Observer, and 0.0 temperature for Reflector.
• Caveman Mode: optional terse compression style for denser memory.
• Attachment Observation Mode: auto observes small images only, on allows supported attachments, and off omits them.
• Scope: session keeps each session isolated; project shares one memory file for the current project.
• Retrieval: local is the default and works offline; gemini uses Gemini embeddings when GEMINI_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY is available; off disables vector retrieval.

---

🕹 Commands

This extension registers the following slash commands in Pi:

• /om — Unified settings/status command. Supports set, reset, enable, disable, observe, reflect, and memory.
• /om-status — Shows a detailed breakdown of pending/observation tokens, active locks, thresholds, and last operation results.
• /om-memory — Opens the interactive multi-tab overlay panel (observations, status stats, and background debug details).
• /om-observe — Forces an immediate Observation pass on all pending raw message history.
• /om-reflect — Forces an immediate Reflection/compression run on all existing observations. Supports optional guidance (e.g. /om-reflect consolidate auth files).
• /om-enable — Enables Observational Memory for the current session.
• /om-disable — Disables Observational Memory (falls back to legacy summarizing).
• /om-compact — Starts the standard Pi compaction pipeline, routed through pi-observational-memory.

---

💻 TUI Overlay Panel Controls

Type /om-memory in Pi's interactive terminal mode to open the fullscreen-ish overlay panel:

• ← / → (Arrow keys) — Switch tabs:
  • Memory: Displays the active Observations list, Current Task, and Suggested Response blocks.
  • Status: Shows live token meters, ratios, and model state.
  • Debug: Lists background buffered chunks, filenames, state paths, and latest errors.
• ↑ / ↓ (Arrow keys) — Scroll content.
• Home / End — Jump to top/bottom of scroll.
• q / Esc — Close overlay and return to chat.

---

🧪 Development and Validation

This package is structured to comply with Pi's strict peer dependency models and TypeScript validation rules.

Check Types and Manifests

Run the typechecker and validation scripts before packaging or releasing:

npm run typecheck
npm run validate
npm test

Commit Guidelines

We enforce Conventional Commits. Ensure all commits use standard prefixes (feat(om):, fix(tui):, refactor(memory):, etc.).

---

📄 License

MIT © Nikita Nosov