@kuyavinny/pi-muninn-mem

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).

Install

pi install npm:pi-mcp-adapter        # required dependency
pi install npm:@kuyavinny/pi-muninn-mem

Then reload Pi and run:

/muninn-setup

This single command handles everything:

1. Checks that pi-mcp-adapter is installed
2. Downloads and installs MuninnDB binary (with SHA-256 verification) if 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.

How It Works

Extension (what this package provides)

Hook	What it does
session_start	Health-check MuninnDB, start SSE subscription, notify user
before_agent_start	On first turn: tell LLM to call muninndb_muninn_where_left_off
context	Push contradiction alerts and relevant memory updates via SSE
session_shutdown	Clean up SSE connection
/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 vault
/muninn-vault unlink	Remove vault mapping for current directory
/muninn-dream	Run dream protocol: consolidate, evolve, enrich memories
tool_call	Auto-inject vault parameter into MuninnDB MCP tool calls

MCP tools (provided by MuninnDB via pi-mcp-adapter)

The LLM calls these directly through the mcp gateway:

Tool	Purpose
muninndb_muninn_where_left_off	Restore context from last session — call this first
muninndb_muninn_recall	Semantic search for relevant memories
muninndb_muninn_remember	Store a fact, decision, preference, or observation
muninndb_muninn_decide	Record a decision with rationale and evidence
muninndb_muninn_remember_batch	Store multiple memories at once (max 50)
muninndb_muninn_evolve	Update a memory with new information
muninndb_muninn_consolidate	Merge related memories
muninndb_muninn_contradictions	Check for known contradictions
muninndb_muninn_guide	Get vault-specific usage instructions

Plus 30 more — see 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      → Auto-inject vault param   │
│  /muninn-setup  → Install + configure        │
│  /muninn-remove → Uninstall                  │
└──────────────┬───────────────────┬───────────┘
               │                   │
          SSE subscription     MCP tools
          (REST :8475)      (:8750/mcp)
               │                   │
               └───────┬───────────┘
                       ▼
                    MuninnDB

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

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

• Downloaded binaries are verified with SHA-256 checksums before execution
• Docker/Podman ports bound to 127.0.0.1 only (no network exposure)
• Docker image pinned to v0.5.1 (no :latest)
• MuninnDB initialized with a generated authentication token
• 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 18 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.

Manual MuninnDB Install

If you prefer not to use /muninn-setup, you can install MuninnDB manually:

# Binary (Linux/macOS/Windows, amd64/arm64)
curl -sSL https://github.com/scrypster/muninndb/releases/latest/download/muninn-linux-amd64 -o ~/bin/muninn
chmod +x ~/bin/muninn
muninn init --tool manual --token YOUR_TOKEN --yes --yes
muninn start

# Docker (localhost only)
docker run -d --name muninndb \
  -p 127.0.0.1:8474:8474 -p 127.0.0.1:8475:8475 \
  -p 127.0.0.1:8476:8476 -p 127.0.0.1:8477:8477 \
  -p 127.0.0.1:8750:8750 \
  -v muninndb-data:/data \
  ghcr.io/scrypster/muninndb:v0.5.1

Configuration Files

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

License

MIT