README.md
Local-first persistent memory infrastructure for coding agents
Muninn
"Muninn flies each day over the world to bring Odin knowledge of what happens." — Prose Edda
Local-first persistent memory infrastructure for coding agents and MCP-compatible tools.
Muninn provides deterministic, explainable memory retrieval with robust transport behavior and production-grade operational controls. Designed for long-running development workflows where continuity, auditability, and measurable quality matter — across sessions, across assistants, and across projects.
🚩 Status
Current Version: v3.24.0 (Phase 26 COMPLETE) Stability: Production Beta Test Suite: 1422+ passing, 0 failing
What's New in v3.24.0
- Cognitive Architecture (CoALA): Integration of a proactive reasoning loop bridging memory with active decision-making.
- Knowledge Distillation: Background synthesis of episodic memories into structured semantic manuals for long-term wisdom.
- Epistemic Foraging: Active inference-driven search to resolve ambiguities and fill information gaps autonomously.
- Omission Filtering: Automated detection of missing context required for successful task execution.
- Elo-Rated SNIPS Governance: Dynamic memory retention system mapping retrieval success to Elo ratings for usage-driven decay.
Previous Milestones
| Version | Phase | Key Feature |
|---|---|---|
| v3.24.0 | 26 | Cognitive Architecture Complete |
| v3.23.0 | 23 | Elo-Rated SNIPS Governance |
| v3.22.0 | 22 | Temporal Knowledge Graph |
| v3.19.0 | 20 | Multimodal Hive Mind Operations |
| v3.18.3 | 19 | Bulk legacy import, NLI conflict detection, uncapped discovery |
| v3.18.1 | 19 | Scout synthesis, hunt mode |
🚀 Features
Core Memory Engine
- Local-First: Zero cloud dependency — all data stays on your machine
- Multimodal: Native support for Text, Image, Audio, Video, and Sensor data
- 5-Signal Hybrid Retrieval: Dense vector · BM25 lexical · Graph traversal · Temporal relevance · Goal relevance
- Explainable Recall Traces: Per-signal score attribution on every search result
- Bi-Temporal Reasoning: Support for "Valid Time" vs "Transaction Time" via Temporal Knowledge Graph
- Project Isolation:
scope="project"memories never cross repo boundaries;scope="global"memories are always available - Cross-Session Continuity: Memories survive session ends, assistant switches, and tool restarts
- Bi-Temporal Records:
created_at(real-world event time) vsingested_at(system intake time)
Memory Lifecycle
- Elo-Rated Governance: Dynamic retention driven by retrieval feedback (SNIPS) and usage statistics
- Consolidation Daemon: Background process for decay, deduplication, promotion, and shadowing — inspired by sleep consolidation
- Zero-Trust Ingestion: Isolated subprocess parsing for PDF/DOCX to neutralize document-based exploits
- ColBERT Multi-Vector: Native Qdrant multi-vector storage for MaxSim scoring
- NL Temporal Query Expansion: Natural-language time phrases ("last week", "before the refactor") parsed into structured time ranges
- Goal Compass: Retrieval signal for project objectives and constraint drift
- NLI Conflict Detection: Transformer-based contradiction detection (
cross-encoder/nli-deberta-v3-small) for memory integrity - Bulk Legacy Import: One-click ingestion of all discovered legacy sources (batched, error-isolated) via dashboard or API
Operational Controls
- MCP Transport Hardening: Framed + line JSON-RPC, timeout-window guardrails, protocol negotiation
- Runtime Profile Control:
get_model_profiles/set_model_profilesfor dynamic model routing - Profile Audit Log: Immutable event ledger for profile policy mutations
- Browser Control Center: Web UI for search, ingestion, consolidation, and admin at
http://localhost:42069 - OpenTelemetry: GenAI semantic convention tracing (feature-gated via
MUNINN_OTEL_ENABLED)
Multi-Assistant Interop
- Handoff Bundles: Export/import memory checkpoints with checksum verification and idempotent replay
- Legacy Migration: Discover and import memories from prior assistant sessions (JSONL chat history, SQLite state) — uncapped provider limits
- Bulk Import:
POST /ingest/legacy/import-allingests all discovered sources in batches of 50 with per-batch error isolation - Hive Mind Federation: Push-based low-latency memory synchronization across assistant runtimes
- MCP 2025-11 Compliant: Full protocol negotiation, lifecycle gating, schema annotations
Quick Start
git clone https://github.com/wjohns989/Muninn.git
cd Muninn
pip install -e .
Set the auth token (shared between server and MCP wrapper):
# Windows (persists across sessions)
setx MUNINN_AUTH_TOKEN "your-token-here"
# Linux/macOS
export MUNINN_AUTH_TOKEN="your-token-here"
Start
Tools (2)
get_model_profilesRetrieves current model routing profiles.set_model_profilesUpdates dynamic model routing profiles.Environment Variables
MUNINN_AUTH_TOKENrequiredAuthentication token shared between server and MCP wrapperMUNINN_OTEL_ENABLEDEnables OpenTelemetry GenAI semantic convention tracingConfiguration
claude_desktop_config.json
{"mcpServers": {"muninn": {"command": "python", "args": ["/path/to/Muninn/main.py"], "env": {"MUNINN_AUTH_TOKEN": "your-token-here"}}}}Try it
→Search my memory for the architectural decisions made during the last refactor of the authentication module.
→Find all project-scoped memories related to the API integration and summarize the current constraints.
→Import my legacy chat history from the previous project session into the current memory store.
→What are the outstanding tasks or unresolved ambiguities identified in my recent development sessions?