convez.ai
MCP ServerProdutividadeIntermediário
marcelocantos

mnemo — Memória de Transcrições Claude Code

marcelocantos/mnemo

Memória pesquisável de todas as sessões Claude Code com indexação automática

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server em Go que indexa e disponibiliza busca em transcrições de sessões Claude Code, commits Git, PRs GitHub, documentação de projetos e mais. Mantém índice SQLite FTS5 em tempo real com dashboard web integrado, monitoramento de sessões ativas e análise de custos de tokens.

Instalação

$npx convez-ai marcelocantos/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
3
Acompanhando
0
Saúde
42%
Último commit
há 3 dias
Versão
v0.118.0
Issues abertas
2
Contribuidores
3

Casos de uso

  • Recuperar contexto e decisões de sessões anteriores durante desenvolvimento
  • Buscar padrões de workarounds em histórico de transcrições
  • Analisar uso de tokens e custos agregados por modelo, repositório ou período
  • Monitorar sessões ativas em tempo real com métricas de CPU e memória
  • Pesquisar documentação, commits Git e PRs GitHub indexados automaticamente

Veredito

Ferramenta robusta para desenvolvedores que usam Claude Code intensivamente — oferece visibilidade completa sobre histórico de sessões, decisões e custos. Excelente para equipes que precisam rastrear contexto em projetos complexos ou multi-repositório, mas requer familiaridade com MCP e CLI.

README

A tradução para o português deste README ainda está na fila.

mnemo

Searchable memory across all Claude Code session transcripts. Runs as a persistent MCP server — available in every Claude Code session.

mnemo indexes JSONL transcript files from ~/.claude/projects/, maintains a realtime SQLite FTS5 index, and exposes 30+ tools via MCP. New transcripts are picked up automatically via filesystem watching. A browser dashboard is served on the same port at http://localhost:19419 — no separate process or build step required.

What it indexes:

  • Session transcripts — all content block types (text, tool use, tool results, thinking), with full-text search and surrounding context
  • Images — inline and file-path images from transcripts, with AI descriptions, Apple Vision OCR, and CLIP embeddings for semantic and visual-similarity search
  • Git commits — full history from all tracked repos, searchable by message, author, date
  • GitHub PRs and issues — backfilled via gh CLI across all repos in session history
  • CI/CD runs — GitHub Actions history with failure log indexing
  • Project documentation — markdown, plain text, and PDF files from docs/, design/, notes/, repo root, and more
  • Auto-memory files — cross-project memory search across all ~/.claude/projects/*/memory/ directories
  • Skills — ~/.claude/skills/*.md discovery and search
  • CLAUDE.md configs — project instructions from all repos
  • Convergence targets — docs/targets.md from all repos
  • Implementation plans — .planning/ directories from all repos
  • Audit logs — docs/audit-log.md from all repos
  • Decisions — automatically detected proposal+confirmation pairs across all sessions

What else it does:

  • Live session monitoring — per-session CPU%, RSS, and memory pressure for active Claude Code processes
  • Session chain detection — links /clear-bounded sessions into continuous work spans, with definitive detection for live transitions and heuristic fallback for historical sessions
  • Context compaction — background summariser preserves context across /clear boundaries; mnemo_restore retrieves it
  • Token usage analytics — aggregated input/output/cache tokens with cost estimates, grouped by day, model, or repo
  • Query templates — save and reuse parameterised SQL queries
  • Pattern discovery — analyses transcript history to find workaround patterns suggesting missing features
  • Permission analysis — suggests allowedTools rules from actual tool usage patterns
  • Raw SQL access — read-only queries against the full database, including sqldeep nested syntax for hierarchical JSON output

Dashboard

Open http://localhost:19419 in a browser after starting mnemo. The dashboard is embedded in the binary — no separate install needed.

Row 1 — Index overview Session and message counts, hourly token rate, subagent session count, and DB health (file size, all-time cost, images, decisions, git commits).

Row 2 — Cost and activity Cost by model, cost by repo, daily cost (today and yesterday), and recent activity by repo.

Row 3 — Sessions Scrollable conversation list (filterable by session type) alongside a live session monitor that polls running claude processes every 5s and correlates them with session metadata.

Row 4 — Context pressure Per-session peak context window usage, colour-coded green / orange / red, scrollable when more than four rows are present.

Dark/light theme is toggled via the button in the top-right corner and persisted in localStorage.

Quick start

Tell your agent:

Install mnemo from https://github.com/marcelocantos/mnemo — brew
install, start the service, register it as an MCP server, and
restart the session. Follow the agents-guide.md in the repo.

Or do it yourself:

brew install marcelocantos/tap/mnemo
brew services start mnemo
claude mcp add --scope user --transport http mnemo http://localhost:19419/mcp

Then restart your Claude Code session. The mnemo_* tools will be available in every session from that point on.

Install

macOS / Linux

brew install marcelocantos/tap/mnemo

Windows

Download the installer for your architecture from the releases page — mnemo-<version>-windows-amd64-setup.exe for Intel/AMD PCs or mnemo-<version>-windows-arm64-setup.exe for Copilot+ / Surface Pro X / other Windows-on-ARM devices — and double-click it. The installer:

  • copies mnemo.exe to C:\Program Files\mnemo\,
  • registers mnemo as a Windows Service (auto-start on boot, restart-on-failure, survives logoff / battery / sleep),
  • patches %USERPROFILE%\.claude.json with an MCP URL that includes ?user=<your username> so the service routes requests to your home directory correctly,
  • shows up in Add/Remove Programs as mnemo for a clean uninstall.

No terminal required. Restart your Claude Code session after install.

Build from source

Requires Go and CGo for SQLite:

go build -tags "sqlite_fts5" -o bin/mnemo .

On Windows, CGo requires a MinGW-w64 or LLVM clang toolchain on the PATH — Go cgo does not use MSVC. The simplest setup is MSYS2 with the mingw-w64-x86_64-toolchain package. Release binaries from the GitHub release page are statically linked and have no external runtime requirements. Live-session discovery (mnemo_whatsup, lsof-based liveness) degrades gracefully on Windows; transcript indexing and all query tools work identically.

Running

As a service (recommended — survives reboots):

brew services start mnemo       # macOS / Linuxbrew

On Windows the installer registers mnemo as a Windows Service (sc query mnemo to inspect, services.msc to manage). The service runs as LocalSystem and routes each request to the right user's home based on the ?user=<name> query parameter on the MCP URL — written into %USERPROFILE%\.claude.json automatically by the installer.

Logs on macOS: $(brew --prefix)/var/log/mnemo.log.

PATH note for service deployments: mnemo's compactor shells out to claude -p. Services (launchd, systemd) inherit a minimal PATH that typically excludes the claude binary. The Homebrew formula's service block sets PATH to include $(brew --prefix)/bin and ~/.claude/local automatically. If you run mnemo via a custom plist or systemd unit, set PATH explicitly to include the directory where claude is installed. Without it, compaction will fail with a logged ERROR.

Manually:

mnemo               # listen on :19419 (default)
mnemo --addr :8080  # custom port

Registering as an MCP server

Claude Code (global install to ~/.claude.json):

claude mcp add --scope user --transport http mnemo http://localhost:19419/mcp

Generic MCP client JSON config:

{
  "mcpServers": {
    "mnemo": {
      "type": "http",
      "url": "http://localhost:19419/mcp"
    }
  }
}

Restart your agent session after registration — tools registered mid-session are not picked up.

Vault export (optional)

Export your knowledge graph as Markdown notes compatible with Obsidian and Logseq. Human annotations sync back into mnemo's FTS5 search within ~2 seconds. Zero overhead when disabled.

Add to ~/.mnemo/config.json and restart the daemon — or, with a running daemon, ask any MCP client to call mnemo_config with op=write and patch={"vault_path": "~/Documents/mnemo-vault"} and the change is adopted in-process:

{
  "vault_path": "~/Documents/mnemo-vault"
}

Full setup guide: internal/vault/README.md

MCP Tools

Transcript search and browsing

ToolDescription
mnemo_searchFull-text search with context (like grep -C). Repo filter, configurable before/after context.
mnemo_sessionsList sessions by recency; filter by project, repo, work type, or session type
mnemo_read_sessionRead messages from a specific session (supports prefix IDs)
mnemo_compacted_sessionDistilled view of a session — compaction summaries plus the live addenda tail past the latest cursor
mnemo_recent_activityPer-repo summary of recent session activity with work types and topics
mnemo_statusRich status report: repos, sessions, and conversation excerpts, plus a transcript-ingest freshness/lag diagnostics block
mnemo_doctorSelf-diagnostics: per-check health report (ok/warn/fail + remediation) — summariser workdir, claude on PATH, configured roots, the compaction circuit-breaker, backfill-since-startup, db responsiveness. Same data backs GET /health, the dashboard health page, and opt-out OS notifications
mnemo_chainRetrieve the full /clear-bounded session chain for any session
mnemo_selfDiscover the calling session's ID via two-phase nonce protocol
mnemo_decisionsSearch past decisions (proposal + confirmation pairs) across sessions
mnemo_session_structureStructural summary of a session — counts of entry types, stop_reasons, content-block kinds, tool names
mnemo_tool_resultRaw tool-result payload by (session_id, tool_use_id) — supports byte offset + truncation
mnemo_locate_uuidLocate any entry by full or prefix UUID across six uuid sources, with surrounding context

Cross-project knowledge

ToolDescription
mnemo_memoriesSearch auto-memory files from all projects
mnemo_get_memoryRead the raw markdown body of a named memory file (or list memories)
mnemo_skillsSearch skill files from ~/.claude/skills/
mnemo_configsSearch CLAUDE.md project instructions from all repos
mnemo_targetsSearch convergence targets from all repos
mnemo_plansSearch implementation plans from all repos
mnemo_auditSearch audit logs from all repos
mnemo_docsSearch markdown, text, and PDF documentation from all repos
mnemo_todosQuery TODO items indexed from TODO.md / todos.md files (Obsidian Tasks dialect) — filter by status, tag, priority, section, due date (overdue/due-soon/no-date), and full text
mnemo_todo_setEdit an existing TODO item in place (status / due / priority) — line-precise, atomic, stale-guarded write-back to the source file
mnemo_todo_addAppend a new TODO item to a tracked TODO file, optionally under a heading

External source indexing

ToolDescription
mnemo_commitsSearch git commits across all tracked repos
mnemo_prsSearch GitHub PRs and issues across all repos
mnemo_ciSearch CI/CD run history (GitHub Actions) with failure log indexing
mnemo_imagesSearch images via FTS on descriptions/OCR, semantic embeddings, or visual similarity

Analytics and observability

ToolDescription
mnemo_usageToken usage analytics with cost estimates, grouped by day/model/repo
mnemo_whatsupLive session resource monitor: CPU%, RSS, memory pressure
mnemo_permissionsAnalyse tool usage patterns to suggest allowedTools rules
mnemo_discover_patternsFind workaround patterns suggesting missing features

Database and templates

ToolDescription
mnemo_queryRead-only SQL or sqldeep nested syntax against the full database
mnemo_reposList repos with paths, session counts, last activity. Supports globs.
mnemo_statsIndex statistics — sessions and messages by type
mnemo_defineSave a reusable parameterised query template
mnemo_evaluateExecute a named query template with parameters
mnemo_list_templatesList all saved query templates

Context restoration

ToolDescription
mnemo_restoreRetrieve compacted context from prior /clear boundaries

Vault

ToolDescription
mnemo_vault_syncTrigger an immediate vault sync (writes all changed notes to vault_path)
mnemo_vault_statusShow vault path and current Markdown file count

Runtime configuration

ToolDescription
mnemo_configRead or update ~/.mnemo/config.json without restarting the daemon. op=read returns the current effective config; op=write with a JSON patch merges, validates, persists, and hot-reloads. vault_path, workspace_roots, extra_project_dirs, and synthesis_roots are applied live; linked_instances is persisted but requires a restart.

For full parameter documentation, see agents-guide.md or run mnemo --help-agent.

Federation across linked instances

Multiple mnemo daemons (different machines, different Claude Code projects) can be peered so a single query reaches every host's index. mTLS authentication, per-peer pinned trust, parallel fan-out, graceful degradation under peer failure.

Setup

On each host:

  1. Generate the local mTLS material and print the public cert:

    mnemo print-endpoint > /tmp/<hostname>.pem
    

    First invocation generates ~/.mnemo/endpoint/{cert.pem,key.pem} (key mode 0600, ECDSA P-256, 10-year validity, regenerated on corruption or expiry).

  2. Distribute that PEM to peer hosts. Each peer drops it into its own ~/.mnemo/peers/<name>.pem (any name is fine; it's the filename the peer uses to refer to this host).

  3. Print this host's federation URL:

    mnemo print-federated-addr
    # → https://<hostname>:19420/mcp
    
  4. On each peer, declare the link in ~/.mnemo/config.json:

    {
      "linked_instances": [
        {
          "name": "alice",
          "url": "https://alice.example:19420/mcp",
          "peer_cert": "alice"
        }
      ]
    }
    

    peer_cert is either the basename of the file under ~/.mnemo/peers/ (without .pem) or an inline PEM block. Validation fails loud at startup on duplicate names, non-https URLs, or unresolvable certs.

  5. Restart the daemon (brew services restart mnemo).

  6. Verify with mnemo ping-peer <name> — invokes mnemo_stats on the peer over mTLS and prints the response.

Behaviour

When linked_instances is non-empty, 16 read-shaped tools wrap their response in a FanoutEnvelope:

{
  "local": <local result>,
  "peers": [{"instance": "alice", "result": <alice's result>}],
  "warnings": [{"instance": "bob", "error_kind": "timeout", "message": "..."}]
}

Slow or offline peers drop into warnings[] with a typed error_kind (timeout, connection_refused, tls_handshake, server_error, malformed_response, connect_failed); the local response returns regardless. Per-peer timeout default 5s.

Write- and control-shaped tools (mnemo_self, template register/evaluate, mnemo_restore, mnemo_whatsup, mnemo_docs, mnemo_synthesis, mnemo_permissions, mnemo_query, mnemo_stats, mnemo_status, mnemo_chain) bypass federation entirely.

When linked_instances is empty or absent, federation is disabled and all tools return their original local-only response shape unchanged (backwards-compatible).

Workflows mnemo enables

mnemo's tools are building blocks. Some examples of what you can build on top of them:

  • Context restoration after /clear — use mnemo_restore to retrieve compacted summaries from prior conversation spans, so a fresh session can pick up where the last one left off
  • "Where are we?" briefings — combine mnemo_recent_activity and mnemo_search to generate a summary of recent work across repos after being away
  • Convergence evaluation — query mnemo_recent_activity to understand recent movement before assessing whether targets are on track
  • Cross-repo knowledge lookups — search memories, configs, targets, and plans from any project without leaving your current session
  • Session forensics — trace a multi-session work span with mnemo_chain, replay decisions with mnemo_decisions, or audit what commands were run with mnemo_who_ran
  • Custom dashboards — use mnemo_query with SQL or sqldeep syntax to build project-specific analytics (message volume, tool usage patterns, active repos)

These workflows can be codified as Claude Code skills for one-command invocation.

Agent guide

If you use an agentic coding tool, run mnemo --help-agent for the full agent guide, or include agents-guide.md in your project context.

Licence

Apache 2.0 — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados