pi-mm: Intelligent Persistent Memory for Pi Coding Agent

Multi-resolution persistent memory for the Pi Coding Agent powered by native C engines (libcorm, libsepal, liblemma).

pi-mm gives your Pi Coding Agent long-term memory that survives context compaction and cross-session restarts. It automatically injects relevant prior technical decisions into context before each turn and captures new learnings when tasks conclude—with zero manual configuration.

1. Quickstart: Zero-Configuration Bring-Up

Install the extension:

pi install npm:@tty-pt/pi-mm

pi-mm works out of the box:

1. Automatic Daemon Startup: Checks if axil-auren is running on port 4242. If offline, it brings up the local server automatically.
2. Automatic Model Provisioning: Discovers models in ~/.models/ and auto-downloads the required fast embedding model (bge-base, 117 MB) with sha256 verification. Heavy and unused inference/chat models are never downloaded. Shows non-blocking visual progress (⬇ bge-base (42%)) and usage status (⚡ bge-base) in the status bar (mm-judge).
3. Proactive Dependency Checks: On session_start, pi-mm automatically checks core C engines (libcorm, libsepal, liblemma, libjoint, axil, axil-auren) and displays actionable remediation toasts if anything is missing.

Verify Memory Health

Inside Pi, run:

/mm doctor

Outputs live endpoint connectivity, latency, loaded models, storage footprint, and core C engine versions.

2. Agent Tools Reference

By default, pi-mm exposes 3 focused tools to keep the agent's context clean and avoid tool ambiguity:

| Tool | Parameters | Description | | :--- | :--- | :--- | | memory_recall | query, overview, zoomRef, project, level, includeEvidence | Multi-resolution retrieval: search semantically, generate all-time timeline overviews (overview: true), or zoom vertically into a specific investigation (zoomRef: 42). | | memory_record | problem, approaches, diffs, findings, outcome, verification | Explicitly records an episode, bug fix, or project invariant with verified test commands. | | memory_review | ref, action, lifecycle, reason, evidenceRef | Inspects memory evidence hierarchy (action: "inspect") or transitions factual lifecycle status (action: "update_lifecycle"). |

Advanced fine-grained tools (memory_store, memory_scan, memory_think, memory_forget, etc.) can be enabled via "advancedTools": true.

3. Diagnostic & Timeline Commands

| Command | Description | | :--- | :--- | | /mm doctor | Displays live status for decision judge, vector endpoints, storage file sizes, and core C engines. | | /mm overview | Synthesizes an all-time structured timeline across active principles (L3), invariants (L2), and milestones (L1). | | /mm timeline | Chronological grouping of memory capture epochs and historical activity. |

4. Configuration Reference

Configure settings in .pi/settings.json (or user ~/.pi/agent/settings.json):

| Option | Default | Description | | :--- | :--- | :--- | | captureEmbedUrl | "http://127.0.0.1:4242" | Endpoint URL for in-memory semantic classification (POST /v1/classify). Independent of embedUrl, which feeds the memory index | | captureEmbedModel | "bge-base" | Classification embedding model (a multilingual model improves non-English recall) | | captureMode | "all", or "judge" when captureEmbedUrl is set in your settings | What automatic conversational capture stores: "all" (every user turn), "keyword" (only turns starting with a capture keyword), "judge" (turns the embedding classifier says are worth remembering), "off" | | captureEmbed | "auto" | Classify turns by embeddings in captureMode: "judge". Env: PI_MM_CAPTURE_EMBED | | captureMinSimilarity | 0.6 | Cosine floor for any embedding verdict (0..1) | | captureMinMargin | 0.075 | How far a "remember" verdict must beat "skip" (0..1); raise it to store less, lower it to store more | | captureExemplars | {} | Your own example sentences, { "remember": [...], "skip": [...] }, any language, merged with the shipped ones | | judgeFallback | "skip" | Deterministic fallback when the classifier server is offline ("skip" or "capture") | | autoStartAuren | true | Automatically launch axil-auren in the background if offline | | autoDownloadModels | "manual" | Model download policy ("manual" prompts for heavy models, "auto" downloads without prompting) | | semanticSearch | true | Enable dense vector embeddings and semantic recall via libsepal | | embedUrl | "http://127.0.0.1:4242/v1/embeddings" | Embedding generation endpoint | | embedModel | "bge-base" | Embedding model identifier ("bge-base" for 768-d, "bge-small" for 384-d) | | advancedTools | false | Expose the 9 advanced low-level memory inspection tools | | recallEmbed | "auto" | Classify user prompts by embeddings (POST /v1/classify) to detect recall intent ("auto" or "off"). Env: PI_MM_RECALL_EMBED | | recallMinSimilarity | 0.6 | Cosine floor for recall intent embedding classification (0..1) | | recallMinMargin | 0.08 | How far a "recall_past" verdict must beat "standalone" (0..1) | | recallExemplars | {} | Your own example sentences, { "recall_past": [...], "standalone": [...] }, merged with shipped ones | | recallFallback | "regex" | Fallback when classifier endpoint is offline: "regex" (deterministic heuristics) or "skip" | | recallAction | "hint" | Action on recall inquiry or architectural wonder: "hint" (default, zero DB queries, emits epistemic hint advising agent to use memory_recall via inference) or "query" (legacy auto-injection). Env: PI_MM_RECALL_ACTION | | wonderingEmbed | "auto" | Classify assistant turns and thoughts by embeddings (POST /v1/classify) to detect cognitive wonderings and architectural curiosity ("auto" or "off"). Env: PI_MM_WONDERING_EMBED | | wonderingMinSimilarity | 0.6 | Cosine floor for assistant wondering embedding classification (0..1) | | wonderingMinMargin | 0.08 | How far a "wondering" verdict must beat "routine_action" (0..1) | | directiveEmbed | "auto" | Classify user prompts by embeddings (POST /v1/classify) to detect standing directives/rules ("auto" or "off"). Env: PI_MM_DIRECTIVE_EMBED | | directiveMinSimilarity | 0.6 | Cosine floor for standing directive classification (0..1) | | directiveMinMargin | 0.08 | How far a "standing_directive" verdict must beat "transient_task" (0..1) | | directiveExemplars | {} | Custom examples { "standing_directive": [...], "transient_task": [...] } merged with shipped ones | | directiveFallback | "regex" | Fallback when endpoint is offline: "regex" or "skip" | | overviewEmbed | "auto" | Classify direct memory inquiries by embeddings (POST /v1/classify) to detect open-ended overviews ("auto" or "off"). Env: PI_MM_OVERVIEW_EMBED | | overviewMinSimilarity | 0.6 | Cosine floor for overview routing classification (0..1) | | overviewMinMargin | 0.08 | How far an "overview_query" verdict must beat "specific_query" (0..1) | | overviewExemplars | {} | Custom examples { "overview_query": [...], "specific_query": [...] } merged with shipped ones | | overviewFallback | "regex" | Fallback when endpoint is offline: "regex" or "skip" | | judgeProtocol | (deprecated) | Deprecated in favor of POST /v1/classify | | judgeModel | (deprecated) | Deprecated in favor of POST /v1/classify | | judgeUrl | (deprecated) | Deprecated; mapped to captureEmbedUrl |

Automatic Capture: What Decides What

captureMode decides whether anything is judged at all. Recall questions ("do you remember ...") are never captured, in any mode. In keyword and judge modes a turn that starts with a capture keyword (@remember, remember:, note: by default) is always stored, without consulting anything; in all mode every other turn is stored too.

| captureMode | What stores a turn | If that is unavailable | | :--- | :--- | :--- | | all | Every user turn. No classifier and no embeddings are consulted. | n/a | | keyword | Only turns that start with a capture keyword | n/a | | judge | In-Memory Embedding Classification via POST /v1/classify | Deterministic judgeFallback (skip stores nothing, capture stores the turn) | | off | Nothing automatic | n/a |

captureMode resolves to all unless you set it or put a judgeUrl in your settings (which implies judge). If you never set either, the embedding tier below never runs.

