🧠 Mnemo Agent Memory

A Lightweight, High-Precision, Zero-Token-Waste Memory Engine, Knowledge Graph, and Portable 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, Windsurf, OpenCode, 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
• Portable Memory Bundles (Team Collaboration)
• Configuration & Environment Variables
• Project ID Auto-Locking Mechanism
• License

🎯 The Core Problem (Why Mnemo Exists)

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

1. Context Window Contamination & Token Waste:
   Traditional agent workflows perform heavy file dumps or forced multi-turn memory searches. This floods the model's context window with irrelevant lines, depletes API context budgets rapidly, and causes context drift.

2. Heavy External Database Overhead:
   Existing agent memory frameworks rely heavily on external vector database services or C++ native binaries (PostgreSQL/pgvector, Pinecone, sqlite3 native builds). In modern agent environments, managing external databases creates complex setup hurdles and cross-platform compilation failures.

3. Team Context Disconnection:
   When multiple developers work on the same repository, historical decisions made by one AI agent session are lost to teammates, forcing each developer's AI agent to re-learn architecture from scratch.

Mnemo solves all three problems at the root. It provides a 100% pure Node.js memory engine operating over the Model Context Protocol (MCP), enforces a Zero-Token-Waste Protocol, auto-locks project identity, mirrors all memories into Markdown notes, and supports portable team memory bundles for instant team collaboration.

⚡ Key Architectural Pillars

1. 🛡️ Zero-Token-Waste Protocol

Mnemo injects relevant past architectural context directly into agent prompts via <MNEMO_CONTEXT> without forcing redundant tool-call turns. Search payloads are ultra-compact (over 90% size reduction), allowing agents to freely use native search tools (grep_search, view_file) at maximum speed.

2. 👥 Portable Team Memory Bundles

Mnemo allows developers to export the entire project memory (notes, index, and Knowledge Graph) into a single portable .json bundle file (mnemo export-memory). Teammates can import this bundle (mnemo import-memory), automatically building local vector embeddings so their AI agent instantly shares the same project context.

3. 🔒 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.

4. 🕸️ Embedded Knowledge Graph & Local ONNX Embeddings

Mnemo maintains a directed persistent Knowledge Graph tracking relationships between concepts, code entities, decision logs, and file structures. Local embeddings are computed via @xenova/transformers (all-MiniLM-L6-v2 ONNX) 100% locally without external API keys, featuring automatic idle RAM unloading.

5. 🧹 Multi-Agent Auto-Cleanup

Uninstalling Mnemo (npm uninstall -g mnemo-agent-memory or mnemo remove) automatically triggers lifecycle hooks that clean injected agent rules (GEMINI.md, AGENTS.md, CLAUDE.md, .cursorrules, .windsurfrules) and remove registered MCP servers across all supported agents.

🏗️ System Architecture

flowchart TD
    subgraph Client ["AI Agent / IDE Environment"]
        Agent["AI Coding Agent (Antigravity / Claude / Cursor / OpenCode)"]
    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["Local ONNX Embeddings (all-MiniLM-L6-v2)"]
        Graph["Knowledge Graph Engine (Nodes & Edges)"]
        Bundle["Portable Memory Bundle (Export / Import)"]
        Lock["Project ID Auto-Lock (mnemo.json)"]
    end

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

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

🚀 Core Features & Capabilities

• Smart Recall Gating & Ultra-Compact Payload: Guardrails prevent amnesia and recall loop spam, serving compact digests and cutting token usage by ~75%.
• Memory Conflict Resolution & Self-Healing: supersedes metadata auto-archives deprecated notes, paired with mnemo audit to fix broken file links.
• Cross-File AST Dependency & Symbol Graph: Direct mapping of relative imports and defined_in symbol edges for deep BFS impact analysis.
• Monorepo & Hierarchical Project Scoping: Auto-detects workspace boundaries (pnpm, npm/yarn, lerna) with blended root + package memory recall.
• Git History & Commit Ingestion: mnemo git-sync auto-extracts commit intent and modified files directly into the Knowledge Graph.
• Hybrid Vector + Keyword Search: Powered by @xenova/transformers (running all-MiniLM-L6-v2 locally via ONNX without Python) combined with BM25 keyword matching and Reciprocal Rank Fusion (RRF).
• Portable Memory Bundles: Export and import complete memory snapshots (notes, index, graph) into a single portable .json file for team sharing.
• Obsidian Mirroring: Seamless two-way sync with an Obsidian-compatible vault directory (notes_export / notes_import).
• Web Dashboard: Interactive web interface (default port 3112) to visualize knowledge graphs, view memories, and manage project notes.

🔧 MCP Tools Reference

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

| MCP Tool Name | Description | |---|---| | memory_recall | Performs hybrid vector + keyword search with compact digest payload & smart single-call guardrails. | | memory_save | Saves new features, bug fixes, or architecture decisions with auto-indexing, embedding, and supersedes linking. | | memory_audit | Inspects memory store health (broken file references, stale notes, supersede chains) and self-heals references. | | git_sync | Syncs recent git commit logs and modified file relations directly into the Knowledge Graph. | | memory_export | Exports project memory bundle (notes, index, Knowledge Graph) to a portable JSON file. | | memory_import | Imports project memory bundle from a JSON file and auto-generates local vector embeddings. | | 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 Knowledge Graph with cross-file imports and symbol nodes. | | 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 ripple-effect 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

# Audit & Self-Healing
mnemo audit               # Check memory health (broken links, stale notes)
mnemo audit --fix         # Auto-clean broken references

# Git Ingestion
mnemo git-sync            # Sync recent 20 commits to Knowledge Graph
mnemo git-sync -n 50      # Sync recent 50 commits

# Export & Import Memory Bundles
mnemo export-memory mnemo-bundle.json
mnemo import-memory mnemo-bundle.json

# Notes Synchronization
mnemo notes-export        # Export & sync notes to Obsidian vault
mnemo notes-import        # Import & re-index notes/*.md files

# Knowledge Graph Operations
mnemo graph init          # Initialize graph with cross-file import links
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

# Agent Connection & Cleanup
mnemo connect agy         # Connect Mnemo MCP to Google Antigravity
mnemo remove              # Clean up agent rules, MCP registrations, and skills

📦 Portable Memory Bundles (Team Collaboration)

Sharing project memory with teammates is simple:

1. Export Memory:

   mnemo export-memory team-memory.json

2. Share File: Commit team-memory.json to your repository or send it to your teammate.
3. Import Memory:

   mnemo import-memory team-memory.json

   Your teammate's Mnemo engine will reconstruct notes, index, Knowledge Graph, and automatically compute local vector embeddings so their AI agent instantly shares the exact same project context.

⚙️ Configuration & Environment Variables

Mnemo can be configured globally via ~/.mnemo/config.json or overridden 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. |

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