Mnemion

Mnemion

Persistent AI Memory · Hybrid Retrieval · Trust Lifecycle · Behavioral Protocol

Mnemion is a production-grade AI memory system built by PerseusXR. Give any AI a persistent, searchable memory Anaktoron — hybrid lexical-semantic retrieval, a human-like trust lifecycle, background contradiction detection, intelligent LLM lifecycle management, and a behavioral protocol so your AI actually knows to use its memory.

Inspired by the original mempal project. Built far beyond it.

[![][version-shield]][release-link] [![][python-shield]][python-link] [![][license-shield]][license-link]

Architecture · Quick Start · Moat · Source Wiki · Obsidian · MCP Tools · Studio · System Prompt · Auto-Save Hooks · Librarian · Anaktoron Sync · Benchmarks · Changelog

---

Architecture Overview

graph TD
    subgraph Clients [MCP Clients & IDEs]
        Codex[OpenAI Codex CLI]
        Antigravity[Antigravity / Gemini CLI]
        Claude[Claude Code / Cursor]
    end

    subgraph Studio [Dashboard]
        WebUI[Mnemion Studio Frontend<br/>React + Vite + Tailwind]
        Backend[FastAPI Backend]
    end

    subgraph Server [Mnemion Core]
        MCPServer[MCP Server<br/>JSON-RPC Loop]
        CLI[Mnemion CLI]
    end

    subgraph Database [Shared Local Database - Anaktoron]
        Chroma[ChromaDB Vector Store<br/>Semantic Search & SIGReg]
        SQLite[SQLite3 Database<br/>FTS5 Lexical Index<br/>Temporal Graph & Core Memories]
    end

    subgraph LLM [LLM Backend]
        Ollama[Ollama / vLLM / LM Studio<br/>Async Contradiction Scanning]
    end

    %% Client Interactions
    Codex <-->|JSON-RPC via stdin/stdout| MCPServer
    Antigravity <-->|JSON-RPC via stdin/stdout| MCPServer
    Claude <-->|JSON-RPC via stdin/stdout| MCPServer

    %% Core Operations
    MCPServer <-->|Query / Write| Chroma
    MCPServer <-->|Query / Write| SQLite
    CLI <-->|Bulk Ingest / Sweep| Chroma
    CLI <-->|Bulk Ingest / Sweep| SQLite

    %% Studio Operations
    WebUI <-->|HTTP / REST| Backend
    Backend <-->|Query / Write| Chroma
    Backend <-->|Query / Write| SQLite
    Backend -->|Auto-Connect Config| Codex
    Backend -->|Auto-Connect Config| Antigravity
    Backend -->|Auto-Connect Config| Claude

    %% Background LLM Checks
    MCPServer -->|Async Daemon Thread| Ollama
    SQLite <-->|Pre-computed Trust & Conflicts| MCPServer

---

Architecture Layers

1. Hybrid Lexical-Semantic Retrieval (hybrid_searcher.py)

Vector search alone has a "Vector Blur" problem: exact technical identifiers (git hashes, function signatures, hex addresses) carry low semantic weight and get outranked by thematically related but wrong results.

Mnemion runs a SQLite FTS5 lexical mirror alongside ChromaDB, fusing both result sets using Reciprocal Rank Fusion (RRF). Benchmarked result:

Metric	Vector Only	Hybrid RRF	Improvement
Mean Reciprocal Rank (MRR)	0.5395	0.8833	+63.7%
Hit@1 Accuracy	46.7%	80.0%	+33.3%

4,344-drawer production Anaktoron, 15-target Gold Standard. Reproduce: python eval/benchmark.py

2. Memory Trust Layer (trust_lifecycle.py + contradiction_detector.py)

Human memory has a lifecycle — beliefs get superseded, contradicted, verified. Without this, an AI memory system accumulates conflicting facts indefinitely.

Every drawer now has a trust record:

current → superseded   (newer fact wins — old one is kept but excluded from search)
current → contested    (conflict detected — surfaces with ⚠ warning in search)
contested → resolved   (AI or user picks the winner)
any → historical       (drawer deleted — ghost record remains for audit)

Contradiction detection runs in the background when a new drawer is saved:

• Stage 1: Fast LLM judge — compares new drawer against top-k similar existing drawers. Auto-resolves if confidence ≥ 0.8.
• Stage 2: For ambiguous cases — pulls additional Anaktoron context, second LLM pass to resolve.

Save speed: unchanged (detection is async, daemon threads). Fetch speed: improved (superseded memories excluded by default, confidence weights scores).

Works with any local LLM — configure once with mnemion llm setup (Ollama, LM Studio, vLLM, or any OpenAI-compatible endpoint). No cloud calls, no API key. Disable entirely for zero-overhead saves.

3. Intelligent LLM Lifecycle (llm_backend.py — ManagedBackend)

Running a local LLM (vLLM, Ollama, etc.) for contradiction detection shouldn't require manual startup. ManagedBackend wraps any OpenAI-compatible server with full lifecycle management:

• Auto-start on demand — when contradiction detection fires and the server is down, it starts automatically (WSL or native Linux)
• Auto-stop on idle — after configurable idle timeout (default: 5 minutes), the server shuts down to free GPU memory
• Auto-restart on failure — 3 consecutive chat failures trigger a stop + relaunch + wait cycle
• Manual control — mnemion llm start / mnemion llm stop for explicit lifecycle management

Configure during setup:

mnemion llm setup
# → prompts for start_script (e.g. wsl:///home/user/run_vllm.sh), idle_timeout

4. Behavioral Protocol Bootstrap (SYSTEM_PROMPT.md + MCP prompts)

The hardest problem with AI memory isn't storage — it's ensuring the AI knows to use it. Without explicit instructions, an AI connected to mnemion will ignore it entirely.