Why embeddings for judge mode: on English/Portuguese turns the default judge model (olmoe) answered "remember" to 40 of the 44 turns that were not worth remembering (greetings, thanks, recall probes, task requests; counted over two corpora of 22 such turns each), i.e. it stored almost everything. Measured on the held-out corpus of 44 new turns:

| | Embeddings (bge-base) | Judge (olmoe) | | :--- | :--- | :--- | | Accuracy | 26/44 (59%) | 24/44 (55%) | | False "remember" (a wrong store) | 0 | 20 | | Real memories recognised | 4/22 (7/22 on the development corpus) | 22/22 | | Latency (p50) | ~15 ms | ~1.9 s |

Read that honestly: embeddings are high-precision and low-recall. They store few turns and almost never the wrong one, so most casual statements are not captured automatically; say @remember ... for the ones that matter, add captureExemplars in your own phrasing, or lower captureMinMargin to store more. The first held-out run failed the adoption rule (3 false "remember"); the exemplar set was then extended by form and a hypothesis recorded before a fresh corpus confirmed it. bge-base is English-only, so Portuguese statements mostly fall back to "skip" until you add examples or use a multilingual model.

Measure your own phrasing (opt-in, never part of npm test; prints accuracy, false "remember", latency and every miss for both strategies): PI_MM_EVAL_JUDGE=1 deno test --allow-all --sloppy-imports tests/eval/ (set PI_MM_EVAL_URL for a non-default server).

Proactive Recall Intent: What Drives Context Injection

In addition to write-path capture judging, pi-mm intelligently classifies the read path before each agent turn (before_agent_start). When a user asks about past architectural choices, previous debugging sessions, decisions, rules, or lore, pi-mm uses POST /v1/classify against a curated bilingual exemplar corpus (recall_past vs standalone):

1. Hint-Only Architecture (recallAction: "hint", default): When recall intent or architectural wondering is confirmed by embeddings, auto_recall executes zero automated database scans (runScanWithTimeout and primeSubsystemInvariants are completely bypassed). Instead, it injects a quiet epistemic hint into event.systemPromptOptions.sections["memory_context"] advising the agent to formulate queries via LLM inference and retrieve records using memory_recall. It sets display: false on the returned custom message, completely eliminating noisy, unprompted UI cards in the user's chat interface. For legacy auto-injected background recall, set "recallAction": "query".
2. Lifting Unprompted Suppression: In general conversational turns without memory keywords, context injection is conservative. When recall_past intent is confirmed by embeddings, unprompted context filtering is lifted, allowing vector and hybrid retrieval to surface relevant memories even without exact subsystem matches.
3. Actionable Agent Steering: When recall intent is positive, pi-mm augments the agent's system prompt sections (memory_context) with explicit guidance directing the model to inspect memory_recall (and zoomRef if candidate records are retrieved) before guessing or invoking irrelevant bash or grep tools.
4. Resilient Offline Fallback: If axil-auren is offline or unconfigured, pi-mm seamlessly falls back to deterministic heuristics (recallFallback: "regex").

Daemon Circuit Breaker & Resilient Timeout

All embedding classification and vector calls to axil-auren are wrapped with a resilient in-memory circuit breaker (src/judge/circuit.ts):

• Fast Timeout: Imposes a tight default timeout of 250 ms (DEFAULT_CLASSIFY_TIMEOUT_MS = 250) on /v1/classify, well above normal local inference (~18 ms p50) but fast enough to prevent perceptible turn lag.
• Fail-Fast Cooldown: On connection refusal (ECONNREFUSED), socket hang, network error, or 5xx server status, the daemon base URL is placed on a 30-second cooldown (CIRCUIT_BACKOFF_MS = 30_000).
• Zero Overhead When Offline: While the circuit is open, subsequent calls bypass network I/O completely and return null immediately (measured at ~1 µs, 0 ms overhead), ensuring that Pi never freezes or stalls when axil-auren is stopped.

Assistant Cognitive Wondering Detection & Self-Hinting

