mnemo-dev 0.6.0

Persistent memory and repo map for AI coding assistants

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 (recommended)	pip install mnemo-dev
Homebrew (macOS/Linux)	brew tap Mnemo-mcp/tap && brew install mnemo
npx (Node.js)	npx @mnemo-dev/mcp
VS Code Extension	Search "Mnemo" in Extensions, or: code --install-extension Nikhil1057.mnemo-vscode
Standalone binary	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/
From source	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

Client	MCP	Hooks	Config
Kiro	✅	5 lifecycle hooks	Agent + skill + rules
Amazon Q	✅	—	.amazonq/rules
Claude Code	✅	6 hooks (settings.json)	CLAUDE.md
Cursor	✅	—	.cursorrules
Copilot	✅	—	.github/copilot-instructions
Windsurf	✅	—	.windsurfrules
Generic MCP	✅	—	MNEMO.md

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

---

Why Mnemo

Without Mnemo	With Mnemo
Re-explain your stack every session	Agent already knows your architecture
Agent breaks call chains it can't see	Full dependency graph with impact analysis
"What caching do we use?" → agent greps 50 files	Semantic search finds the answer in 2ms
Decisions lost between sessions	Permanent decisions survive forever
Context window wasted on repetition	~500 tokens of targeted recall per session
"What broke last time?" → no idea	Error patterns, incidents, and regression warnings
Agent doesn't know cross-service deps	Multi-repo linking with cross-impact analysis
Memory file grows forever, goes stale	Natural decay: hot → warm → cold → evicted

---

Benchmarks

Metric	Mnemo	Static rules (CLAUDE.md)	No memory
Search Recall@5	100%	N/A (grep)	0%
Search latency	2ms	—	—
Token cost/session	~500	22,000+ (full file)	0
Cross-session persistence	✅	Manual only	❌
Contradiction handling	✅ auto-supersede	❌	❌
Memory decay	✅ natural eviction	❌ grows forever	—
Code understanding	Knowledge graph	None	None
Cross-repo awareness	✅	❌	❌

System Resources

Resource	Value
RAM (with model loaded)	265 MB
Disk (.mnemo/)	~16 MB
ONNX model (one-time download)	86 MB
External databases	0
Cloud dependencies	0
API keys required	0

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

Gate	What it checks	Blocks
tests_pass	Runs test suite (pytest/npm/maven/gradle)	review, ship
plan_done	All plan tasks marked complete	ship
no_findings	No unresolved critical findings in memory	ship

Template Resolver System

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

Resolver	Injects
{{PREAMBLE}}	Mandatory header — forces tool usage, DO NOT PROCEED pattern
{{LEARNINGS}}	Past learnings relevant to current skill
{{CONTEXT_LOAD}}	Shell command to load brain context at skill start
{{TOOL_REFERENCE}}	Available mnemo commands table
{{PERSIST_BLOCK}}	Shell commands for persisting knowledge at skill end

---

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)

Tool	What it does
mnemo_recall	Load full project context at session start (budgeted ~2000 tokens)
mnemo_remember	Store important context with auto-categorization & dedup
mnemo_decide	Record permanent architectural decisions (never evicted)
mnemo_supersede	Supersede (replace) an existing decision by ID
mnemo_redact	Permanently redact a decision (e.g., accidental secrets)
mnemo_forget	Delete a specific memory by ID
mnemo_search_memory	Semantic search across memories (3-way RRF fusion)
mnemo_lookup	360° detail: class methods, function signatures, or full service architecture
mnemo_search	Unified search: code + memory + APIs + errors + cross-repo
mnemo_graph	Query knowledge graph (stats, neighbors, find by type)
mnemo_impact	Blast radius — what breaks if X changes (N-hop BFS traversal)
mnemo_plan	Task plans: create, done, add, remove, depends, status
mnemo_audit	Security scan, health check, dead code, convention violations
mnemo_record	Store errors, incidents, reviews, corrections
mnemo_generate	Commit messages and PR descriptions from git diff
mnemo_map	Regenerate repo map from graph (instant)
mnemo_ask	Natural language → auto-routed to appropriate tools
mnemo_lesson	Learned patterns with confidence decay and reinforcement

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

Click to expand full tool inventory

Code Intelligence:

