# 🧠 Mnemo Agent Memory

[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
[![MCP Protocol](https://img.shields.io/badge/MCP-1.3.0-blue.svg)](https://modelcontextprotocol.io/)
[![Zero Python](https://img.shields.io/badge/Dependencies-Zero%20Python-orange.svg)]()
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

> **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**, **Pi Agent (`pi-coding-agent`)**, **Claude Desktop**, **Cursor**, **Windsurf**, **OpenCode**, and other MCP clients, please refer to [**INSTALL.md**](INSTALL.md).

---

## 📖 Table of Contents

- [The Core Problem (Why Mnemo Exists)](#-the-core-problem-why-mnemo-exists)
- [Key Architectural Pillars](#-key-architectural-pillars)
- [System Architecture](#-system-architecture)
- [Core Features & Capabilities](#-core-features--capabilities)
- [MCP Tools Reference](#-mcp-tools-reference)
- [CLI Usage & Commands](#-cli-usage--commands)
- [Portable Memory Bundles (Team Collaboration)](#-portable-memory-bundles-team-collaboration)
- [Configuration & Environment Variables](#-configuration--environment-variables)
- [Project ID Auto-Locking Mechanism](#-project-id-auto-locking-mechanism)
- [License](#-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

```mermaid
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`).

```bash
# 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**:
   ```bash
   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**:
   ```bash
   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`](LICENSE) for details.

---

<p align="center">
  <b>Built for high-efficiency AI Pair Programming.</b><br>
  <i>Read <a href="INSTALL.md">INSTALL.md</a> to set up Mnemo with your AI Agent today.</i>
</p>