Mnemo — Memória de Conhecimento Local-First com Inteligência de Código
mmct-jsc/mnemo
Memória local + code intelligence + agente companion para Claude e IDEs
Ver no GitHubMCP server que agrega memória local, conhecimento de projeto e código-fonte em um grafo tipado único, recuperando contexto relevante via Graph-RAG com limite de tokens. Funciona como companion agentic para Claude e outras IDEs, injetando memória estruturada e inteligência de código a cada prompt, com visualização WebGL interativa do grafo completo.
Instalação
npx convez-ai mmct-jsc/mnemo1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Manter contexto consistente de projeto entre múltiplas sessões de código
- Conectar lições aprendidas (memória) com implementação (código-fonte)
- Recuperar decisões de design e feedback passados relevantes ao contexto atual
- Visualizar relacionamentos entre funções, commits e anotações em grafo interativo
Veredito

Solução madura (v5.1.0) e bem-arquitetada para desenvolvedores que trabalham em projetos complexos. Abordagem local-first com SQLite é robusta; suporte multi-IDE (Claude Desktop, Cursor, Continue, Windsurf, Zed) valida o design. Curva de aprendizado é alta, mas ROI compensa para equipes que precisam manter memória institucional em código.
README
A tradução para o português deste README ainda está na fila.
mnemo
▶ Live interactive demo — the real Nebula galaxy renderer on a seeded synthetic graph of mnemo's own architecture (static, no backend).
Local-first knowledge memory + code intelligence + an agentic companion for Claude Code. Aggregates your Claude memory, project knowledge, and source code into a single typed graph; retrieves it via hybrid Graph-RAG on every prompt; ships it back as token-budgeted, cited context. Chat with it through a tool-using agent ("Mnem"), and explore the whole graph as a custom WebGL galaxy at /graph.
[Claude Code plugin] skills + hooks + slash commands
|
v localhost HTTP
[mnemo daemon] Python + FastAPI on 127.0.0.1:7373
|
+-- typed graph: memory_* nodes + code_* nodes + commit nodes
+-- typed edges: applies_to / calls / routes_to / at_endpoint / touched_by / ...
+-- per-edge confidence (0.0..1.0) for inferred inferences
|
v
[mnemo store] SQLite + sqlite-vec (~/.claude/mnemo/)
Why
Claude memory is scattered: ~/.claude/projects/<project>/memory/*.md, per-repo CLAUDE.md, design docs under docs/plans/, the global ~/.claude/CLAUDE.md. As you work across projects, the same lessons get re-discovered, the same feedback gets re-given, the same designs get re-derived.
v2.0 adds the missing half: your code lives next to your memory in the same typed graph. Now "where is this function called from?" + "why was this commit made?" + "what feedback applies here?" are all one query.
When you start a session, mnemo injects a memory map. When you submit a prompt, hybrid Graph-RAG injects ≤ 800 tokens of relevant typed memory + code structure. When Claude edits a file, mnemo re-embeds in the background.
What's new
Newest first. The full version-by-version diff is in CHANGELOG.md.
v5 — Mnem the prompt architect
- MCP substrate reach (v5.5.0 + v5.7.0). Five new 5-minute mount guides + smoke tests land alongside the Phase-1 flagships (Cursor + OpenAI Agents SDK): Claude Desktop, Continue, Windsurf, Zed, and now Gemini CLI. One
mnemo mcpstdio server, seven documented hosts, one tool surface —docs/integrations/PICKS.mdis the rubric for the next pick. - Type a quick prompt into the dock; paste a polished prompt into any IDE. The companion analyses your raw input against the typed Graph-RAG memory + code graph and emits a sectioned-markdown block (Problem / Context / Files / Acceptance / Anti-patterns / Prompt) ready to drop into Cursor / Claude Code / Continue / Copilot. The host LLM receives the same context Mnem has — without needing mnemo's MCP server itself.
local_onlynode flag + retrieval filter — frontmatterlocal_only: true, any_privatepath segment, or a[LOCAL ONLY]body marker auto-flags a node. The prompt-architect skill passesexclude_local_only=trueso paste-bound output never references locally-scoped notes. The dock surfaces a pre-emit warning whenever a flagged node was dropped before paste.- T9 in the open agent-memory benchmark locks
mnemo.answer_correctness > vanilla.answer_correctnessin CI — the mirror of T1'svanilla > mnemoon rederivation. Both invariants together pin the typed-Graph-RAG substrate wedge. - v4.7.0 substrate (the foundation v5 builds on) — locked 26-tool MCP contract test, Cursor + OpenAI Agents SDK 5-minute mount guides, flag-gated hosted
/v1/querywith API-key auth + metering + 429 quota enforcement, ROI dashboard card, and the published CC-BY-4.0 agent-memory benchmark spec v0 with a reference MIT harness atbench/.
v4.x — Nebula custom graph engine + design-system + responsive
- The Nebula at
/graphis now a custom WebGL galaxy. The whole third-party renderer stack (cytoscape, then sigma + graphology) is gone. The layout is computed server-side in Python — a deterministic, community-separating spectral embedding sheared into a face-on log-spiral galaxy, cached byscope_key + fingerprint + LAYOUT_VERSION(the browser is a pure renderer). It is drawn by a purpose-built single-file regl renderer (nebula-gl.js): crisp extension-free SDF star points graded by galactic radius, a rendered barred core-glow + full-viewport deep-space dust, length/zoom-graded curved edge filaments, every-node labels (frame-budgeted), a slow GPU-only galactic drift, and click-to-focus that flies + freezes on the node. Scales to 11k+ nodes; idle costs zero. - C1 design-system contract — every primitive value single-sourced in
app.css :root+ a guard test; a documented page-shell contract so the v3.2-class layout bug can't return. - Fully responsive / adaptive layout — breakpoint tokens, off-canvas drawers, collapse primitives, a strict no-overflow rule, responsive-contract tests.
- Provider registry, a dedicated settings surface, and chat-surface/backlog refinements.
v3 — Mnem, the agentic companion
- A tool-using agent over your own memory + code graph, not a pre-canned RAG box. Four providers behind one abstraction (Anthropic / OpenAI / Google / Ollama), BYO API keys (env > repo
.env> OS keychain > 0600 fallback; never insettings.json). - Permission protocol — risk-tagged tools;
confirm/dangercalls pause forPOST /v1/chat/<id>/permit;allow_alwayspersists per-project. - Conversations are first-class SQLite rows with an SSE event stream; a
/chatpage + a Mnem companion dock on every page, plus themnemo:docskill (```mnemo-draftfences → one-click Save as memory). - MCP server (
mnemo mcp, stdio) — the same tool surface, so Cursor / Claude Desktop / Codex / Windsurf get mnemo for free.
v2 — Code Intelligence + language parity + Workspaces
- Typed code graph — every
code_repobecomescode_module/code_function/code_class/code_method/code_route/code_component/code_endpointnodes withimports/defines/method_of/calls/routes_to/at_endpointedges, plus commit provenance (touched_by) from git history. - Tier 1 tree-sitter ingestion with full structural extraction at Python parity for Python, JavaScript, TypeScript, Go, and Django.
- Tier 2 call-graph resolver — scope resolution with constructor +
self/thislookups (same-file 0.95, cross-file via imports 0.8). - Tier 3 framework extractors — FastAPI / Flask / Express (backend) + React (frontend) emit routes/components anchored on a shared
code_endpointURI so cross-stack sitemap queries work. - Source auto-router (
mnemo source addclassifies kind + dry-run preview + 50k-file guard), the/codeUI family, 7 code skills, and named Workspaces — switchable bundles ofproject_keys+ filter prefs; with no active workspace the UI drops into BASE-only mode.
v1.2 — Learning to Listen (carried forward)
- Feedback events (thumb up/down per hit; auto-detected re-queries flag missed hits), MMR re-rank to de-duplicate paraphrases, and a coordinate-descent auto-tuner over the 6-term scoring weights (MRR objective, threshold-gated).
Quick start
Requires Python 3.11+ and uv.
# Install
git clone https://github.com/mmct-jsc/mnemo.git
cd mnemo
./install.sh # or .\install.ps1 on Windows
# First index of your existing memory
mnemo reindex
# Add a code repo (auto-router proposes the kind)
mnemo source add ~/code/my-project # picks code_repo when it sees .git/ + source files
# Open the UI
mnemo ui
The install script:
- Syncs the daemon dependencies via
uv sync(incl. tree-sitter + 8 bundled grammars). - Drops a
mnemoshim onto your PATH (~/.local/bin/mnemo). - Registers the
mnemo mcpserver with Claude Code, wires a one-line status line (non-clobbering), and prints the two/plugincommands that install the plugin (commands + hooks + skills).
Then, inside Claude Code, run /plugin marketplace add mmct-jsc/mnemo and /plugin install mnemo@mnemo, and restart. The /mnemo-* commands appear immediately; the SessionStart memory banner + per-prompt auto-injection begin next session. Run mnemo doctor to confirm every link is green.
Use mnemo from any MCP-capable agent
mnemo's MCP server (mnemo mcp, stdio) is provider-neutral — same 30-tool surface, any agent. Phase 1 of the substrate roadmap ships two flagship 5-minute mount guides:
- Cursor (IDE-embedded) — one block in
~/.cursor/mcp.json, window reload, done. - OpenAI Agents SDK (agent-loop) — Python + TypeScript snippets wiring
MCPServerStdiodirectly to mnemo.
See docs/integrations/ for the full index, the selection rubric, and the deferred picks (Continue, Zed, Gemini CLI, LangGraph) with the rationale for each defer.
Benchmark
The agent-memory benchmark (CC-BY-4.0) is mnemo's reproducible eval for typed Graph-RAG agent memory — the missing layer every modern AI coding agent reinvents in private. v0 defines 8 tasks (T1 follow-up → T8 budget compliance), 4 metrics (re-derivation rate, tokens-to-answer, citation precision, answer correctness), and 2 reference baselines (vanilla no-memory + reference mnemo).
- Spec: docs/benchmark/agent-memory-spec-v0.md
- Harness (MIT):
bench/—MemoryProtocol,run_task, fixtures, baseline agents. - First case study: docs/case-studies/2026-05-mnemo-self-host.md — real numbers from the dogfooded mnemo install.
- Live ROI on every install:
GET /v1/roi/summary+ the dashboard "ROI summary" card.
External implementations welcome — open an issue with a new task / metric / non-mnemo agent.
Slash commands
/mnemo-query <text>— ad-hoc memory query/mnemo-add— capture an insight as a new memory node/mnemo-reindex— full rescan of all sources/mnemo-ui— open the web UI/mnemo-status— daemon health, node counts/mnemo-hooks <on|off>— toggle automatic injection
Skills
v1 workflow skills (7)
| Skill | Phases |
|---|---|
mnemo:implement-platform | requirements → analysis → design → decision → planning → specs → implementation → verification → docs |
mnemo:debug | reproduce → hypothesize → instrument → bisect → fix → verify → RCA |
mnemo:refactor | measure → propose → atomic commits → verify behavior + perf |
mnemo:add-knowledge | novelty check → categorize → write → graph-link → reindex |
mnemo:query-knowledge | intent classify → hybrid retrieve → budget-compress → cite |
mnemo:onboard-project | scan → extract conventions → build initial nodes → user-confirm |
mnemo:review | pull project review memory → checklist → review → capture lessons |
v2 code skills (7)
| Skill | What it does |
|---|---|
mnemo:explore-codebase | shape-of-the-codebase tour: top modules, central functions, route surface, lessons |
mnemo:trace-call | walks Tier 2 calls edges from a target function; surfaces callers + callees with line ranges |
mnemo:trace-route | the cross-stack sitemap walker: Component → Endpoint → Route → Handler → Service |
mnemo:explain-design | synthesizes a design narrative from plan_doc + memory_project nodes |
mnemo:debug-with-code | adds a phase-3 code-graph overlay to mnemo:debug (stack-trace → hypothesis chain) |
mnemo:why-is-this-here | decision provenance: code → commits that touched it → memory_feedback that motivated them |
mnemo:impact-analysis | blast radius via reverse calls + routes_to + at_endpoint, with memory_feedback warnings overlaid |
Architecture
- docs/architecture.md — three tiers, data model, retrieval algorithm, and what we deliberately don't do.
- docs/plans/2026-05-09-mnemo-design.md — full v1 design.
- docs/plans/2026-05-11-mnemo-v2.0-design.md — full v2.0 (Code Intelligence) design.
- docs/plans/2026-05-14-mnemo-v3-design.md — full v3 (Mnem agentic companion) design.
- docs/plans/2026-05-16-mnemo-v4-design.md — full v4.x (design-system contract) design.
- docs/plans/2026-05-17-mnemo-v4.6-custom-graph-engine-design.md — the custom Nebula graph engine (server layout + WebGL renderer) design.
- docs/workflows/index.md — guided summaries of the workflow skills.
- docs/examples/sample-queries.md — real queries against a real
~/.claude/memory, with the actual scored hits. - CHANGELOG.md — version-by-version diff.
Contributing
See CONTRIBUTING.md.
Hard rules:
- No
Co-Authored-Bytrailers on commits. Ever. - No emojis in code, docs, or commit messages unless explicitly requested.
- Conventional commit prefixes (
feat:/fix:/chore:/docs:/test:/refactor:/perf:). - HEREDOC for multi-line commit messages.
- Daemon binds to
127.0.0.1only; never0.0.0.0.
License
MIT — see LICENSE.