mnemo-mcp/mnemo

Mnemo

Persistent engineering cognition for AI coding agents.

[100% R@5] [2ms search] [58 tools] [17 agent-facing] [11 lifecycle hooks] [0 external DBs] [641 tests]

Install • Why • Benchmarks • How It Works • Clients • Features • Tools • Dashboard • Architecture

---

You explain the same architecture every session. You re-discover the same bugs. You re-teach the same conventions. The agent has no memory of what worked, what broke, or what you decided yesterday.

Mnemo fixes this.

It silently captures decisions as they happen, builds a knowledge graph of your entire codebase, indexes everything for semantic search, and injects the right context when the next session starts. Memories decay naturally — fresh decisions stay hot, stale context fades, contradictions get superseded.

What changes:

Session 1: you set up a new microservice with a database layer, configure retry policies, wire up dependency injection. Session 2: you ask the agent to add a new endpoint. It already knows your service uses a resilience pipeline, auth goes through a delegating handler, your DTOs follow the *Request/*Response pattern, and the orchestration uses durable workflows. No re-explaining. No grepping. The agent just knows.

python3 -m pip install mnemo-dev    # or: brew tap Mnemo-mcp/tap && brew trust --formula mnemo-mcp/tap/mnemo && brew install mnemo
cd your-project
mnemo init --client kiro # or: amazonq, cursor, claude-code, copilot, generic

---

Install

Note: The PyPI package name is mnemo-dev (not mnemo). We recommend using python3 -m pip instead of bare pip and installing inside a virtual environment for reliable dependency isolation.

Then initialize:

cd your-project
mnemo init --client kiro        # or: amazonq, cursor, claude-code, copilot, generic

That’s it. Your agent now has persistent memory, semantic search, and architectural understanding.

mnemo recall          # Preview what the agent will see
mnemo serve           # Dashboard at localhost:3333
mnemo doctor          # Diagnose issues

---

What It Looks Like Day-to-Day

You don’t interact with Mnemo directly. You just talk to your AI agent as usual — Mnemo works in the background.

Day 1 — Setting up a project:

You:   "Set up a new payment service with retry policies and circuit breaker"
Agent: [builds the service, configures resilience]
       [Mnemo auto-captures: architecture decision, file structure, patterns used]

Day 2 — Continuing work:

You:   "Add a new endpoint for refund processing"
Agent: [Already knows: your service uses resilience pipelines, 
        auth goes through a delegating handler, DTOs follow *Request/*Response pattern]
       "I see your existing service uses X pattern. I'll follow the same 
        structure for the refund endpoint..."

Day 5 — Debugging:

You:   "The batch job is failing intermittently"
Agent: [Searches memory → finds you hit a similar issue last week with timeout config]
       "Based on a similar issue you fixed on Monday — the timeout was set too low 
        for large batches. Let me check if the same config applies here..."

Day 10 — New team member’s agent:

You:   "How does our auth flow work?"
Agent: [mnemo_lookup on the auth service → full architecture in one call]
       "Your auth uses a delegating handler pattern with token caching.
        Here are the key classes and their methods..."
       [No file reading needed — graph has everything]

Day 30 — Cross-service impact:

You:   "I need to change the response format of the eligibility API"
Agent: [mnemo_cross_impact → finds 3 other services consuming this API]
       "⚠️ Changing this will affect: ServiceA (mock consumer), 
        ServiceB (integration tests), and the UI (display logic).
        Want me to show the specific callers?"

The agent never asks you to re-explain. Old stale context fades naturally. Critical decisions persist forever.

---

Supported Clients

Works with any agent that speaks MCP. One server, one memory, shared across all clients.

---

Why Mnemo

---

Benchmarks

System Resources

Search uses ONNX all-MiniLM-L6-v2 dense embeddings + BM25 keyword + Dijkstra graph traversal, fused with Reciprocal Rank Fusion (RRF).

---

How It Works

┌─── INIT (one-time, ~7s for 300 files) ───────────────────────────┐
│                                                                  │
│  1. Scan: single os.walk pass across repo                        │
│  2. Parse: tree-sitter AST (14 langs) + Roslyn (C#)              │
│  3. Graph: LadybugDB — files, classes, methods, CALLS edges      │
│  4. Scope: cross-file function call resolution                   │
│  5. Cluster: Louvain community detection                         │
│  6. Index: ONNX vector embeddings for semantic search            │
│  7. Detect: languages, services, key classes, frameworks         │
│  8. Configure: MCP server + hooks for your AI client             │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─── SESSION START (automatic via hooks) ──────────────────────────┐
│                                                                  │
│  mnemo_recall injects into agent context:                        │
│    • Architectural decisions (permanent, never evicted)          │
│    • Hot memories (scored by access × recency × importance)      │
│    • Active plan + next task                                     │
│    • Compact repo index (classes per service)                    │
│    • Project metadata (languages, frameworks, services)          │
│                                                                  │
│  Total: ~500 tokens. Agent starts fully informed.                │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─── DURING SESSION (tools + freshness) ──────────────────────────┐
│                                                                  │
│  Agent has 17 MCP tools available:                               │
│    • mnemo_lookup → full service/class architecture              │
│    • mnemo_search → semantic search (code, memory, APIs)         │
│    • mnemo_impact → blast radius if X changes                    │
│    • mnemo_remember → store decisions, patterns, bugs            │
│    • mnemo_plan → track task progress                            │
│                                                                  │
│  Background: graph + vector index refresh every 30s              │
│  User prompt hook: searches relevant memories, injects them      │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─── SESSION END (auto-capture via stop hook) ─────────────────────┐
│                                                                  │
│  • Detects learnings (bug fixes, discoveries)                    │
│  • Records session decisions                                     │
│  • Stores accomplishments                                        │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─── BETWEEN SESSIONS (decay + maintenance) ───────────────────────┐
│                                                                  │
│  Every 10th recall:                                              │
│    • Retention scored: salience × exp(-0.01 × days) + access     │
│    • Hot (≥0.5) → Warm (≥0.25) → Cold → Evicted                  │
│    • Contradictions auto-superseded (sim > 0.9)                  │
│    • Low-value pruning (cap: 200 active memories)                │
│    • Graph synced (stale memory nodes removed)                   │
│                                                                  │
│  Pinned forever: architecture, decision, preference              │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

---

Features

🧠 Memory System

• Categorized storage: architecture, pattern, bug, preference, decision, todo
• Event-sourced decisions: JSONL append-only event log, computed snapshots, supersede/redact operations
• Branch-scoped decisions: decisions tagged per branch, filtered on recall
• Retention scoring: access frequency × recency × importance (Ebbinghaus-inspired decay)
• Branch-aware: memories tagged with git branch, filtered on recall
• Contradiction detection: new facts auto-supersede old conflicting ones (threshold: 0.6)
• Token-budgeted recall: never exceeds ~2000 tokens regardless of memory count
• Memory slots: pinned structured context (project_context, conventions, known_gotchas)
• Auto-categorization: regex-based category inference from content
• Entity resolution: resolves “this file” → actual filename from task context
• Deduplication: identical/near-identical memories merged, timestamps refreshed

🔍 Triple-Stream Search (100% R@5)

• BM25: IDF-weighted sparse embeddings with synonym expansion
• Vector: ONNX all-MiniLM-L6-v2 dense embeddings (384-dim, cosine similarity, 2ms)
• Graph: Dijkstra shortest-path from code symbols to linked memories (weighted edges)
• Fusion: Reciprocal Rank Fusion (RRF) with source diversification (max 3 per category)
• Zero-LLM query expansion: entity extraction, case detection, path matching

🏗️ Code Intelligence Engine (LadybugDB)

• Knowledge graph: files, folders, classes, methods, functions, projects, communities
• 14 languages: Python, JS/TS, C#, Go, Java, Rust, Ruby, PHP, C/C++, Kotlin, Swift, Scala
• Roslyn enrichment: C# method signatures, implements, full AST detail
• Louvain community detection: automatic functional clustering
• CALLS edges: scope-resolved function call graph with confidence scoring
• Impact analysis: upstream/downstream blast radius (N-hop BFS)
• Incremental freshness: graph + vector index auto-update within 30s of file changes
• Service-level lookup: one tool call returns full service architecture (classes + methods + deps)
• Parse caching: unchanged files skipped on re-index

📋 Planning & Knowledge

• Task plans: create, track, mark done, dependency resolution, auto-detect completion from memory
• Error patterns: store errors with root cause and fix
• Incidents: past incidents with affected services and resolution
• Code reviews: feedback history per file
• Corrections: wrong→right pairs with confidence decay (agent learns from mistakes)
• Lessons: learned patterns that reinforce with repetition
• Knowledge base: markdown docs indexed for semantic retrieval
• API discovery: auto-detect OpenAPI specs + controller annotations

🛡️ Safety & Audit

• Secret stripping: auto-removes tokens, keys, passwords from memories before storage
• Security scan: hardcoded secrets, SQL injection, eval(), shell injection, insecure HTTP
• Dead code detection: symbols with no incoming edges in the graph
• Convention checking: naming violations per language (PascalCase, camelCase, snake_case)
• Pre-tool-use hook: blocks catastrophic shell commands (rm -rf /, system dirs, credential exfil)
• Audit trail: every memory operation logged with timestamp and action

🌐 Multi-Repo & Cross-Service

• Workspace linking: mnemo link ../other-repo connects sibling repos
• Cross-repo search: find code, APIs, knowledge across all linked repos
• Cross-impact analysis: what breaks in OTHER services if you change a symbol
• Shared knowledge: decisions and patterns visible across workspace
• Service registry: auto-detected from project manifests

---

Workflow Skills & Orchestrator

Mnemo includes 6 workflow skills that guide agents through a structured SDLC pipeline, with quality gates enforcing standards between phases.

The Pipeline

investigate → plan → implement → verify → review → ship
                                    ↑                ↑
                              [tests_pass]    [tests_pass + plan_done + no_findings]

Each phase has a dedicated skill template with explicit instructions, shell commands for mnemo tools, and persistence hooks. The orchestrator tracks state in .mnemo/autorun_state.json and blocks advancement when gates fail.

Quality Gates

Template Resolver System

Skills use {{RESOLVER}} placeholders that get expanded per-host:

---

MCP Tools (58 total: 17 agent-facing + 42 specialized)

Mnemo exposes 17 consolidated agent-facing tools via MCP — designed to cover every workflow in minimal tool calls. Under the hood, these route to 42 specialized internal tools for granular operations.

Agent-Facing Tools (what the AI calls)

Specialized Internal Tools (42 — routed through agent-facing tools)

---

Lifecycle Hooks (per client)

Hooks are shell scripts (Kiro) or JSON config (Claude Code) that fire at key points in the agent lifecycle. They’re what makes Mnemo automatic — you don’t need to manually tell the agent to remember or recall.

Kiro (5 hooks)

Claude Code (6 hooks via .claude/settings.json)

Other Clients (Amazon Q, Cursor, Copilot, Windsurf)

These clients don’t support hooks natively. Instead, Mnemo installs a rules/context file that instructs the agent to:

1. Call mnemo_recall at session start
2. Call mnemo_search_memory before asking the user a question
3. Call mnemo_remember after making decisions or fixing bugs
4. Call mnemo_plan to track task progress

The rules file is auto-generated at mnemo init and includes the full tool reference.

---

Performance

---

Dashboard UI

mnemo serve    # http://localhost:3333

• 🕸️ Interactive knowledge graph visualization (vis-network)
• 🧠 Memory & decisions viewer with category filters
• 🏘️ Community explorer with zoom-to-cluster
• 🔍 Code search with click-to-focus on graph nodes
• 📊 Health monitoring, stats, and resource usage
• 📋 Node detail panels (methods, callers, callees, community)

---

Architecture

.mnemo/
├── memory.json              Memories with retention scores & access history
├── decisions.json           Permanent architectural decisions (computed snapshot)
├── decisions.events.jsonl   Event-sourced decision log (source of truth)
├── plans.json               Task tracking with dependencies
├── context.json             Auto-detected project metadata
├── learnings.json           Typed learnings with confidence & key-dedup
├── autorun_state.json       SDLC orchestrator phase tracking
├── graph.lbug/              LadybugDB knowledge graph (Kuzu engine)
├── vectors_code.npy         ONNX embeddings of code symbols (384-dim)
├── vectors_memory.npy       ONNX embeddings of memories
├── meta_*.json              Vector metadata for cosine search
├── engine-meta.json         File hashes for incremental detection
├── parse-cache.json         AST parse cache (skip unchanged files)
├── tree.md                  Compact repo index (generated from graph)
├── corrections.json         Wrong→right patterns with confidence
├── lessons.json             Learned patterns with reinforcement
└── slots.json               Pinned structured context (conventions, gotchas)

Stack: Python · LadybugDB (Kuzu) · ONNX Runtime · tree-sitter · Roslyn · NetworkX (Louvain)

Zero cloud. Zero API keys. Zero telemetry. Everything runs locally.

---

Memory Retention Model

Retention = Salience × Temporal_Decay + Reinforcement

Salience:       architecture=0.9  decision=0.9  preference=0.85
                pattern=0.8  bug=0.7  todo=0.6  general=0.5

Decay:          exp(-0.01 × days_old)

Reinforcement:  Σ(1 / days_since_each_access) × 0.05    (capped at 0.3)

Tiers:
  retention ≥ 0.5   → HOT    (always shown in recall)
  retention ≥ 0.25  → WARM   (shown if token budget allows)
  retention < 0.25  → COLD   (excluded from recall, findable via search)
  retention  60d → EVICTED

Pinned categories (never evicted): architecture, decision, preference

---

CLI Reference

mnemo init --client CLIENT       # Initialize in a repo (kiro, cursor, claude-code, amazonq, copilot, generic)
mnemo recall [--tier TIER]       # Show agent context (compact, standard, deep)
mnemo map                        # Regenerate repo map from graph
mnemo serve [-p PORT]            # Dashboard UI (default: 3333)
mnemo doctor                     # Diagnose installation issues
mnemo reset                      # Remove Mnemo data (safe: only Mnemo-owned files)
mnemo link [TARGET]              # Link another repo to multi-repo workspace
mnemo remember "content" [-c CAT]# Store a memory
mnemo learn -t TYPE -k KEY -i TXT# Store a typed learning (7 types, key-dedup)
mnemo learnings [-t TYPE]        # List stored learnings (sorted by confidence)
mnemo ingest [--file FILE]       # ETL: extract learnings from session transcripts
mnemo tool NAME [--args]         # Call any MCP tool from CLI

Customizing What Gets Indexed

Mnemo skips a built-in set of heavy/non-source directories during indexing (node_modules, .venv, dist, build, etc. — see mnemo/config.py for the full list).

To skip additional directories in a specific repo, drop a .mnemoignore file at the repo root with one directory name per line:

# Heavy dirs to exclude from indexing
data
logs
backups

Lines are matched by exact directory basename, anywhere in the tree (same semantics as the built-in list). Blank lines and # comments are ignored. Trailing slashes are tolerated. Glob / .gitignore semantics are not supported yet — patterns are basenames only.

---

Contributing

git clone https://github.com/Mnemo-mcp/Mnemo.git
cd Mnemo
python3 -m pip install -e ".[dev]"
pytest                    # 641 tests
ruff check .              # Lint
mnemo init                # Test on self

---

Links

---

License

AGPL-3.0 — Free for personal and open-source use.