🧠 Mnemo Agent Memory

A Lightweight, High-Precision, Zero-Token-Waste Memory Engine, Knowledge Graph, and Notes System Built Exclusively for AI Coding Agents via MCP.

📖 Table of Contents

• The Core Problem (Why Mnemo Exists)

• Key Architectural Pillars

• System Architecture

• Core Features & Capabilities

• MCP Tools Reference

• CLI Usage & Commands

• Configuration & Environment Variables

• Project ID Auto-Locking Mechanism

• License

Related MCP server: memento

🎯 The Core Problem (Why Mnemo Exists)

As AI coding agents (such as Antigravity, Claude, Cursor, and Cline) work on complex codebases, they encounter three fundamental limitations:

1. Context Window Contamination & Token Waste:
   Traditional agent workflows perform full-file reads (cat, read_file from line 1) or broad grep searches. This floods the model's context window with irrelevant lines, depletes context budgets rapidly, increases API costs by up to 600%, and causes "context drift" where the agent forgets earlier architectural decisions.

2. Heavy Python Ecosystem Overhead:
   Existing agent memory frameworks rely heavily on Python stacks (LangChain, ChromaDB, PyTorch, C++ bindings). In modern JavaScript/TypeScript agent environments, running Python subprocesses creates heavy memory footprints, slow startup times, and complex environment management issues.

3. Volatile Project Identification:
   Naïve storage fallback mechanisms identify projects dynamically based on current working directories or missing config files. When a project name changes or a config file is created midway, historical memories get orphaned in different storage namespaces.

Mnemo solves all three problems at the root. It provides a 100% pure Node.js memory engine that operates over the Model Context Protocol (MCP), enforces a strict Zero-Token-Waste Protocol, auto-locks project identity, and mirrors all memories into human-readable Markdown notes and Obsidian knowledge graphs.

⚡ Key Architectural Pillars

1. 🛡️ Zero-Token-Waste Protocol

Mnemo mandates line-range inspection (file_info) and targeted hybrid recall before any broad file reading. By fetching AST skeletons, line coordinates (startLine to endLine), and vector-relevance scores, Mnemo cuts token consumption by up to 65% while keeping precision at 100%.

2. 🔒 Auto-Lock Project ID

To eliminate storage drift, Mnemo automatically persists a mnemo.json file in the workspace root during its first normalization step. Once generated, the Project ID is permanently locked, ensuring absolute memory consistency across developer sessions, folder renames, or structural refactors.

3. 🕸️ Embedded Knowledge Graph & Decay Model

Mnemo maintains a directed persistent Knowledge Graph tracking relationships between concepts, code entities, decision logs, and file structures. It features automatic God Node detection, community clustering, and temporal node decay to archive stale context automatically.

4. 📝 Obsidian Vault Mirroring

All agent memories are saved as standard GitHub-flavored Markdown files. Mnemo includes a real-time Obsidian mirror engine (notes-export / notes-import), allowing developers to view, edit, and search their AI agent's memory bank directly inside Obsidian.

🏗️ System Architecture

flowchart TD
    subgraph Client ["AI Agent / IDE Environment"]
        Agent["AI Coding Agent (Antigravity / Claude / Cursor)"]
    end

    subgraph MCP ["Model Context Protocol Interface"]
        Server["Mnemo MCP Server (stdio / HTTP)"]
    end

    subgraph Core ["Mnemo Engine Core (Pure Node.js)"]
        Store["Index & Memory Store"]
        Vec["ONNX Vector Embedding (all-MiniLM-L6-v2)"]
        Graph["Knowledge Graph Engine (Nodes & Edges)"]
        Lock["Project ID Auto-Lock (mnemo.json)"]
    end

    subgraph Storage ["Local Filesystem (~/.mnemo/projects/)"]
        NotesDir["notes/ (*.md)"]
        GraphDir["graph/ (graph.json)"]
        VectorsDir["vectors/ (index.bin)"]
        ObsidianVault["Obsidian Vault Mirror"]
    end

    Agent <-->|"MCP Tools (memory_recall, file_info)"| Server
    Server --> Core
    Core --> Storage
    NotesDir <-->|"Two-way Sync"| ObsidianVault

🚀 Core Features & Capabilities

• Hybrid Vector + Keyword Search: Powered by @xenova/transformers (running all-MiniLM-L6-v2 locally via ONNX without Python) combined with BM25-style keyword matching.

• Smart Memory Auto-Injection: Automatically computes memory similarity and injects relevant context into agent prompts within a configurable token budget (default: 800 tokens).

• AST Skeleton Extraction: file_info parses file structures and outputs function symbols with line coordinates, preventing blind line-by-line reading.

• Web Dashboard: Built-in interactive dashboard to visualize knowledge graphs, view memories, and manage project notes.

• Graph Analytics & Reporting: Generate comprehensive wiki pages, impact reports, and dependency graphs.

🔧 MCP Tools Reference

When running as an MCP Server, Mnemo exposes the following tools to the AI Agent:

💻 CLI Usage & Commands

Mnemo comes with a powerful CLI executable (mnemo).

# View CLI Help
mnemo --help

# Export & sync notes to Obsidian vault
mnemo notes-export

# Import & re-index notes/*.md files
mnemo notes-import

# Knowledge Graph Operations
mnemo graph init          # Initialize graph for current workspace
mnemo graph --extend      # Extract and extend new graph entities
mnemo graph query <name>  # Search specific entity relations
mnemo graph prune         # Clean up stale/archived graph nodes

⚙️ Configuration & Environment Variables

Mnemo can be configured globally via ~/.mnemo/config.json or overriden per-session using Environment Variables (MNEMO_*):

🔒 Project ID Auto-Locking Mechanism

To guarantee 100% session consistency, Mnemo uses a 3-tier deterministic resolution strategy:

1. mnemo.json (Priority 1): Reads name or projectId from workspace root.

2. package.json (Priority 2): Reads name if mnemo.json does not exist yet.

3. Folder Slug Fallback (Priority 3): Uses the last two path segments of the workspace folder.

The Auto-Lock Feature: Upon first run, if mnemo.json is missing, Mnemo calculates the target ID and immediately writes a locked mnemo.json file into the root folder. This prevents Project ID shifts even if package.json is added later or the folder is relocated.

📄 License

Distributed under the MIT License. See LICENSE for details.