When the agent expresses cognitive uncertainty, architectural curiosity, or wonders how a subsystem works mid-task:

• Examples: "I wonder how the caching layer works in this project", "Not sure how FTS handles accent folding here", "Where are session files stored in this architecture?"
• pi-mm intercepts the assistant's turn in message_end and evaluates the reasoning via vector embeddings (POST /v1/classify on axil-auren, bge-base).
• When classified as wondering (similarity $\ge 0.60$, margin $\ge 0.08$), the system steers the agent via pi.sendMessage (deliverAs: "steer"):

  💡 [Memory Hint]: You are exploring how this subsystem, convention, or architecture works. Check memory_recall to consult past technical decisions and lore.

• Zero automated database scans are run in the background, ensuring no speculative database queries and zero UI pollution. The agent uses its own inference to query memory_recall.
• Measured Accuracy: 100.0% accuracy (24/24), 100.0% recall, and 0.0% false positives (p50: 17.9 ms) across bilingual wondering and routine action benchmarks (npm run eval:wondering or scripts/eval-wondering.ts).

Empirical Benchmark: Regex Heuristics vs. Embeddings

Measured on a held-out, bilingual (English + Portuguese) corpus of 44 realistic turns (22 recall_past queries, 22 standalone engineering tasks), completely disjoint from training exemplars (npm run eval:recall against axil-auren with bge-base):

| Metric | Previous Heuristic Gate (isMemoryRecallPrompt) | axil-auren Embeddings (POST /v1/classify) | Impact / Delta | | :--- | :--- | :--- | :--- | | Overall Accuracy | 56.8% (25/44) | 81.8% (36/44) | +25.0% accuracy | | Recall Catch Rate (recall_past) | 13.6% (3/22) | 63.6% (14/22) | 4.7× improvement (+11 caught) | | Task Specificity (standalone) | 100.0% (22/22) | 100.0% (22/22) | Zero regressions / zero false recall | | False Positives | 0 | 0 | Zero unwanted memory spam | | Latency (p50 / p95) | < 1 ms | 17 ms / 34 ms | Fast, imperceptible C SIMD execution |

Run the recall evaluation suite against your live axil-auren instance:

npm --prefix .pi/extensions/pi-mm run eval:recall

npm test is hermetic: it preloads tests/no-live-network.ts, which refuses any request to the real auren port (4242) or to a non-loopback host, and runs with PI_MM_AUTO_START_AUREN=0 so no local server is started. Run with PI_MM_ALLOW_LIVE=1 to lift the guard.

5. Prerequisites & Core C Engines

pi-mm uses compiled C engines for sub-microsecond in-memory retrieval:

| Engine | Description | Build & Guide | | :--- | :--- | :--- | | libcorm | In-memory key-value store, unified recall kernel, and cormd daemon. | libcorm | | libsepal | Pure-C Approximate Nearest Neighbor (ANN) dense vector store. | libsepal | | libjoint | Interval-tree temporal presence engine for historical co-occurrence. | libjoint | | liblemma | Diacritic-preserving full-text search tokenizer (pão ≠ pao). | liblemma | | axil-auren | Local LLM inference, embeddings, and fast decision judging. | axil-auren |

Prebuilt packages are available via tty.pt packages for APT, Homebrew, and pacman.

6. Development & Verification

npm --prefix .pi/extensions/pi-mm test             # Run hermetic test suite (450+ tests)
npm --prefix .pi/extensions/pi-mm run lint         # Lint all TypeScript source and scripts
npm --prefix .pi/extensions/pi-mm run eval:recall  # Benchmark recall intent classification against live auren
npm --prefix .pi/extensions/pi-mm run eval:surfaces # Benchmark directive, overview, and kind classification
npm --prefix .pi/extensions/pi-mm run test:playbook # Non-destructive bootstrap verification playbook
npm --prefix .pi/extensions/pi-mm run demo          # Interactive live bootstrap demonstration
npm --prefix .pi/extensions/pi-mm run zip           # Package distribution bundle

License

BSD 2-Clause License. Copyright (c) 2025, tty-pt. See LICENSE.