convez.ai
MCP ServerProdutividadeAvançado
mmct-jsc

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 GitHub
InicialPluginScore · de 0 a 100

MCP 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/mnemo

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
75%
Último commit
há 4 meses
Versão
v6.2.1
Issues abertas
7
Contribuidores
2

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

CI Python 3.11+ License: MIT Version Tests ruff Live demo Buy me a coffee

▶ 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 mcp stdio server, seven documented hosts, one tool surface — docs/integrations/PICKS.md is 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_only node flag + retrieval filter — frontmatter local_only: true, any _private path segment, or a [LOCAL ONLY] body marker auto-flags a node. The prompt-architect skill passes exclude_local_only=true so 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_correctness in CI — the mirror of T1's vanilla > mnemo on 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/query with 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 at bench/.

v4.x — Nebula custom graph engine + design-system + responsive

  • The Nebula at /graph is 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 by scope_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 in settings.json).
  • Permission protocol — risk-tagged tools; confirm/danger calls pause for POST /v1/chat/<id>/permit; allow_always persists per-project.
  • Conversations are first-class SQLite rows with an SSE event stream; a /chat page + a Mnem companion dock on every page, plus the mnemo:doc skill (```mnemo-draft fences → 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_repo becomes code_module / code_function / code_class / code_method / code_route / code_component / code_endpoint nodes with imports / defines / method_of / calls / routes_to / at_endpoint edges, 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/this lookups (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_endpoint URI so cross-stack sitemap queries work.
  • Source auto-router (mnemo source add classifies kind + dry-run preview + 50k-file guard), the /code UI family, 7 code skills, and named Workspaces — switchable bundles of project_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:

  1. Syncs the daemon dependencies via uv sync (incl. tree-sitter + 8 bundled grammars).
  2. Drops a mnemo shim onto your PATH (~/.local/bin/mnemo).
  3. Registers the mnemo mcp server with Claude Code, wires a one-line status line (non-clobbering), and prints the two /plugin commands 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 MCPServerStdio directly 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).

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)

SkillPhases
mnemo:implement-platformrequirements → analysis → design → decision → planning → specs → implementation → verification → docs
mnemo:debugreproduce → hypothesize → instrument → bisect → fix → verify → RCA
mnemo:refactormeasure → propose → atomic commits → verify behavior + perf
mnemo:add-knowledgenovelty check → categorize → write → graph-link → reindex
mnemo:query-knowledgeintent classify → hybrid retrieve → budget-compress → cite
mnemo:onboard-projectscan → extract conventions → build initial nodes → user-confirm
mnemo:reviewpull project review memory → checklist → review → capture lessons

v2 code skills (7)

SkillWhat it does
mnemo:explore-codebaseshape-of-the-codebase tour: top modules, central functions, route surface, lessons
mnemo:trace-callwalks Tier 2 calls edges from a target function; surfaces callers + callees with line ranges
mnemo:trace-routethe cross-stack sitemap walker: Component → Endpoint → Route → Handler → Service
mnemo:explain-designsynthesizes a design narrative from plan_doc + memory_project nodes
mnemo:debug-with-codeadds a phase-3 code-graph overlay to mnemo:debug (stack-trace → hypothesis chain)
mnemo:why-is-this-heredecision provenance: code → commits that touched it → memory_feedback that motivated them
mnemo:impact-analysisblast radius via reverse calls + routes_to + at_endpoint, with memory_feedback warnings overlaid

Architecture

Contributing

See CONTRIBUTING.md.

Hard rules:

  • No Co-Authored-By trailers 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.1 only; never 0.0.0.0.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados