Mnemo

Production-Ready Cognitive Long-Term Memory & Code Knowledge Graph for AI Agents
Zero-Infrastructure, Local-First Model Context Protocol (MCP) Server and CLI.

Overview

Mnemo provides persistent, cross-session architectural memory and an autonomous code knowledge graph for AI coding agents. Unlike ephemeral prompt windows or naive vector-only RAG, Mnemo is an autonomous cognitive subsystem built directly on local SQLite.

It links natural-language rules and decisions directly to code entities, automatically detects architectural code drift, models memory retention through codebase activity ticks, executes true bitemporal point-in-time queries, and retrieves knowledge through a 3-channel Reciprocal Rank Fusion (RRF) search engine.

                              ┌──────────────────────────────────────────────┐
                              │             AI Coding Agent / IDE            │
                              └──────────────────────┬───────────────────────┘
                                                     │ MCP Protocol (JSON-RPC)
                                                     ▼
┌────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                             MNEMO SUBSYSTEM                                            │
│                                                                                                        │
│  ┌─────────────────────────┐  ┌─────────────────────────────┐  ┌────────────────────────────────────┐  │
│  │     Zero-Trust Boundary │  │  Fact-Entity Linking & AST  │  │   Activity Spaced Repetition       │  │
│  │   Hardened MCP Server   │  │   Incremental SHA-256 Drift │  │   Activity-Tick Decay (No Time)    │  │
│  └────────────┬────────────┘  └──────────────┬──────────────┘  └─────────────────┬──────────────────┘  │
│               │                              │                                   │                     │
│               ▼                              ▼                                   ▼                     │
│  ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐  │
│  │                                 3-Channel Hybrid Retriever (RRF k=60)                            │  │
│  │                                                                                                  │  │
│  │       Dense Vector (ONNX)       Sparse FTS5 (Code BM25)      Graph CTE (fact_entity_links)       │  │
│  └───────────────────────────────────────────────────┬──────────────────────────────────────────────┘  │
│                                                      │                                                 │
│                                                      ▼                                                 │
│  ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐  │
│  │                     Local SQLite Storage Engine (WAL Mode, BEGIN IMMEDIATE)                      │  │
│  │                                                                                                  │  │
│  │     facts (Bitemporal)  │  entities & relations  │  fact_entity_links  │  debt_ledger (Audit)    │  │
│  └──────────────────────────────────────────────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Related MCP server: Menhir

Core Architectural Pillars

1. Fact-Entity Linking & AST Drift Detection

• Direct Association: Memory facts are not isolated text strings; they are linked to AST entities (modules, classes, methods, functions) via the fact_entity_links table with SHA-256 node hashes (entity_hash_at_link).

• Autonomous Drift Flagging: When code is refactored, modified, or removed, subsequent incremental scans detect hash mismatches or missing nodes, instantly marking linked facts as is_stale = 1 and queueing them in the debt_ledger.

• Stale Penalization: Stale facts suffer an accelerated decay rate ($\lambda_{\text{stale}} = 0.05$) and receive a $0.5\times$ penalty in graph ranking, warning agents against hallucinating outdated architectural patterns.

2. Activity-Based Spaced Repetition

• Activity Ticks over Wall-Clock: Real software development does not decay on a calendar clock. Memory salience $S$ is modeled against project activity ticks (activity_ticks incremented on memory ingestion, scanning, and edits) rather than wall-clock time: $$S = e^{-\frac{\Delta \text{ticks}}{R}}$$ This eliminates artificial amnesia after weekends, holidays, or project pauses.

• Multiplicative Stability Growth: Repeated reinforcement increases retention stability exponentially: $$R = R_0 \cdot (1 + \gamma)^n$$ (where $\gamma = 0.5$ and stability factor $n$ is clamped to prevent numerical overflows).

• Search Without Reinforcement Bias: Merely reading facts during search does not reinforce them. Reinforcement requires explicit agent acknowledgment (mnemo_acknowledge_usage), preventing "rich-get-richer" retrieval loops.

3. True Bitemporal Retrieval (as_of)

• Dual Time Dimensions: Strict separation of:

  • Valid Time (valid_start, valid_end): When the fact was true in the real world / project reality.

  • System / Transaction Time (ingest_start, ingest_end): When the fact was asserted, updated, or retracted in the database.

• Point-in-Time Historical Reconstruction: The as_of parameter allows agents and auditors to travel back in time: mnemo_search("database driver", as_of="2026-01-15T00:00:00Z")

• Audit vs. Logical Erasure: Updates and invalidations never overwrite history silently. Retractions record valid_end = now (logical expiration) or ingest_end = now (correction of error).

4. 3-Channel Hybrid RRF Search