This fork solves it with three layers:

Layer	Mechanism	Covers
MCP tool descriptions	mnemion_status description says "CALL THIS FIRST"	All MCP clients
MCP prompts capability	prompts/get?name=mnemion_protocol returns the full behavioral rules	Clients supporting MCP prompts
SYSTEM_PROMPT.md	Copy-paste template for every major AI platform	Claude Code, Cursor, ChatGPT, Gemini

The result: any AI connecting to this MCP server receives clear instructions on when (startup, before answering, when learning, at session end), which tool to call, and why.

5. AI-Independent Auto-Save Hook (hooks/mnemion_save_hook.py)

The original hook asks the AI to save memories at intervals — which means it depends on the AI cooperating. We replaced it with a Python hook that:

• Reads the transcript directly
• Extracts memories via general_extractor.py (pure patterns, no LLM)
• Saves to ChromaDB with hash-based dedup
• Triggers a git sync in the background
• Always outputs {} — never blocks the AI, never interrupts the conversation

Covers: decisions, preferences, milestones, problems, emotional notes.

6. Librarian — Daily Background Tidy-Up (librarian.py)

Even with contradiction detection running per-save, a Anaktoron accumulates noise over time: misclassified rooms, redundant drawers, entity facts buried in prose but never extracted into the knowledge graph. The Librarian runs as a daily background job that reviews every drawer that has never been verified or challenged.

For each drawer it performs three tasks using the configured local LLM:

Task	What it does
Contradiction scan	Checks the drawer against similar Anaktoron content for conflicts; flags contested if found
Room re-classification	Suggests a better wing/room if the current taxonomy is wrong; moves silently
KG triple extraction	Pulls structured facts (subject → predicate → object) from the drawer's text and adds them to the knowledge graph

The Librarian is cursor-based — it saves its position to ~/.mnemion/librarian_state.json and resumes where it left off. It processes one drawer at a time with an 8-second inter-request sleep to stay polite to the local GPU. At 3 AM via Windows Task Scheduler (or cron) it's invisible during working hours.

# Run manually
mnemion librarian

# Dry-run — read-only preview; still uses the configured LLM for LLM-backed tasks
mnemion librarian --dry-run

# Schedule daily 3 AM run (Windows)
powershell -ExecutionPolicy Bypass -File scripts/setup_librarian_scheduler.ps1

Requires the LLM backend to be configured (mnemion llm setup). Without it, the Librarian skips LLM tasks and only runs room re-classification using the local rule-based detector.

7. Anaktoron Sync (sync/SyncMemories.ps1)

The ChromaDB Anaktoron is ~860MB — too large for git. The sync system:

1. Exports all drawer content to archive/drawers_export.json (~24MB)
2. Commits and pushes the JSON to your private memory repo
3. Runs automatically via Task Scheduler (Windows) or cron (macOS/Linux)

On a new machine: git clone <repo> → mnemion restore archive/drawers_export.json → full Anaktoron restored.

8. LeWorldModel (LeWM) Upgrade — Self-Organizing Intelligence

Based on LeWorldModel (Maes et al., 2026), Mnemion uses SIGReg to prevent embedding collapse and an LSTM-based predictor for proactive context retrieval.

Feature	What it does	Verified Impact
Latent Grooming (SIGReg)	Uses the Epps-Pulley test statistic to spread embeddings across the latent manifold, preventing cluster collapse.	+40% Recall@5 (0.600→1.000 in A/B benchmark)
Predictive Context (JEPA)	LSTM-based predictor tracks session latent trajectories. Use mnemion_predict_next to anticipate the next information need.	Proactive pre-fetch
Latent Health Suite	Diagnostic tools (benchmarks/latent_health.py) to measure Anaktoron density and Gaussian normality.	Monitoring

A/B benchmark: 2,000-drawer Anaktoron, 20 planted needles. Raw ChromaDB R@5=0.600, SIGReg groomed R@5=1.000. Reproduce: python tests/benchmarks/bench_ab_test.py

Enable grooming in ~/.mnemion/config.json:

"lewm": {
  "groom_iterations": 10,
  "sigreg_weight": 0.1
}

9. Cognitive Reconstruction, Memory Guard, and Moat Evaluation

Mnemion now adds a structured cognitive graph above raw vector drawers. mnemion consolidate extracts proposition, causal, preference, objective, event, and prescription units from stored drawers. mnemion reconstruct searches those units first, follows recurring topic tunnels, and only then hydrates raw drawers with an evidence trail.

The security path is part of the memory system, not an afterthought. mnemion memory-guard scan detects obvious instruction-injection and privacy-exfiltration memories, mnemion memory-guard status shows aggregate risk counts without dumping content, mnemion memory-guard review --limit 20 --json returns drawer IDs/risk types/scores/timestamps only, and mnemion memory-guard quarantine --drawer-id <id> --apply is the explicit opt-in path for moving a reviewed drawer into the quarantined trust state.

The moat harness is executable:

mnemion consolidate --limit 1000
mnemion reconstruct "why did the pricing dashboard move to GraphQL?"
mnemion memory-guard scan
mnemion memory-guard status
mnemion memory-guard review --limit 20 --json
mnemion memory-guard quarantine --drawer-id drawer_... --dry-run
mnemion eval moat --suite all

For the design thesis and operational workflow, see docs/moat.md.

10. Obsidian Owned Mirror (obsidian.py)

Mnemion can project the full Anaktoron architecture into an Obsidian vault without making Obsidian the database. The mirror is one-way and Mnemion-owned: Chroma, SQLite trust state, the knowledge graph, cognitive units, and memory-guard findings

This is a shortened preview. Read the full README at the source.