Mimir

Persistent memory for AI agents. Structured entity model. SQLite + FTS5 + hybrid vector search. MCP-native. Fully local.

What is Mimir?

Mimir is a lightweight MCP JSON-RPC 2.0 stdio server that gives AI agents durable
memory across sessions. Agents store structured entities, journal their decisions,
manage transient state, generate embeddings, query with hybrid search, and ingest
external data — all through 27 MCP tools.

It uses SQLite with FTS5 + dense vector search across three tables: entities
(structured, idempotent), journal (append-only event log), and state (key-value
with TTL). Optional Ollama integration enables RAG (mimir_ask) and embedding
generation (mimir_embed). A built-in web dashboard provides visual exploration.

Works with any MCP host: Claude Desktop, Cursor, OpenClaw, Hermes Agent, Perseus, etc.

Quick Start

# Build from source
git clone https://github.com/Perseus-Computing-LLC/mimir.git
cd mimir
cargo build --release

# Linux/macOS: use cargo install to avoid macOS security kill (Killed: 9)
cargo install --path .

# Or copy manually (Linux only — macOS will kill the unsigned binary)
cp target/release/mimir ~/.local/bin/

# Or download the binary
curl -sSL https://github.com/Perseus-Computing-LLC/mimir/releases/download/v1.0.0/mimir-v1.0.0-linux-x86_64 -o mimir
chmod +x mimir && mv mimir ~/.local/bin/

Requirements: Rust 1.70+ (stable), a C compiler (rusqlite bundles SQLite).

Install

# Python client
pip install mimir

# Or download the standalone binary (no Python needed)
curl -L https://github.com/Perseus-Computing-LLC/mimir/releases/latest/download/mimir-linux-x86_64 -o mimir
chmod +x mimir
./mimir --db ./memory.db

Quickstart

from mimir import MimirClient

client = MimirClient("./memory.db")
client.remember("Hello world — my first persistent memory!", category="demo")
results = client.recall("first memory")
print(results[0].content)
# "Hello world — my first persistent memory!"

Why Mimir vs Alternatives

Mimir is for teams that want production memory without infrastructure — no Postgres, no Docker, no cloud services. Just one binary.

Features

Hybrid Search

• FTS5 keyword search with LIKE fallback and stemming expansion
• Dense vector search via cosine similarity on stored embeddings
• Reciprocal Rank Fusion (RRF) — combine keyword + vector results
• Query expansion — Porter stemming variants for broader recall

RAG & Embeddings

• mimir_ask — natural language Q&A over stored memories via Ollama
• mimir_embed — generate and store dense vectors via Ollama /api/embed
• Supports single-entity and batch-category embedding

Encryption

• AES-256-GCM transparent encryption for entity body_json
• Opt-in via --encryption-key flag
• mimir keygen subcommand for key generation
• FTS5 index stays plaintext for search

Web Dashboard

• Built-in Axum HTTP server (mimir serve --web --port 8767)
• Dark-themed dashboard with search, entity table, vis.js graph, timeline
• Default bind: 127.0.0.1 (use --web-bind 0.0.0.0 to expose)
• Separate SQLite connection in WAL mode for concurrent reads

External Connectors

• GitHub issues connector — ingest issues/PRs by repo, rate-limit aware
• File watcher — scan directories for .md/.txt/.json files with content-hash dedup
• mimir_ingest — trigger connector syncs, dry-run preview
• YAML-based connector config via --connectors-config

Data Lifecycle

• mimir_prune — bulk archive by category, decay threshold, or age
• Ebbinghaus decay with retrieval boosts and configurable archiving
• Near-duplicate detection via trigram similarity
• Vault export/import — markdown files with YAML frontmatter

MCP Tools (v1.0.0 — 27 tools)

Entity tools

Search & RAG

Journal tools

State tools

Management

Graph & analysis

Vault

CLI

mimir serve --db /data/mimir.db
mimir serve --web --port 8767 --encryption-key ~/.mimir/secret.key
mimir serve --llm-endpoint http://localhost:11434/api/generate --llm-model llama3
mimir serve --connectors-config ~/.mimir/connectors.yaml
mimir keygen --key-file ~/.mimir/secret.key
mimir migrate --from old.db --to new.db

Flags

MCP Configuration

{
  "mcpServers": {
    "mimir": {
      "command": "mimir",
      "args": ["--db", "/home/YOU/.mimir/data/mimir.db"]
    }
  }
}

Perseus

mimir:
  enabled: true
  transport: "stdio"
  command: ["mimir", "--db", "~/.mimir/data/mimir.db"]
  timeout_s: 30.0
  merge_strategy: "local_first"
  fallback_to_local: true
  context_categories: ["decision", "architecture", "convention"]
  context_limit: 10

Connector Config

connectors:
  github:
    enabled: true
    token: "${GITHUB_TOKEN}"
    repos:
      - Perseus-Computing-LLC/mimir
      - Perseus-Computing-LLC/perseus
    days_past: 90
    max_items_per_repo: 500
  file_watcher:
    enabled: true
    paths:
      - ~/Documents/notes
      - ~/projects
    extensions:
      - .md
      - .txt
    debounce_ms: 1500

Key Properties

• 27 MCP tools — full CRUD, search, RAG, embeddings, connectors, lifecycle
• Hybrid search — FTS5 + dense vectors + RRF fusion
• Encryption at rest — AES-256-GCM, opt-in, transparent
• Web dashboard — built-in, browser-based, dark theme
• Zero runtime deps — static binary with bundled SQLite
• No LLM required — core operations work offline; Ollama optional for RAG/embeddings
• Single-file database — easy backup, copy, inspect
• Fully offline — no telemetry, no API calls, no network by default

License

MIT — see LICENSE.