Tool	Purpose
mnemo_symbol	360° context for a symbol (callers, callees, community)
mnemo_query	Raw Cypher queries against LadybugDB
mnemo_communities	List all detected code communities
mnemo_dead_code	Find unreferenced classes and functions
mnemo_check_conventions	Naming violation check per language
mnemo_dependencies	Dependency tree for a symbol
mnemo_breaking_changes	Detect potential breaking changes in a diff
mnemo_temporal	File instability scores (change frequency)
mnemo_onboarding	Generate onboarding guide from graph

Memory & Knowledge:

Tool	Purpose
mnemo_slot_get	Read a named memory slot
mnemo_slot_set	Write a named memory slot
mnemo_context	Save/update project context key-values
mnemo_search_memory	Deep semantic memory search
mnemo_episode	Store episodic session summaries
mnemo_snapshot	Capture full memory state snapshot
mnemo_knowledge	Search project knowledge base (runbooks, docs)
mnemo_corrections	List stored wrong→right corrections
mnemo_add_correction	Add a new correction pattern

Safety & Security:

Tool	Purpose
mnemo_check_security	Scan for secrets, injection, insecure patterns
mnemo_add_security_pattern	Add custom security scan pattern
mnemo_check_regressions	Check known regression risks
mnemo_add_regression	Register a new regression risk
mnemo_check	Pre-command safety check (blocks dangerous ops)

Engineering Records:

Tool	Purpose
mnemo_add_error	Store error pattern with root cause
mnemo_search_errors	Search past errors
mnemo_add_incident	Record incident with affected services
mnemo_incidents	Search past incidents
mnemo_add_review	Store code review feedback
mnemo_reviews	Search review history

Multi-Repo & APIs:

Tool	Purpose
mnemo_links	Show linked repos in workspace
mnemo_cross_search	Search across all linked repos
mnemo_cross_impact	Cross-service impact analysis
mnemo_discover_apis	Auto-detect API endpoints (OpenAPI + annotations)
mnemo_search_api	Search API catalog

Team & Velocity:

Tool	Purpose
mnemo_team	Team activity and expertise map
mnemo_who_touched	Find who has expertise on a file/symbol
mnemo_velocity	Sprint velocity and throughput metrics
mnemo_tests	Test coverage and health insights

Generation:

Tool	Purpose
mnemo_commit_message	Generate commit message from staged changes
mnemo_pr_description	Generate PR description with context
mnemo_drift	Detect architectural drift from declared rules
mnemo_health	Overall project health score

---

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)

Hook	Trigger	What it does
agent-spawn	Session starts	Calls mnemo_recall → injects full context (decisions, memories, plans, repo map) into agent
user-prompt-submit	Every user message	Searches memories relevant to the current prompt → injects as <mnemo-relevant-context>
pre-tool-use	Before Bash commands	Security check: blocks catastrophic commands (rm -rf /, credential exfil, system dir mods)
post-tool-use	After Write/Edit	Records modified files in memory (Modified file: path/to/file)
stop	Session ends	Detects learnings (bug fixes, decisions, accomplishments) → auto-stores in memory

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

Hook	Trigger	What it does
SessionStart	Chat opens	Loads full recall context
UserPromptSubmit	Every message	Semantic memory search on user's prompt
PreToolUse (Bash)	Before shell command	Safety: blocks dangerous operations
PostToolUse (Write|Edit)	After file write	Records file modification in memory
Stop	Session ends	Captures session learnings and decisions
PreCompact	Before context compaction	Re-injects recall so context survives compaction

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

Operation	Time
mnemo init (55 files)	3.5s
mnemo init (300 files)	7s
Re-init (no changes)	0.01s
mnemo_recall	33ms
mnemo_remember	5ms
mnemo_search_memory	2ms
mnemo_lookup (service-level)	0.5ms
Graph query	0.2ms

---

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

🌐 Website	mnemo-mcp.github.io/Mnemo
📦 PyPI	pypi.org/project/mnemo-dev
📦 npm	npmjs.com/package/@mnemo-dev/mcp
🍺 Homebrew	brew tap Mnemo-mcp/tap && brew install mnemo
🧩 VS Code	Marketplace
💻 GitHub	github.com/Mnemo-mcp/Mnemo
📋 Changelog	CHANGELOG.md
📋 Distribution	DISTRIBUTION.md

---

License

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