# Mira > Long-term memory system for LLMs with optimal context budget allocation, approximation guarantees, and temporal coherence. 100% local, deterministic, O(n log n). - **Type:** MCP server - **Install:** `agentstack add mcp-benoitpetit-mira` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [benoitpetit](https://agentstack.voostack.com/s/benoitpetit) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [benoitpetit](https://github.com/benoitpetit) - **Source:** https://github.com/benoitpetit/mira - **Website:** https://devbyben.fr ## Install ```sh agentstack add mcp-benoitpetit-mira ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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**](https://github.com/benoitpetit/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](https://github.com/benoitpetit) - **Source:** [benoitpetit/mira](https://github.com/benoitpetit/mira) - **License:** MIT - **Homepage:** https://devbyben.fr Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-benoitpetit-mira - Seller: https://agentstack.voostack.com/s/benoitpetit - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.