μνήμη · Mneme

The memory layer of your codebase.

Pronounced NEE-meh · Greek for "memory"
_{sister of Lethe (forgetting), mother of the muses.}

Your codebase remembers everything. Your AI assistant remembers nothing.
Mneme is the bridge.

Every commit, every PR, every late-night fix is recorded in your git history.
But your AI assistant can't see any of it — so it guesses.
Mneme indexes that history and gives it back to you, and to your AI, in 2 seconds.

═══════════════════════════════════════════════════════════════════════════════

🚀 Install — pick one of three ways

💡 You only need one of these. Pick the row that fits you, run that one command — done.

After install, run the same 60-second flow on any git repo:

mneme init                       # creates .mneme/ inside the repo
mneme index                      # ~90s for 5k commits with Ollama
mneme ask "why does X exist?"    # query the memory

═══════════════════════════════════════════════════════════════════════════════

🔧 Upgrade

mneme --version                       # 1. see what you have
npm install -g mneme-ai@latest        # 2. pull latest
mneme --version                       # 3. verify

💡 If the version doesn't change, open a fresh terminal — your shell caches the old binary path. On Windows, npm install -g writes to %APPDATA%\npm\ which the parent shell only re-reads on launch.

═══════════════════════════════════════════════════════════════════════════════

✨ Try these 5 commands first

The fastest way to "get it" is to copy-paste any of these on your repo right now:

1️⃣ Ask anything about your code

mneme ask "why does the webhook handler retry?"

Q  why does the webhook handler retry?

  ● HIGH CONFIDENCE  ◉ TRUST 95%
  synthesized in 240ms

  ✦ Answer
    Per commit a3f9b21 from 2024-08, the team switched from sessions to
    token-based auth after the rate-limit incident referenced in #482.
    The 3-retry backoff was added in the hotfix that followed, matching
    a third-party API provider's recommended client behavior.

  ◆ Evidence  (showing 3 of 8)
  ● a3f9b21  [2024-08-14 · Alice · 0.045]
    fix: retry webhook on 502 (closes #482)
  ● 2c4d8e0  [2024-08-15 · Alice · 0.039]
    pr#503: tune retry backoff to match upstream guidance

2️⃣ Understand any line in 2 seconds

mneme why src/auth/session.ts:47

Walks the blame, mines the PRs, returns the actual reason — with citations.

3️⃣ Predict regret before you commit

mneme premortem "rewrite the auth flow"

🔮  Pre-mortem
═══════════════════════════════════════════════════════════════
intent:  rewrite the auth flow

✦ Verdict
   risk: VERY HIGH  (P(regret) = 78%)
   7 of 9 similar past attempts ended badly.

◆ Top risks
   • token race condition (3× before)
       b2e1f04  fix: stale token served to logged-in users
   • breaking external integrations (2× before)
       9c3593c  hotfix: oauth callback dropped on PATCH

4️⃣ See your file's life as a story

mneme time-machine src/payments/charge.ts

Groups commits into eras: birth → rewrite → firefight → plateau. You read 8 epochs and you understand the file's life.

5️⃣ Ship audit-grade answers (zero hallucination)

mneme ask --audit "is this safe to merge?"

Refuses to answer below confidence threshold. Refuses if any cited commit hash isn't real. Returns trust score 0–100%. Use this for CI gates and AI agent tool calls.

═══════════════════════════════════════════════════════════════════════════════

🎯 Why people use Mneme

💬 "I gave my AI assistant a memory of my repo. It stopped guessing."

═══════════════════════════════════════════════════════════════════════════════

🤖 Tell your AI to install it (one prompt)

Paste this into Claude Code, Cursor, Codex CLI, or any agent that can edit files & run shell:

Install Mneme as an MCP server for this repo so you can query my git history
and codebase memory.

Steps:
  1. Run `npx -y mneme-ai init` then `npx -y mneme-ai index`.
  2. Add an MCP server entry pointing to `npx -y mneme-ai mcp` (cwd = this
     repo's absolute path) in the right config file:
       - Claude Code:  ~/.claude/settings.json
       - Cursor:       ~/.cursor/mcp.json
       - Codex CLI:    ~/.codex/config.json
  3. Reload MCP and confirm `mneme_ask`, `mneme_why`, `mneme_search_commits`
     appear.
  4. From now on, before answering "why" questions about this code, call
     `mneme_ask` first.

The agent will install, configure, and start using Mneme as a tool in its reasoning loop.

═══════════════════════════════════════════════════════════════════════════════

⚡ All Commands

💡 Every command supports --help for usage notes. Examples below show what each does in plain English.

🟢 Tier 1 — Essentials (always visible in mneme --help)

🌟 Insights — world-firsts in this category

💰 Quant — Wall-Street-inspired engineering intelligence

🧰 More commands available — entity-level similarity, incident correlation, the Wisdom Mutant Engine (self-improving), and several specialized tools live in the Command Tour wiki. Run mneme advanced to list them all.

═══════════════════════════════════════════════════════════════════════════════

🛡 Audit-grade mode — zero hallucination guarantee

mneme ask --audit "why does the webhook retry?"
mneme ask --audit --audit-floor high "..."   # tighten the threshold

In audit mode, Mneme:

• ✅ Refuses below confidence floor (default: medium · --audit-floor low|medium|high)
• ✅ Refuses on unverified citations — every backtick-hash is checked against retrieved evidence
• ✅ Returns trust score 0–100% with every answer (green / cyan / yellow / red)
• ✅ JSON output usable as a CI gate or MCP tool result

🌌 This is the only tool we know of that ships an explicit hallucination guard for git Q&A. The new moat.

═══════════════════════════════════════════════════════════════════════════════

🌌 The Frontier — what makes Mneme one of a kind

After researching the landscape of git, code-search, and AI-coding tools, we confirmed every command below occupies whitespace where no maintained, open-source, local-first tool ships this capability today.

13 world-firsts. Local-first by design. One of a kind. The frontier.

🛡 Built to complement existing AI coding assistants — not to replace them.

═══════════════════════════════════════════════════════════════════════════════

📚 Want more? → Wiki

🏗 Architecture deep-dive: ARCHITECTURE.md · 🔒 Privacy: docs/SECURITY.md · 🗺 Roadmap: ROADMAP.md

═══════════════════════════════════════════════════════════════════════════════

📦 Project links

═══════════════════════════════════════════════════════════════════════════════

📜 License & support

MIT — use it, fork it, ship it.

🧑‍💻 Solo developer. I read every issue. PRs welcome. Be kind.