Queries execute simultaneously across three complementary retrieval channels, combined using Reciprocal Rank Fusion (RRF): $$\text{RRF}(d) = \sum_{c \in C} \frac{w_c}{k + r_c(d)} \quad (k=60)$$

1. Dense Vector Channel: FastEmbed / ONNX Runtime local embeddings (bge-small-en-v1.5) capturing semantic concepts and intent.

2. Sparse Lexical Channel (FTS5 BM25): SQLite FTS5 index tokenized with custom code sub-token extraction for camelCase, snake_case, and dotted qualified paths (e.g. UserService.login_by_id).

3. Graph Dependency Channel (Recursive CTE): Recursive traversal starting from referenced symbols through AST relations (CALLS, INHERITS, IMPORTS, DEPENDS_ON), pulling downstream facts linked via fact_entity_links.

5. Enterprise Hardening & Zero-Trust

• Protocol-Level Zero-Trust: All facts written by agents over MCP are strictly constrained to source_type="agent" and confidence=0.75. Protected developer/git memory (tier="core", source_type="human_developer") cannot be overwritten or downgraded by agents.

• Path Traversal & Symlink Defense: AST scanner and MCP tools reject paths outside the repository root and block symlink escapes.

• Deadlock-Free SQLite Concurrency: Write transactions use BEGIN IMMEDIATE with exponential backoff retry; search operations execute in non-blocking WAL read mode (session(readonly=True)).

• Administrative CLI-Only Purge: Physical redaction (mnemo_purge) is excluded from MCP tool exposure and restricted to the terminal CLI (mnemo purge <fact_id> --yes) to prevent adversarial data destruction.

Empirical Benchmarks & Evidence Base

A rigorous, reproducible benchmark suite (benchmarks/run_benchmarks.py) was evaluated over 54 multi-category benchmark queries across small (500 facts), medium (5,000 facts), and large (20,000 facts) synthetic code knowledge bases.

1. Channel Ablation Study (Retrieval Quality)

Quality by Query Complexity (MRR / NDCG@5)

Key Empirical Finding: On Graph Dependency queries (where a top-level component relies on a downstream module containing the rule), standard Dense and Sparse channels miss the relationship (MRR = 0.554). Mnemo's 3-channel RRF boosts MRR to 0.708 (+27.8% relative gain), elevating global Hit@1 from 57.4% to 66.7%.

2. Latency & Throughput Profile

Tested locally with SQLite WAL mode and local ONNX embeddings:

Model Context Protocol (MCP) Specification

Mnemo runs as a standard Model Context Protocol server over stdio, compatible with Claude Desktop, Cursor, Antigravity, and any MCP client.

Active MCP Tools Exposed to Agents

mnemo purge <fact_id> --yes

Installation & Quick Start

1. Installation

Install directly via pip or uv:

pip install mnemo-agentmcp

Or install from source in development mode:

git clone https://github.com/YoruichiYams/mnemo.git
cd mnemo
pip install -e ".[dev]"

Or run directly without installation via uvx:

uvx --from mnemo-agentmcp mnemo --help

2. Configure MCP Client

Add Mnemo to your MCP client configuration:

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "mnemo": {
      "command": "python",
      "args": ["-m", "mnemo.mcp.server"]
    }
  }
}

Cursor / Antigravity (.cursor/mcp.json or mcp_config.json)

{
  "mcpServers": {
    "mnemo": {
      "command": "mnemo",
      "args": ["serve"]
    }
  }
}

Zero-Setup via uvx (Cross-Platform)

{
  "mcpServers": {
    "mnemo": {
      "command": "uvx",
      "args": ["--from", "mnemo-agentmcp", "mnemo", "serve"]
    }
  }
}

3. CLI Management Commands

# Initialize database in current repository
mnemo init

# Scan codebase AST and extract architecture graph
mnemo scan .

# Search memories across channels
mnemo search "database transaction rules"

# Review system health, FTS sync, and schema status
mnemo doctor

# Inspect architectural memory debt
mnemo debt

# Launch dark-minimal interactive knowledge visualizer
mnemo visualize

# Administrative physical purge (human-only)
mnemo purge fact_abc123 --yes

4. Running Benchmarks

# Run complete benchmark suite (small scale)
python -m benchmarks.run_benchmarks --scale small

# Run across all scales (small, medium, large)
python -m benchmarks.run_benchmarks --all-scales

Testing & Quality Assurance

Mnemo maintains a strict 100% automated test pass rate with full test isolation:

# Run complete test suite (141 unit, integration, and security tests)
pytest

# Run security and hardening test suite
pytest tests/test_audit_hardening.py

# Run benchmark smoke tests
pytest tests/test_benchmarks_smoke.py

# Static analysis and style verification
ruff check src tests benchmarks

License

This project is licensed under the MIT License — see the LICENSE file for details.