Get started with Mnemo

Installation #

Install Mnemo globally via npm. Node.js 20 or later is required.

npm install -g mnemo-cli

Verify the installation:

mnemo --version

Initialize a project #

Run mnemo init inside any git repository. It installs a post-commit hook and creates the project config under ~/.mnemo/.

cd my-project
mnemo init

Mnemo identifies your project by hashing its git remote URL — the same remote always maps to the same project, so your context survives re-clones and directory moves.

Wire up your agent #

Run mnemo install <agent> to generate the right config file for your AI coding agent. Mnemo keeps it up to date automatically after every commit.

mnemo install claude    # CLAUDE.md + skill file + MCP in ~/.claude/settings.json
mnemo install copilot   # copilot-instructions.md + skill file + MCP in .vscode/mcp.json
mnemo install codex     # AGENTS.md + skill file + MCP in ~/.codex/config.toml
mnemo install cursor    # .cursor/rules/mnemo.mdc + skill file + MCP in .cursor/mcp.json
mnemo install windsurf  # .windsurfrules + skill file + MCP in ~/.codeium/windsurf/mcp_config.json

FEAT Context Cache Layer 3 #

The FEAT cache is Mnemo's differentiator. While Layers 1 and 2 index the code, Layer 3 captures the work in progress — what you're building, why you made certain choices, and where you left off.

Each feature is an append-only event log (events.jsonl) rendered into a context.md your agent reads at session start.

Workflow #

# Start a feature
mnemo feat start payment-flow

# Record decisions as you make them
mnemo feat decision "Using Stripe Checkout — simpler for MVP"

# Link the files in scope
mnemo feat link-file src/routes/payments.ts
mnemo feat link-file src/services/stripe.ts

# Note blockers
mnemo feat blocker "Webhook signature verification failing on localhost"

# Check the generated context your agent will see
mnemo feat context

# Finish and switch features
mnemo feat done
mnemo feat start auth-refresh

Semantic Index Layer 1 #

Semantic search over your codebase using local embeddings. Uses all-MiniLM-L6-v2 (~88 MB) via ONNX Runtime — no API keys, no network calls, no code leaves your machine.

mnemo search "JWT authentication middleware"
mnemo search "database connection pooling" --limit 5
mnemo search "auth guards" --include-tests

The index is updated automatically on every git commit via the post-commit hook installed by mnemo init.

To index immediately without committing:

mnemo update

mnemo update performs incremental indexing by default — it hashes every file and only re-indexes files that changed, skipping unchanged ones. A full re-index of a large project (2 000+ files) completes in seconds on subsequent runs.

Structural Graph Layer 2 #

File-level dependency graph built with Tree-sitter. Tells your agent which files import what, which are affected by a change, and what symbols live where — without reading file contents.

# Files this file imports
mnemo graph deps src/services/auth.ts

# Files that import this file
mnemo graph refs src/routes/payments.ts

# Transitive dependents (BFS, max depth 3)
mnemo graph affected src/services/auth.ts

# Top-level functions and classes in a file
mnemo graph symbols src/services/auth.ts

mnemo init #

Initialize Mnemo for the current git repository.

mnemo init [--force]

Creates ~/.mnemo/projects/<project-id>/ and installs the post-commit hook at .git/hooks/post-commit.

mnemo feat #

Manage FEAT context cache entries.

mnemo search #

mnemo search "<query>" [--limit <n>] [--include-tests] [--output json] [--no-hybrid]

Results are ranked by hybrid score (semantic similarity + graph proximity + feat relevance). Scores display as decimals (e.g. 0.87). Snippets show 6 lines of context.

mnemo install #

mnemo install claude|copilot|codex|cursor|windsurf

Generates the agent-specific config file and adds instructions for the agent to load Mnemo context at session start.

mnemo mcp serve #

mnemo mcp serve [--port <n>]

Starts a stdio-based MCP server exposing Mnemo tools to any MCP-compatible client. Useful for custom agent setups or IDE extensions that speak the Model Context Protocol.

Data model #

Each feature is an append-only event log. Events are never mutated — a snapshot is re-derived on every read.

// FeatureEvent (events.jsonl)
{
  "id":        "evt_01j...",
  "type":      "decision" | "blocker" | "link-file" | "note" | ...,
  "payload":   "<text or path>",
  "timestamp": "2026-04-25T14:32:00Z"
}

The context.md file is derived from this log on every write — it is never the source of truth.

Local storage layout #

~/.mnemo/
  config.json
  projects/
    {project-id}/          # xxh3(git remote)[0:16]
      meta.json
      index.db             # vector index (SQLite + sqlite-vec)
      graph.db             # structural dependency graph (SQLite)
      feats/
        {feat-name}/
          events.jsonl     # source of truth (append-only)
          context.md       # derived — do not edit
          meta.json
      active_feat          # name of active feature (plain text)

All data lives under ~/.mnemo/. Nothing is written to your repository except the git hook and the agent config file.

Privacy #

Mnemo is designed to run entirely offline by default. The semantic index uses all-MiniLM-L6-v2 downloaded once from Hugging Face (~88 MB) and cached locally. No code or context is ever sent to any external server.

Optionally, you can use Ollama (local) or OpenAI (cloud) for better embedding quality:

mnemo config set embedding.provider ollama
mnemo config set embedding.provider openai