@tty-pt/pi-mm
Memory Mipmaps extension for Pi Coding Agent — persistent, hierarchical recall with automatic bounded context injection and streamlined memory_recall, memory_record, memory_review tools.
Package details
Install @tty-pt/pi-mm from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@tty-pt/pi-mm- Package
@tty-pt/pi-mm- Version
0.8.0- Published
- Nov 16, 2026
- Downloads
- 1,809/mo · 228/wk
- Author
- quirinpa
- License
- BSD-2-Clause
- Types
- extension, skill
- Size
- 6.2 MB
- Dependencies
- 8 dependencies · 3 peers
Pi manifest JSON
{
"image": "cover.png",
"skills": [
"skills/pi-mm/SKILL.md"
],
"extensions": [
"index.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
pi-mm: Intelligent Persistent Memory for Pi Coding Agent
Multi-resolution persistent memory, active session recall, and live codebase mipmap graphs for the Pi Coding Agent powered by native C engines (
libcorm,libsepal,liblemma,libjoint,libislet).
pi-mm gives your Pi Coding Agent a unified multi-resolution memory space spanning persistent cross-session lore (scope: "persistent"), ephemeral active session transcripts & lossless compaction (scope: "session"), and live codebase symbol graphs, call graphs, and git diff blast radius (scope: "code"). It automatically injects relevant prior technical decisions into context before each turn, compacts long sessions into navigable mipmaps, and fuses historical debugging episodes directly into code symbol reads—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:
- Standalone Prebuilt C Engines via npm: Pulls
@tty-pt/{axil,auren,stele,corm,joint,lemma,sepal,islet}prebuilt native Node-API addons, CLI host (@tty-pt/axil/bin/axil.js), and shared libraries (libaxil-auren, axis.so/.dylib) automatically (NativeAddonCormRunner&findAurenLaunchers), running without requiring system-wide/usr/binbinaries,/usr/libC libraries, orpkg-config(while seamlessly attaching tocormdwhen a daemon lease is active). - Automatic Daemon Startup: Checks if
axil-aurenis running on port 4242. If offline, it brings up the shared background server automatically using@tty-pt/axil+@tty-pt/aurenprebuilds (or system/usr/bin/axilwhen present). - 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 unified status bar (pi-mm). - Proactive Dependency & Feature Floor Checks: On
session_start,pi-mmaudits core C engines (libcorm,libsepal,liblemma,libjoint,libislet,axil,axil-auren) againstREQUIRED_ENGINE_FEATURESand 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, consolidation pipeline health (L2/L3 synthesis status, L0/L1 queue depths, drain rate, backlog/stale alerts), 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, scope, session, overview, zoomRef, zoomTurn, toolIndex, lineage, symbol, symbols, file, kind, parentSymbol, neighbors, trace, direction, depth, diff, diagnose, guardrail, lineRange, maxLines, fullOutput, project, subsystem, level, includeEvidence, limit |
Unified multi-resolution retrieval across persistent lore (scope: "persistent"), active/parallel session turns (scope: "session"), and live codebase structure, call graphs, failure diagnosis, and counterfactual guardrails (scope: "code"). |
memory_record |
problem, approaches, diffs, findings, outcome, verification, evidence, standing |
Explicitly records an episode, bug fix, or project invariant with verified test commands (automatically promoted to supported when attested by the session verification ledger) and binds it to AST symbol anchors. |
memory_review |
ref, action, lifecycle, reason, evidenceRef |
Inspects memory evidence hierarchy (action: "inspect") or transitions factual lifecycle status (action: "update_lifecycle") with automatic Evidence DAG Truth Maintenance cascade. |
Advanced fine-grained tools (memory_store, memory_scan, memory_think, memory_forget, etc.) can be enabled via "advancedTools": true.
2.1 Multi-Axis Codebase Mipmap Graph, Causal Diagnosis & Lore Fusion (scope: "code")
pi-mm indexes live repository source code directly into the C multi-axis recall kernel (libcorm + liblemma + libsepal + libislet), replacing standalone AST/graph tools with a unified codebase mipmap space:
- Zero-Regex Character-Stream Structural Scanner & Higher-Order Stitching (
src/code/lexer.ts,src/code/scanner.ts):- Single-pass character-stream state machine tracking string literals, line/block comments, preprocessor directives, brace/paren depth, and line numbers across C/C++, TypeScript/JavaScript, and Python (handling TS inline object parameter/return types and parenthesized C
#definemacros cleanly). - Extracts
Function(includingXY_IMPL(...)definitions vsXY_DECL(...)forward declarations),Method,Class,Struct,Interface,Enum,Macro,TypeAlias, and HTTPRoutesymbols, plus#include,import, andxy_load(...)module dependencies. - Higher-Order Call-Graph Stitching: Automatically links HTTP
Routeregistrations to handler functions, function-pointer callback arguments passed to higher-order wrappers (with_module_item_access(..., cb)), C struct designated-initializer callbacks (.detail = song_detail_handler), and cross-modulexy_load("./mods/<M>/<M>")calls to targetxy_installentrypoints. - Library-Agnostic Structural Route Detection: Detects route registrations purely from call-argument structure without hardcoded framework names:
- Method calls:
obj.<http_method>("/path"[, handler])(e.g.app.get("/v1/classify", handler)) - Two-string calls:
fn("<http_method>", "/path"[, handler])(e.g.register_route("POST", "/song/edit", handler)) - Method-prefixed route strings:
fn("<HTTP_METHOD>:/path"[, handler])orfn("<HTTP_METHOD> /path"[, handler])(e.g.route("GET:/api/song/:id", handler))
- Method calls:
- Single-pass character-stream state machine tracking string literals, line/block comments, preprocessor directives, brace/paren depth, and line numbers across C/C++, TypeScript/JavaScript, and Python (handling TS inline object parameter/return types and parenthesized C
- Incremental Multi-Axis Code Store & Concurrency Safety (
src/code/store.ts,src/code/graph.ts):- Stores L2 file summaries and L1/L0 symbol records in
code.db(joint,lemma,sepal) and 2D[fileHash, startLine..endLine]interval spans incode-islet.db(libislet). - Priority Root Indexing & Submodule Isolation: Scans primary project roots (
mods/,src/,include/,lib/,app/,bin/) beforeexternal/,vendor/, ortests/, excludes third-party vendor git submodules by default unless explicitly queried, and skips nested git submodule directories whengit statusreports only submodule commit changes. - Single-Flight Refresh Serialization & Turn Coalescing: Serializes concurrent
refreshIncremental()calls behind an in-memory promise lock (refreshLock) and coalesces rapidbefore_agent_startturns within 1500 ms. - Call-Graph Disambiguation: Filters language keywords, C/POSIX stdlib routines (
malloc,free,memcpy,printf, etc.), built-in JS/TS/Python method names (get,set,map,filter,push, etc.), non-callable#definemacro constants, and C struct member pointer invocations (ops->load()) fromrawCallees; resolves call edges with language-family isolation, same-file/same-module/import-path affinity, andXY_IMPLdefinition preference overXY_DECLheader declarations.
- Stores L2 file summaries and L1/L0 symbol records in
- Seven Unified Codebase Workflows:
- Hybrid Symbol Search & Auto-Preview:
memory_recall({ scope: "code", query: "<symbol or concept>", file?, kind? })— fusesliblemmaidentifier/signature matching andlibsepalsemantic search; automatically expands full source, callers/callees, and linked lore when a single symbol matches unambiguously. - Concrete Symbol / Batch Source Read (Fail-Closed on Ambiguity):
memory_recall({ symbol: "render_song_item", file?, parentSymbol?, neighbors?: "both", lineRange?: [1, 80] })ormemory_recall({ symbols: ["SymA", "SymB"] })— returns exactfile:startLine-endLinesource slices, direct callers/callees, cross-boundary pairs (XY_DECL$\leftrightarrow$XY_IMPLand Server C $\leftrightarrow$ Isomorphic UX WASM), first-touch module dossiers, and automatically fuses linkedpi-mmpersistent invariants and past debugging episodes. - Multi-Hop Call Graph Traversal:
memory_recall({ trace: "song_detail_handler", direction: "inbound" | "outbound" | "both", depth: 3 })— BFS traversal across direct calls, higher-order callbacks, struct initializers, routes, andxy_loadedges with cycle detection and per-hopfile:linecitations. - Architecture Overview (L3/L2 Mipmap):
memory_recall({ scope: "code", overview: true })— synthesizes module clusters,#include/import/xy_loaddependency DAG, HTTP routes & entry points, and high-degree call hotspots. - Worktree Change Impact, Contract Flight Check & Tier-0 Verification Gate Status:
memory_recall({ diff: true, depth: 2 })— mapsgit diffmodified line hunks vialibislet2D interval spans to affected symbols, traces inbound callers up todepthhops, checksXY_DECL$\leftrightarrow$XY_IMPLsignature/declaration parity (detectXyContractMismatches), and reports live[Tier-0 Module Verification Gate Status]([VERIFIED ✓ after last edit]vs[UNVERIFIED ⚠️]) for every modified module. - Execution-Trace & Differential Failure Topology (
diagnose):memory_recall({ diagnose: "<stack trace | compiler error | test failure>", depth?: 2 })— parses TS/JS, C/GDB, and Python stack frames without regexes, maps frames to enclosing AST symbols vialibislet, and intersects the stack call-cone withgit diffblast radius to pinpoint the Causal Fault Intersection (modified_on_stack,modified_callee_of_stack,caller_of_modified_on_stack), automatically fusing relevant debugging lore and counterfactual guardrails. - Pre-Tool Counterfactual Guardrails (
guardrail):memory_recall({ guardrail: "<planned edit | command | approach>", file?, symbol? })— pre-flights planned actions against contradicted memories, previously failed episode approaches, standing restrictions, and stale-suspect code-bound invariants (also triggered passively onedit,write, and failingbashtool results).
- Hybrid Symbol Search & Auto-Preview:
- Live Epistemic Invalidation, Working-Memory Staleness Radar & Swarm Stigmergy:
- Code-to-Lore Causal Binding (
src/code/lore_binding.ts): Bindssupported/testedinvariants and episodes to AST symbol fingerprints (lore-bindings.json). If a bound symbol's signature/callees change, the symbol is deleted, or agit diffhunk touches its span,memory_recallflags the invariant as⚠️ [STALE_SUSPECT]. - Working-Memory Context-Window Staleness Radar (
src/code/context_sync.ts): Tracks per-session snapshots (mtimeMs, size, symbol spans/fingerprints) of every file inspected or edited by the agent. If a file in the agent's working context is modified externally on disk, the nextmemory_recallauto-refreshesCodeStoreand emits a surgical symbol delta alert (modified,lines_shifted,added,removed). - Collective Swarm Stigmergy (
src/code/stigmergy.ts): Broadcasts 15-minute spatial attention leases (swarm-leases.json, shared across.pi/scratch/slot-*worktrees) when sessions inspect or mutate symbols, surfacing active peer sessions (exact_symbol,same_file,call_graph_neighbor) in real time.
- Code-to-Lore Causal Binding (
2.2 Ephemeral Semantic Session Memory, Provenance Boundaries & Mipmap Compaction (scope: "session")
pi-mm indexes active conversational turns and tool outputs into an ephemeral per-session multi-axis store (.pi/mm/sessions/<sessionId>/session.db), enabling progressive in-session recall, parallel session inspection, and lossless context compaction:
- Asymmetric Multi-Granularity Ingestion & Write Serialization (
src/session/sink.ts,src/session/store.ts):- Decomposes each settled turn into Turn (L1) summaries, Block (L1) tool/reasoning segments, and Symbol (L0) exact identifier/path records over
libcorm(joint,lemma,sepal), while preserving raw line-addressable turn payloads on disk (turns/turn-<N>.json). - Serializes all
ingestTurnandrebuildSessionIndexmutations through a per-store promise queue (withWriteLock), preventing concurrentcorm -p/corm -cCLI invocations from corruptingsession.db.
- Decomposes each settled turn into Turn (L1) summaries, Block (L1) tool/reasoning segments, and Symbol (L0) exact identifier/path records over
- Active Branch Lineage DAG & Reload Resilience (
src/session/lineage.ts,src/session/manager.ts):- Tracks turn parent-child edges across session branches and forks so
lineage: "active"(default) filters out abandoned sibling branches whilelineage: "all"searches the entire session DAG. - Automatically reconstructs linear ancestry for previously persisted turns if the extension is reloaded mid-session or a session is resumed without in-memory lineage nodes.
- Tracks turn parent-child edges across session branches and forks so
- Explicit Session Provenance Boundaries & Multi-Session Routing (
src/session/recall.ts,src/session/manager.ts):- Supports
session: "current" | "parallel" | "all" | "<uuid-prefix>" | "<slot-label>"(e.g.slot-6) to query across active, parallel scratch-slot, or historical sessions. - Explicitly labels every retrieved turn and excerpt with provenance badges (
[Current Session],[Parallel Session <id> (<slot>)], or[Past Session <id>]) so agents never confuse historical dialogue with current session state.
- Supports
- Progressive 3-Tier Session Retrieval (
src/session/recall.ts):- Fuses C multi-axis (
liblemma+libsepal+libjoint) scores with exact symbol/identifier boosts and formats matches according to query specificity:- Tier 1 (Index Card): Compact turn metadata, timestamp, summary, and extracted symbols.
- Tier 2 (Focused Excerpt): Relevant message/tool block excerpt surrounding the matched query terms.
- Tier 3 (Exact Line Slice): Exact line range (
memory_recall({ scope: "session", zoomTurn: 7, toolIndex?: 0, lineRange: [10, 40] })) sliced directly from the stored turn payload.
- Fuses C multi-axis (
- Mipmap-Driven Context Compaction & Post-Compaction Continuity (
src/session/compaction.ts,src/hooks/auto_recall.ts):- Hooks
session_before_compactto synthesize a structured L2/L1 session mipmap (session objectives, completed milestones, active files & symbols, verified decisions, recent verbatim interactions, and unresolved blockers) with explicitmemory_recall({ scope: "session", zoomTurn })drill-down pointers, and injects post-compaction continuity hints on the first turn after compaction.
- Hooks
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.55 |
Cosine floor for any embedding verdict (0..1) |
captureMinMargin |
0.025 |
How far a "remember" verdict must beat "skip" (0..1); lower margin enables high-frequency technical capture |
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) |
synthUrl |
auto (auren chat endpoint) | Chat completions URL for L2/L3 abstraction synthesis (defaults to /v1/chat/completions on the local auren server, or "off" to disable). Env: PI_MM_SYNTH_URL |
synthModel |
"smollm" |
Model name for L2/L3 synthesis when auto-defaulted to local auren. Env: PI_MM_SYNTH_MODEL |
consolidateDrainMs |
250 |
Wall-clock budget in ms per turn to drain the pending L0 consolidation queue; 0 disables idle backlog draining. Env: PI_MM_CONSOLIDATE_DRAIN_MS |
consolidateBatchLimit |
20 |
Maximum number of memories processed per consolidation batch. Env: PI_MM_CONSOLIDATE_BATCH_LIMIT |
maxStorageBytes |
107374182400 |
Soft storage limit threshold in bytes (default 100 GB). Env: PI_MM_MAX_STORAGE_BYTES |
l0RetentionPolicy |
"keep_all" |
Raw L0 tool retention policy: "keep_all" (preserves full 100GB history) or "prune_after_consolidation" (supersedes raw tool traces once consolidated). Env: PI_MM_L0_RETENTION_POLICY |
autoRecallBudgetChars |
1500 |
Maximum character budget injected into system prompt before a turn. Env: PI_MM_AUTO_RECALL_BUDGET |
semanticDeduplication |
true |
Automatically supersede older duplicate records in the same scope when cosine similarity >= 0.88. Env: PI_MM_SEMANTIC_DEDUPLICATION |
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 |
"skip" |
Fallback when classifier endpoint is offline: "skip" (default, zero guessing) or "capture" |
recallAction |
"query" |
Action on recall inquiry: "query" (default, executes hybrid scan and injects matching memories) or "hint" (emits epistemic hint advising agent to use memory_recall). 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 |
"skip" |
Fallback when endpoint is offline: "skip" (default, zero guessing) or "capture" |
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 |
"skip" |
Fallback when endpoint is offline: "skip" (default, zero guessing) or "capture" |
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):
- Hint-Only Architecture (
recallAction: "hint", default): When recall intent or architectural wondering is confirmed by embeddings,auto_recallexecutes zero automated database scans (runScanWithTimeoutandprimeSubsystemInvariantsare completely bypassed). Instead, it injects a quiet epistemic hint intoevent.systemPromptOptions.sections["memory_context"]advising the agent to formulate queries via LLM inference and retrieve records usingmemory_recall. It setsdisplay: falseon 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". - Lifting Unprompted Suppression: In general conversational turns without memory keywords, context injection is conservative. When
recall_pastintent is confirmed by embeddings, unprompted context filtering is lifted, allowing vector and hybrid retrieval to surface relevant memories even without exact subsystem matches. - Actionable Agent Steering: When recall intent is positive,
pi-mmaugments the agent's system prompt sections (memory_context) with explicit guidance directing the model to inspectmemory_recall(andzoomRefif candidate records are retrieved) before guessing or invoking irrelevant bash or grep tools. - Resilient Offline Fallback: If
axil-aurenis offline or unconfigured,pi-mmsafely defaults to skipping unprompted retrieval (recallFallback: "skip"), completely eliminating fragile regex guessing or false positives.
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
nullimmediately (measured at ~1 µs, 0 ms overhead), ensuring that Pi never freezes or stalls whenaxil-aurenis 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-mmintercepts the assistant's turn inmessage_endand evaluates the reasoning via vector embeddings (POST /v1/classifyonaxil-auren,bge-base).- When classified as
wondering(similarity $\ge 0.60$, margin $\ge 0.08$), the system steers the agent viapi.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:wonderingorscripts/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.
Quest Symbiosis & Standing Directive Reinforcement
pi-mm works seamlessly with pi-quest for continuous memory distillation and operational discipline:
- Decoupled Quest Archive Distillation:
When a quest concludes via
quest_archive,pi-mmasynchronously processes the completed task metadata. Key findings, verified code diffs, execution metrics, and root-cause discoveries are distilled into structured episodic records (memory_record) without stalling the agent turn. Failed quests with setbacks are similarly preserved as lessons learned (lifecycle: "observed",approach: "failed"). - Dual-End Assistant Discovery Distillation & Verification-Attested Promotion Ledger:
When a task turn involves informative tool executions (code modifications or test runs) and the assistant explains the fix,
pi-mmdistills the discovery into an L1 Task Episode citing the tool executions as evidence. Simultaneously,src/hooks/verification_ledger.tstracks failing test/build commands (make test*,deno test,npm test,check-*.sh,check-complexity.ts, etc.), mutated files, andFAIL -> PASStransitions: when edited files transition a failing verification command to exit code 0,pi-mmautomatically synthesizes an attested L2 causal fix memory (tags: ["attested-fix", "fail-to-pass"]) and promotesmemory_recordepisodes whoseverification.testsPassedmatch the session's passing ledger directly tolifecycle: "supported". - Evidence DAG Truth Maintenance Cascade:
When
memory_review/memory_lifecycletransitions a memory tocontradictedorsuperseded,pi-mmautomatically updateslore-bindings.json, unregisters invalidated directives fromstanding_directives.json, and cascades down the evidence DAG (propagateTruthMaintenanceCascade) to auto-downgrade dependentsupported/testedconclusions tohypothesizedwith full audit history. - Unwedged L0 Consolidation & Zero-Config Local Synthesis:
L0 tool episodes are consolidated into L1 episodes without queue stalls. Fresh turns are consolidated first, followed by the remaining backlog ordered newest-first (
orderPendingL0Refs). Idle turns drain remaining L0 items within a configurable wall-clock budget (consolidateDrainMs, default 250ms). When a localaxil-aurenserver is running, L2/L3 abstraction synthesis is automatically wired to its OpenAI-compatible chat endpoint (/v1/chat/completions) usingsmollm, eliminating stalled consolidation queues without manual configuration. - Retrieval-Quality Gate & L0 Targeted Recall:
Targeted recall via
memory_recallincludes L0 task memories when requested (level: "L0"or untiered searches) while strictly exempting structured technical episodes from code artifact pruning. Golden retrieval quality is asserted via a rigorous benchmark gate (scripts/eval-retrieval.ts) requiring recall@5 = 1.0, MRR $\ge$ 0.5, and synthesized L1/L2 records ranked above raw tool noise. - Conversational Invariants & Negative Constraint Learning:
Developer feedback ("don't use raw pointers in request handlers", "never mock the filesystem in tests", "stop modifying the lockfile without running make", "you made a mistake, that function requires three arguments") is semantically classified via
POST /v1/classify, elevated to L2 invariants (standing: true), and continuously reinforced in the assistant's prompt across every turn with newest-first ordering. - Scalable 100GB Mipmap Architecture:
Stores up to 100GB of raw execution diffs and logs on disk via
libcormOS memory-mapped files (mmap) andlibsepalHamming sketches, while keeping LLM context lean via compact L1/L2 summaries and on-demandzoomRefdrilldowns. - Standing Directive Reinforcement Sync:
Operational directives and invariants (
level: "L2",standing: true) are persisted to disk (standing_directives.json) and synchronized into the global cache. This guarantees that established invariants survive cross-session restarts and are automatically seeded into newpi-questdraft proposals. - In-Process Node-API (
NativeAddonCormRunner) &cormdJSON Protocol Support: Executes structured memory storage and retrieval in-process via@tty-pt/corm(corm_node.nodewithRTLD_GLOBAL) or over the nativecormddaemon JSON IPC protocol when an external daemon lock is held.
5. Prerequisites & Core C Engines
pi-mm bundles prebuilt Node-API addons, the axil CLI host, libaxil-auren, and axis shared libraries via npm (@tty-pt/{axil,auren,stele,corm,joint,lemma,sepal,islet}) for zero-system-library operation, and also supports system/workspace builds:
| 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 |
libislet |
2D spatial & interval-span indexing engine (file line-range intersection & spatial grids). | libislet |
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 (500+ 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 eval:retrieval # Benchmark retrieval quality (recall@5, MRR, ranking)
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.