Mira

MIRA

### Memory with Information-theoretic Relevance Allocation

Long-term Memory System for LLMs with Optimal Context Budget Allocation

[](https://golang.org/) [](LICENSE) []() []()

*100% Local • Deterministic (embedding variance

---

Table of Contents

• [What is MIRA?](#what-is-mira)
• [The Memory Revolution for LLMs](#the-memory-revolution-for-llms)
• [How It Works](#how-it-works)
• [3-Level Architecture (T0/T1/T2)](#3-level-architecture-t0t1t2)
• [The CBA Algorithm](#the-cba-algorithm)
• [Enhanced Recall Pipeline](#enhanced-recall-pipeline)
• [Causal Graph](#causal-graph)
• [Installation](#installation)
• [Quick Start](#quick-start)
• [Configuration](#configuration)
• [MCP API](#mcp-api)
• [Performance](#performance)
• [Technical Architecture](#technical-architecture)
• [Development](#development)
• [Changelog](#changelog)

---

What is MIRA?

MIRA is a sophisticated long-term memory system designed specifically for Large Language Models (LLMs). Unlike traditional memory systems that simply store and retrieve, MIRA uses information-theoretic allocation to optimize every token in the context window.

SOUL Extension: Identity Preservation

MIRA answers "What does the agent know?" But a complete agent needs more: it needs to know "Who is it?"

SOUL (System for Observed Unique Legacy) is an optional identity extension for MIRA that captures, stores, and recalls the personality, voice, and values of AI agents across sessions and model changes.

To embed SOUL in MIRA, start with --with-soul or set soul.enabled: true in config. When enabled, SOUL provides 8 additional MCP tools (16 total) for:

• Capturing identity from conversations
• Recalling identity prompts for LLM context injection
• Detecting identity drift after model changes
• Generating reinforcement prompts after model swaps

SOUL is opt-in and disabled by default. MIRA works perfectly alone (8 tools). To activate SOUL, use --with-soul flag or set soul.enabled: true in config.yaml. When enabled, they share the same SQLite database.

| Configuration | Tools | What it answers | |---------------|-------|-----------------| | MIRA only | 8 mira_* | "What does the agent know?" | | MIRA + SOUL | 16 mira_* + soul_* | "What does the agent know?" + "Who is the agent?" |

The Problem MIRA Solves

Modern LLMs suffer from a fundamental problem: the context window is limited (4K-128K tokens), but conversations and projects span thousands of interactions. How do we decide what to keep in context?

Traditional approaches fail:

• [x] Simple RAG: Retrieval based only on similarity, ignores information density
• [x] Sliding window: Loses critical information from the beginning
• [x] Static summarization: Doesn't adapt to the current query
• [x] Basic Vector DB: O(n) complexity, no budget management

MIRA provides the solution:

• [+] Context Budget Allocation: Optimizes every token across 6 dimensions
• [+] Information Density: Prioritizes memory-rich facts
• [+] Temporal Coherence: Maintains narrative continuity
• [+] Causal Graph: Understands cause-effect relationships
• [+] O(log n) Search: HNSW for millions of memories
• [+] Clean Architecture: Maintainable, testable, extensible

---

The Memory Revolution for LLMs

What MIRA Brings New

1. Information Allocation (CBA)

Instead of simply retrieving the "most similar", MIRA solves an optimization problem under constraint: maximize useful information within a fixed token budget.

Score(m) = Relevance × Density × Recency × (1-Overlap) × Coherence × CausalPenalty

2. Triple Representation (T0/T1/T2)

Each memory exists in 3 forms for different uses:

• T0 (Verbatim): Full original text
• T1 (Fingerprint): Structured extracted facts (~15% of tokens)
• T2 (Embedding): 384D semantic vector for search

3. Integrated Causal Graph

Automatic detection of relations (BECAUSE, TRIGGERED, CONTRADICTS, UPDATES, RESOLVES) to trace reasoning chains.

4. Adaptive Rendering

Based on remaining budget, MIRA intelligently chooses the detail level:

• Header (5 tokens): Reference only
• Fingerprint (~15% tokens): Essential facts
• Verbatim (100% tokens): Full text

---

How It Works

Overview Flow

┌─────────────────────────────────────────────────────────────────────────┐
│                         MEMORY STORAGE                                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   Input Text         T1,T2 Extraction        Atomic Storage             │
│   ┌─────────┐       ┌──────────────┐          ┌─────────────────┐       │
│   │"We      │──────→│  Fingerprint │─────────→│  SQLite + HNSW  │       │
│   │ decided │       │  + Embedding │          │  (WAL Mode)     │       │
│   │ to use  │       └──────────────┘          └─────────────────┘       │
│   │PostgreSQL"            │                       │                     │
│   └─────────┘             ↓                       ↓                     │
│                        T1: {                 Vector Index               │
│                          - decision: "PostgreSQL"  ℝ³⁸⁴                 │
│                          - rejected: ["MySQL",     HNSW O(log n)        │
│                                      "MongoDB"]                         │
│                          - reason: ["ACID", "Exp"]                      │
│                          - type: DECISION                               │
│                                                                         │
│                         T2: [0.23, -0.15, 0.89, ...] 384D               │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│                         RETRIEVAL (RECALL)                              │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   Query "Why PostgreSQL?"                                               │
│       │                                                                 │
│       ▼                                                                 │
│   ┌─────────────┐    ┌─────────────────┐    ┌──────────────────────┐    │
│   │ Embedding   │───→│  HNSW Search    │───→│  Composite Scoring   │    │
│   │ Query       │    │  Top 100        │    │  CBA Algorithm       │    │
│   │ ℝ³⁸⁴        │    │  O(log n)       │    │  O(n log n)          │    │
│   └─────────────┘    └─────────────────┘    └──────────────────────┘    │
│                                                        │                │
│                                                        ▼                │
│                                              Greedy Selection           │
│                                              with 4000 token budget     │
│                                                        │                │
│       ┌────────────────────────────────────────────────┘                │
│       ▼                                                                 │
│   Optimized Result:                                                     │
│   ┌───────────────────────────────────────────────────────────────┐     │
│   │ [1] Fingerprint: "PostgreSQL Decision (ACID, expertise)" 45tk │     │
│   │ [2] Verbatim: "Meeting 04/15 - DB discussion..."         120tk│     │
│   │ [3] Header: "Sprint 5 deadline"                           5tk │     │
│   │ ...                                                           │     │
│   │ Total: 3987/4000 tokens (99.7% utilization)                   │     │
│   └───────────────────────────────────────────────────────────────┘     │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

The CBA Composite Score

For each candidate memory, MIRA calculates a multidimensional score:

┌─────────────────────────────────────────────────────────────────────┐
│                     CBA SCORE FORMULA                               │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   S(m) = ρ × δ × η × (1-σ) × τ × χ × 𝟙[ρ>θ]                         │
│                                                                     │
│   where:                                                            │
│   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━    │
│   ρ (rho)    = Semantic Relevance      cos(embedding_m, embedding_q)│
│   δ (delta)  = Information Density     sigmoid(facts/√tokens)       │
│   η (eta)    = Temporal Weight         exp(-λ × age)                │
│   σ (sigma)  = Max Overlap             sim(m, already_selected)     │
│   τ (tau)    = Session Boost           +20% if same session         │
│   χ (chi)    = Causal Penalty          avoids long chains           │
│   𝟙[ρ>θ]     = Relevance Threshold     eliminates if ρ  0.6}                                     │
│     If C' = ∅: C' ← top-5(C) by ρ                                  │
│                                                                     │
│  4. INITIAL SCORING                                                 │
│     For each c ∈ C':                                                │
│        c.score ← ρ(c) × δ_sigmoid(c) × η_recency(c)                 │
│                                                                     │
│  5. GREEDY SELECTION WITH DYNAMIC RENORMALIZATION                   │
│     S ← ∅, tokens_used ← 0                                         │
│     PQ ← MaxHeap(C')  # by initial score                            │
│                                                                     │
│     WHILE PQ ≠ ∅ AND tokens_used  adjusted_score:                       │
│           Push(PQ, c) with adjusted_score                           │
│           continue                                                  │
│                                                                     │
│        # Determine mode based on REMAINING BUDGET                   │
│        remaining ← B - tokens_used                                  │
│        mode ← ChooseMode(c, remaining)                              │
│        cost ← CalculateCost(c, mode)                                │
│                                                                     │
│        # Downgrade if necessary                                     │
│        If tokens_used + cost > B:                                   │
│           mode ← Downgrade(mode)  # Verbatim → Fingerprint → Header │
│           cost ← Recalculate(mode)                                  │
│           If tokens_used + cost > B: continue                       │
│                                                                     │
│        S ← S ∪ {c}, tokens_used ← tokens_used + cost                │
│                                                                     │
│  6. RETURN S sorted by descending score                             │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Adaptive Render Modes

| Remaining Budget | Mode | Tokens | Content | | ---------------- | ----------- | ------ | -------------------- | |

MIRA - Memory with Information-theoretic Relevance Allocation

"Memory is the sap of artificial intelligence."

[API Reference](docs/API_REFERENCES.md) • [Changelog](CHANGELOG.md)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: benoitpetit
• Source: benoitpetit/mira
• License: MIT
• Homepage: https://devbyben.fr

Install and usage instructions live in the source repository linked above.