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 GitHubMCP 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/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
- 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
ghCLI 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/*.mddiscovery and search - CLAUDE.md configs — project instructions from all repos
- Convergence targets —
docs/targets.mdfrom all repos - Implementation plans —
.planning/directories from all repos - Audit logs —
docs/audit-log.mdfrom 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
/clearboundaries;mnemo_restoreretrieves 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
allowedToolsrules 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.exetoC:\Program Files\mnemo\, - registers mnemo as a Windows Service (auto-start on boot, restart-on-failure, survives logoff / battery / sleep),
- patches
%USERPROFILE%\.claude.jsonwith 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
mnemofor 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 minimalPATHthat typically excludes theclaudebinary. The Homebrew formula's service block setsPATHto include$(brew --prefix)/binand~/.claude/localautomatically. If you run mnemo via a custom plist or systemd unit, setPATHexplicitly to include the directory whereclaudeis 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
| Tool | Description |
|---|---|
mnemo_search | Full-text search with context (like grep -C). Repo filter, configurable before/after context. |
mnemo_sessions | List sessions by recency; filter by project, repo, work type, or session type |
mnemo_read_session | Read messages from a specific session (supports prefix IDs) |
mnemo_compacted_session | Distilled view of a session — compaction summaries plus the live addenda tail past the latest cursor |
mnemo_recent_activity | Per-repo summary of recent session activity with work types and topics |
mnemo_status | Rich status report: repos, sessions, and conversation excerpts, plus a transcript-ingest freshness/lag diagnostics block |
mnemo_doctor | Self-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_chain | Retrieve the full /clear-bounded session chain for any session |
mnemo_self | Discover the calling session's ID via two-phase nonce protocol |
mnemo_decisions | Search past decisions (proposal + confirmation pairs) across sessions |
mnemo_session_structure | Structural summary of a session — counts of entry types, stop_reasons, content-block kinds, tool names |
mnemo_tool_result | Raw tool-result payload by (session_id, tool_use_id) — supports byte offset + truncation |
mnemo_locate_uuid | Locate any entry by full or prefix UUID across six uuid sources, with surrounding context |
Cross-project knowledge
| Tool | Description |
|---|---|
mnemo_memories | Search auto-memory files from all projects |
mnemo_get_memory | Read the raw markdown body of a named memory file (or list memories) |
mnemo_skills | Search skill files from ~/.claude/skills/ |
mnemo_configs | Search CLAUDE.md project instructions from all repos |
mnemo_targets | Search convergence targets from all repos |
mnemo_plans | Search implementation plans from all repos |
mnemo_audit | Search audit logs from all repos |
mnemo_docs | Search markdown, text, and PDF documentation from all repos |
mnemo_todos | Query 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_set | Edit an existing TODO item in place (status / due / priority) — line-precise, atomic, stale-guarded write-back to the source file |
mnemo_todo_add | Append a new TODO item to a tracked TODO file, optionally under a heading |
External source indexing
| Tool | Description |
|---|---|
mnemo_commits | Search git commits across all tracked repos |
mnemo_prs | Search GitHub PRs and issues across all repos |
mnemo_ci | Search CI/CD run history (GitHub Actions) with failure log indexing |
mnemo_images | Search images via FTS on descriptions/OCR, semantic embeddings, or visual similarity |
Analytics and observability
| Tool | Description |
|---|---|
mnemo_usage | Token usage analytics with cost estimates, grouped by day/model/repo |
mnemo_whatsup | Live session resource monitor: CPU%, RSS, memory pressure |
mnemo_permissions | Analyse tool usage patterns to suggest allowedTools rules |
mnemo_discover_patterns | Find workaround patterns suggesting missing features |
Database and templates
| Tool | Description |
|---|---|
mnemo_query | Read-only SQL or sqldeep nested syntax against the full database |
mnemo_repos | List repos with paths, session counts, last activity. Supports globs. |
mnemo_stats | Index statistics — sessions and messages by type |
mnemo_define | Save a reusable parameterised query template |
mnemo_evaluate | Execute a named query template with parameters |
mnemo_list_templates | List all saved query templates |
Context restoration
| Tool | Description |
|---|---|
mnemo_restore | Retrieve compacted context from prior /clear boundaries |
Vault
| Tool | Description |
|---|---|
mnemo_vault_sync | Trigger an immediate vault sync (writes all changed notes to vault_path) |
mnemo_vault_status | Show vault path and current Markdown file count |
Runtime configuration
| Tool | Description |
|---|---|
mnemo_config | Read 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:
-
Generate the local mTLS material and print the public cert:
mnemo print-endpoint > /tmp/<hostname>.pemFirst invocation generates
~/.mnemo/endpoint/{cert.pem,key.pem}(key mode 0600, ECDSA P-256, 10-year validity, regenerated on corruption or expiry). -
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). -
Print this host's federation URL:
mnemo print-federated-addr # → https://<hostname>:19420/mcp -
On each peer, declare the link in
~/.mnemo/config.json:{ "linked_instances": [ { "name": "alice", "url": "https://alice.example:19420/mcp", "peer_cert": "alice" } ] }peer_certis 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. -
Restart the daemon (
brew services restart mnemo). -
Verify with
mnemo ping-peer <name>— invokesmnemo_statson 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— usemnemo_restoreto 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_activityandmnemo_searchto generate a summary of recent work across repos after being away - Convergence evaluation — query
mnemo_recent_activityto 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 withmnemo_decisions, or audit what commands were run withmnemo_who_ran - Custom dashboards — use
mnemo_querywith 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.