@gaodes/pi-muninndb

Persistent memory for Pi via MuninnDB.

Gives Pi semantic memory across sessions — decisions, preferences, facts, procedures — that survives restarts. Uses an MCP-first architecture: all 39 MuninnDB tools are exposed through pi-mcp-adapter, and the extension provides only what MCP cannot (SSE push, context injection, setup automation).

Fork of @kuyavinny/pi-muninn-mem v1.1.0 — published under PrimeCodex as @gaodes/pi-muninndb.

Install

pi install npm:pi-mcp-adapter        # required dependency
pi install npm:@gaodes/pi-muninndb

Then reload Pi and run:

/muninn-setup

This single command handles everything:

1. Checks that pi-mcp-adapter is installed
2. Runs the official MuninnDB install script if the binary is not found
3. Starts MuninnDB
4. Writes MCP config to ~/.config/mcp/mcp.json
5. Adds MuninnDB instructions to ~/.pi/agent/AGENTS.md (non-destructive)
6. Verifies the setup

If MuninnDB isn't running when Pi starts, you'll see:

⚠️ MuninnDB is not running. Run /muninn-setup to install and configure it.

Commands

Command	Description
/muninn-setup	Install MuninnDB, configure MCP + AGENTS.md
/muninn-remove	Unregister extension, remove MCP config, clean AGENTS.md
/muninn-vault status	Show current vault and mapping
/muninn-vault create [name]	Link current directory to a named vault
/muninn-vault unlink	Remove vault mapping for current directory
/muninn-dream	Run dream protocol: consolidate, evolve, enrich memories (offline)
/muninn-test	Fast smoke test — 16 REST API tests in ~120ms
/muninn-test full	Full smoke test — 49 tests covering all 39 MCP tools in ~380ms
/muninn-backup	Export vault archive + offline data backup
/muninn-health	Show server status, vault stats, service ports
/muninn-import	Import a .muninn backup archive into a vault
/muninn-upgrade	Check for and install MuninnDB updates

How It Works

Extension Hooks

Hook	What it does
session_start	Health-check MuninnDB, start SSE subscription, notify user
before_agent_start	Evolve SSE subscription context from current prompt; on first turn: pre-fetch memories, surface muninndb_muninn_guide
context	Push contradiction alerts, memory updates, and activation signals via SSE
session_shutdown	Clean up SSE connection
tool_call	Auto-inject vault parameter, annotate: true on recall, batch nudge, checkpoint hint, and feedback hint on recall

MCP Tools (via MuninnDB on port 8750)

The LLM calls these directly through the mcp gateway. All 39 tools are available:

Tool	Purpose
muninndb_muninn_where_left_off	Restore context from last session — call this first
muninndb_muninn_remember	Store a fact, decision, preference, or observation
muninndb_muninn_recall	Semantic search for relevant memories
muninndb_muninn_read	Read a single memory by ID
muninndb_muninn_forget	Soft-delete a memory
muninndb_muninn_restore	Recover a soft-deleted memory
muninndb_muninn_evolve	Update a memory with new information
muninndb_muninn_consolidate	Merge related memories
muninndb_muninn_decide	Record a decision with rationale and evidence
muninndb_muninn_remember_batch	Store multiple memories at once (max 50)
muninndb_muninn_state	Set lifecycle state (active, completed, paused, etc.)
muninndb_muninn_link	Create association between two memories
muninndb_muninn_traverse	Explore the memory graph by following associations
muninndb_muninn_explain	Show why a memory was returned for a query
muninndb_muninn_entities	List all known entities in the vault
muninndb_muninn_entity	Full detail for a named entity
muninndb_muninn_remember_tree	Store a nested hierarchy (project plan, task tree)
muninndb_muninn_recall_tree	Retrieve a complete hierarchy
muninndb_muninn_export_graph	Export entity graph as JSON-LD or GraphML
muninndb_muninn_contradictions	Check for known contradictions
muninndb_muninn_guide	Get vault-specific usage instructions

Plus 18 more — call muninndb_muninn_guide for the full list.

Architecture

