🧠 Mnemo Agent Memory

Zero Python License: MIT

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

[!IMPORTANT]📌 INSTALLATION & AGENT INTEGRATION: For complete step-by-step installation guides and integration instructions for Google Antigravity, Claude Desktop, Cursor, Roo Code, and other MCP clients, please refer to INSTALL.md.

📖 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

🎯 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:

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.
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.
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:

MCP Tool Name	Description
`memory_recall`	Performs hybrid vector + keyword search to recall relevant project decisions and context.
`memory_save`	Auto-saves new features, bug fixes, or architecture decisions into persistent memory.
`file_info`	Inspects a file's AST skeleton, line counts, imports, and symbol line ranges before reading lines.
`graph_query`	Queries entities, relationships, and neighbor nodes within the Knowledge Graph.
`graph_init`	Scans workspace and builds initial Knowledge Graph structure.
`graph_extend`	Dynamically adds new concepts, nodes, and edges to the Knowledge Graph.
`graph_analytics`	Computes graph metrics (centrality, god nodes, community clusters).
`graph_report`	Generates structured architectural reports from stored graph relationships.
`graph_wiki`	Compiles a markdown wiki from knowledge graph entities.
`graph_impact`	Analyzes potential impact of changing specific code entities or modules.
`notes_import`	Re-indexes manual Markdown notes from the local `notes/` directory.
`notes_export`	Exports and mirrors all project notes to an Obsidian vault structure.

💻 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_*):

Environment Variable	Default	Description
`MNEMO_DATA_DIR`	`~/.mnemo`	Root storage folder for notes, vectors, graphs, and models.
`MNEMO_PROJECT_ID`	(auto-detect)	Explicit override for Project ID (bypasses auto-detection).
`MNEMO_PORT`	`3112`	HTTP Server & Web Dashboard port.
`MNEMO_AUTO_INJECT`	`true`	Enables/disables automatic memory injection into agent prompts.
`MNEMO_AUTO_INJECT_BUDGET`	`800`	Maximum token budget for injected memory context.
`MNEMO_INJECT_THRESHOLD`	`0.35`	Minimum cosine similarity score required for context injection.
`MNEMO_RULES_LEVEL`	`normal`	Rule aggressiveness level (`strict` \| `normal` \| `light`).
`MNEMO_GRAPH_AUTO`	`true`	Automatically triggers `graph_extend` upon `memory_save`.
`MNEMO_GRAPH_EXTEND_THRESHOLD`	`0.5`	Minimum confidence threshold for new graph node/edge creation.

🔒 Project ID Auto-Locking Mechanism

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

mnemo.json (Priority 1): Reads name or projectId from workspace root.
package.json (Priority 2): Reads name if mnemo.json does not exist yet.
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.

Built for high-efficiency AI Pair Programming. Read INSTALL.md to set up Mnemo with your AI Agent today.

🧠 Mnemo Agent Memory