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:

Checks that pi-mcp-adapter is installed
Runs the official MuninnDB install script if the binary is not found
Starts MuninnDB
Writes MCP config to ~/.config/mcp/mcp.json
Adds MuninnDB instructions to ~/.pi/agent/AGENTS.md (non-destructive)
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:

Detects the vault for the current project (or uses default)
Warns if the server is running
Runs muninn dream --dry-run --scope <vault> to preview changes
Shows the preview and asks for confirmation
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