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)    │  │
│  └──────────────────────────────────────────────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────────────────────────────────────────────┘

---

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)

Configuration	Retrieval Channels	Hit@1	Hit@3	Hit@5	MRR	NDCG@5
Config A (Dense Only)	vector	0.574	0.796	0.833	0.679	0.718
Config B (Sparse Only)	fts	0.259	0.259	0.259	0.259	0.259
Config C (Graph Only)	graph	0.222	0.518	0.593	0.353	0.413
Config D (Dense + Sparse)	vector + fts	0.574	0.796	0.833	0.679	0.718
Config E (Mnemo Full 3-Channel)	vector + fts + graph	0.667	0.815	0.833	0.736	0.761

Quality by Query Complexity (MRR / NDCG@5)

Configuration	Semantic Intent (15)	Code Identifiers (15)	Graph Dependencies (16)	Bitemporal History (8)
Config A (Dense Only)	0.439 / 0.490	1.000 / 1.000	0.554 / 0.627	1.000 / 1.000
Config B (Sparse Only)	0.000 / 0.000	0.867 / 0.867	0.000 / 0.000	0.250 / 0.250
Config C (Graph Only)	0.000 / 0.000	0.519 / 0.612	0.552 / 0.655	0.062 / 0.125
Config D (Dense + Sparse)	0.439 / 0.490	1.000 / 1.000	0.554 / 0.627	1.000 / 1.000
Config E (Mnemo Full 3-Channel)	0.439 / 0.490	1.000 / 1.000	0.708 / 0.771	1.000 / 1.000

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:

Operation	Scale (Facts)	Median (p50)	95th Percentile (p95)	Throughput (ops/sec)
Ingestion (mnemo_remember)	500	1.15 ms	1.95 ms	~870 ops/s
Sparse Search (FTS5 BM25)	500	0.16 ms	0.35 ms	~6,200 ops/s
Dense Search (Cosine Vector)	500	0.38 ms	0.65 ms	~2,600 ops/s
Graph Traversal (Recursive CTE)	500	0.35 ms	0.82 ms	~2,850 ops/s
Full Hybrid Search (3-Channel RRF)	500	1.40 ms	2.10 ms	~715 ops/s
Full Hybrid Search (3-Channel RRF)	20,000	5.56 ms	7.90 ms	~180 ops/s
Incremental AST Scan (Unchanged)	Repo	1.41 ms	2.20 ms	~710 ops/s

---

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

Tool Name	Parameters	Description
mnemo_remember	text: str category: str = "general" target_fact_id: str = "" [opt] force_op: str = "" [opt] entity_identifiers: list[str] = [] [opt]	Ingests architectural decision or fact through AUDN classifier. Auto-links mentioned AST entities via SHA-256 hashes. Agent payload capped at 32k chars.
mnemo_search	query: str limit: int = 5 category: str = "" [opt] tier: str = "" [opt] valid_at: float = None [opt] as_of: str | float = None [opt]	3-Channel Hybrid Retrieval (Vector + FTS5 + Graph via RRF). Supports historical reconstruction via RFC3339 as_of.
mnemo_acknowledge_usage	fact_ids: list[str]	Reinforces salience and increments stability count ($n$) for facts that successfully aided the agent in completing a task.
mnemo_invalidate	fact_id: str reason: str = "outdated"	Soft-deletes a fact by setting valid_end = now. Protected core/developer memories cannot be invalidated by agents.
mnemo_inspect	fact_id: str	Retrieves full bitemporal metadata, link hashes, tier, salience, and provenance audit for a specific fact.
mnemo_get_debt_ledger	(none)	Lists accumulated architectural memory debt (stale facts from AST drift, decayed working memories, orphan links).
mnemo_scan_project	path: str = "." force: bool = False	Triggers incremental AST scan of repository. Protected against path traversal and symlink escapes.

Caution

Administrative Security Boundary: The physical erasure operation (mnemo_purge) is intentionally excluded from MCP exposure to prevent adversarial or compromised LLM subagents from permanently purging audit trails or leaked secrets. Physical purge must be performed by a human operator via the CLI:

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.