┌──────────────────────────────────────────────┐
│              Pi Extension                    │
│                                              │
│  session_start  → Health check, start SSE   │
│  before_agent_start (1st turn) → Inject     │
│  context        → Push contradictions       │
│  session_shutdown → Clean up SSE            │
│  tool_call      → Vault, annotate, nudge      │
│  /muninn-setup  → Install + configure        │
│  /muninn-remove → Uninstall                  │
│  /muninn-test   → Smoke test (REST + MCP)    │
│  /muninn-dream  → Dream protocol (via CLI)  │
│  /muninn-backup → Export vault archive       │
│  /muninn-health → Server status + stats      │
│  /muninn-import → Import backup archive      │
│  /muninn-upgrade→ Check/install updates      │
│  /muninn-vault  → Vault management           │
└──────────────┬───────────────────┬───────────┘
               │                   │
          SSE subscription     MCP tools
          (REST :8475)      (:8750/mcp)
               │                   │
               └───────┬───────────┘
                       ▼
                    MuninnDB

Extension Behaviors

The extension adds several automatic behaviors on top of the MCP tools:

Behavior	Description
Vault auto-injection	All 39 muninndb_muninn_* tool calls receive the resolved vault name automatically. No need to pass vault manually.
Recall annotations	muninn_recall calls automatically get annotate: true, so results include staleness, conflict, and trust metadata.
Feedback hint	After each muninn_recall, a subtle context hint reminds the agent that muninn_feedback exists for quality scoring.
Batch nudge	After 2+ individual muninn_remember calls in one turn, the extension nudges toward muninn_remember_batch.
Context-aware semantic triggers	SSE subscriptions include the agent's working context (current prompt, recent memory concepts, vault name). MuninnDB fires triggers only when relevance exceeds threshold, not on every high-scoring write.
Evolving subscription context	Subscription context refreshes on every turn, so triggers track the live task instead of going stale.
Guide surfacing	Session-start injection reminds the agent to call muninndb_muninn_guide to learn vault-specific behavior and enrichment state.
SSE: contradictions	When a new memory conflicts with an existing one, the agent receives a [⚠️ Contradiction detected] context push.
SSE: threshold crossed	When a memory's activation score crosses the subscription threshold, the agent receives an [📈 Activation signal] context push.
SSE: new writes	High-scoring new memories (≥ threshold) are pushed to the agent's context in real time.
Health liveness	/muninn-health reports whether the SSE subscription, tool_call hook, and context hook are actually firing, so a broken integration is visible.

All LLM operations go through MCP. The extension only provides SSE subscription (which MCP cannot do), context injection, setup automation, and diagnostics.

Smoke Testing

Fast Mode (REST only)

/muninn-test

Runs 16 REST API tests against http://127.0.0.1:8475 in ~120ms:

Suite	Tests
Health & Connection	health, vaults, guide
CRUD	create, read, recall, forget, list-deleted, recreate
Batch & Advanced	batch write, evolve, lifecycle state, decide
Query	filter by tag, contradictions, session activity

Full Mode (REST + MCP)

/muninn-test full

Runs 49 tests covering all 39 MCP tools via HTTP JSON-RPC on port 8750 in ~380ms:

Suite	Tests	Tools covered
MCP Connection	3	initialize, status, where_left_off
Entity Operations	7	entities, entity, find_by_entity, timeline, state, clusters, similar
Graph & Link	6	remember, link, traverse, explain, export_graph
Memory Operations	7	read, recall, evolve, consolidate, state, decide
Tree Operations	3	remember_tree, recall_tree, add_child
Enrichment & Provenance	4	provenance, enrichment candidates, trust, feedback
Delete & Restore	2	forget + restore, list_deleted
Batch	1	remember_batch

All test artifacts are tagged __pi_test__ and cleaned up automatically.

Dream Protocol

muninn dream is LLM-driven memory consolidation — it merges related memories, evolves stale ones, and runs enrichment on unprocessed engrams. Think of it as "defrag for your memory vault."

Key Constraint

Dream requires the MuninnDB server to be stopped. It reads SQLite data files directly, not through the REST API. While dream runs, all MCP tools (remember, recall, etc.) are offline.

Running Dream

/muninn-dream

This command:

1. Detects the vault for the current project (or uses default)
2. Warns if the server is running
3. Runs muninn dream --dry-run --scope <vault> to preview changes
4. Shows the preview and asks for confirmation
5. Runs muninn dream --scope <vault> for real if confirmed

Flags:

Flag	Description
--dry-run	Preview only — show what dream would do, then stop
--scope <vault>	Override vault (defaults to current project vault)
--force	Bypass trigger gates (not yet implemented)

Manual CLI alternative:

# Stop the server first
muninn stop

# Preview consolidation
muninn dream --dry-run --scope default

