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.

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

Install

pip install mnemo-dev

brew tap Mnemo-mcp/tap && brew install mnemo

npx @mnemo-dev/mcp

code --install-extension Nikhil1057.mnemo-vscode

curl -fsSL https://github.com/Mnemo-mcp/Mnemo/releases/latest/download/mnemo-$(uname -s | tr A-Z a-z)-$(uname -m) -o mnemo
chmod +x mnemo && sudo mv mnemo /usr/local/bin/

git clone https://github.com/Mnemo-mcp/Mnemo.git && cd Mnemo && pip install -e .

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 < 0.1 + age > 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
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.