# Run for real
muninn dream --scope default

# Restart the server
muninn start

Practical Guidance

• When to run: When stepping away from the machine, or between sessions. Large vaults take longer.
• Scope it: Use --scope <vault> to limit consolidation to one vault. Smaller scope = faster.
• Downtime: Expect ~30–60 seconds of MCP unavailability per vault, depending on engram count.
• Automated runs: For overnight maintenance, use a cron/launchd job: muninn stop && muninn dream --scope default && muninn start
• No data loss: Dream consolidates and evolves — it never deletes without archiving. Soft-deleted memories remain recoverable for 7 days.

Development

Script	Command
Build (all)	npm run build
Build extension	npm run build:extension
Build dream CLI	npm run build:dream
Build test CLI	npm run build:test
Type check	npm run check
Lint	npm run lint
Fix lint	npm run lint:fix
Format	npm run format
Check format	npm run format:check
Test (unit)	npm test
Smoke test (fast)	node dist/muninn-test.mjs --vault default
Smoke test (full)	node dist/muninn-test.mjs full --vault default --verbose

Embedding Configuration

MuninnDB ships with a bundled ONNX embedder (all-MiniLM-L6-v2, 384-dim) that works offline with zero configuration. This is the default.

For better embeddings, edit ~/.muninn/muninn.env and restart MuninnDB:

Provider	Config	Quality
Ollama (recommended)	MUNINN_OLLAMA_URL=ollama://localhost:11434/nomic-embed-text	768-dim, free, local
LM Studio	MUNINN_OPENAI_URL=http://localhost:1234/v1	Any model
OpenAI	MUNINN_OPENAI_KEY=sk-...	text-embedding-3-small
Voyage AI	MUNINN_VOYAGE_KEY=pa-...	voyage-3

For enrichment (summaries, entities, contradiction detection):

MUNINN_ENRICH_URL=ollama://localhost:11434/llama3.2:1b
MUNINN_ENRICH_TIMEOUT=120s

Models are never auto-pulled — you must install them explicitly.

Security

• MCP config URLs validated as localhost-only with known ports
• File writes are atomic (temp + rename)
• All command execution uses argument arrays (no shell interpolation)
• SSE reconnection uses exponential backoff (5s → 5min cap)
• Tool calls validated against an allowlist of known MuninnDB tools
• Vault names sanitized and length-limited (64 chars)

Uninstall

/muninn-remove

This removes the MCP config, AGENTS.md section, and Pi extension registration. MuninnDB data (~/.muninn/) is preserved — delete it manually if desired.

Configuration Files

File	Purpose
~/.config/mcp/mcp.json	MCP server URL for MuninnDB
~/.pi/agent/AGENTS.md	LLM instructions for MuninnDB (non-destructive)
~/.pi/agent/prime-settings.json	Extension configuration
~/.muninn/muninn.env	MuninnDB embedder/enricher settings
~/.muninn/data/	MuninnDB data (Pebble DB)

Configuration

pi-muninndb reads its settings from the muninndb key in prime-settings.json. The first time the extension loads, it auto-seeds the following defaults into ~/.pi/agent/prime-settings.json:

{
  "muninndb": {
    "sse": {
      "enabled": true,
      "threshold": 0.7,
      "newWriteScoreGate": 0.7
    },
    "prefetchLimit": 8,
    "checkpointTools": ["git_commit_execute", "git_push", "git_tag"]
  }
}

Project-level overrides are supported at .pi/prime-settings.json (merged over global).

Key	Type	Default	Description
sse.enabled	boolean	true	Master switch for the SSE semantic-trigger subscription.
sse.threshold	number	0.7	Minimum activation score for a subscription match (0.0–1.0).
sse.newWriteScoreGate	number	0.7	Minimum score to surface a new_write push to the agent.
prefetchLimit	number	8	How many recent memories to pre-fetch at session start.
checkpointTools	string[]	git_commit_execute, git_push, git_tag	Native Pi tools that trigger a checkpoint save hint.

Lower threshold = more triggers (higher recall, lower precision). Higher threshold = fewer, more relevant pushes.

Provenance

Field	Value
Forked from	@kuyavinny/pi-muninn-mem v1.1.0
Upstream repo	https://github.com/kuyavinny/pi-muninn-mem
Relationship	Fork
Inspiration	muninndb server (https://github.com/scrypster/muninndb)
License	MIT

See .upstream.json for full provenance tracking.

License

MIT