MCP Memory-mesh

Um servidor MCP que dá ao Claude Code memória persistente entre sessões (código aberto, SQLite)

Documentação

MemoryMesh

SQLite para memória de IA. Camada de memória persistente para agentes MCP e copilotos de codificação — local-first, zero nuvem, funciona em 5 minutos.

Veja em ação: Claude Code lembrando decisões de projeto entre sessões.

💻 Copilotos de codificação	🤖 Agentes MCP	📚 Assistentes de pesquisa
Lembre-se de decisões de arquitetura, bugs e preferências entre sessões	Memória persistente em qualquer cliente compatível com MCP	Recuperação semântica sobre suas notas, artigos e documentos

Em funcionamento em 5 minutos

pip install memorymesh-mcp
cp config.example.yaml ~/.memorymesh/config.yaml
# edit config.yaml — point at your folders
memorymesh index ~/Documents
memorymesh search "how did I configure the debounce"

Conecte-o ao Claude Desktop. Encontre o arquivo de configuração em:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "memorymesh": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/absolute/path/to/memory-mesh",
        "memorymesh", "start"
      ]
    }
  }
}

Reinicie o Claude Desktop. As 15 ferramentas aparecem automaticamente.

Por que existe

Toda conversa de IA começa do zero. Claude não sabe qual decisão de arquitetura você tomou na semana passada. Cursor não lembra do bug que você corrigiu ontem. O contexto morre quando a sessão termina.

Mem0 exige uma conta na nuvem. Zep precisa de um servidor em execução e um banco de dados. LangMem amarra você ao ecossistema LangChain. Nenhum deles fala MCP nativamente.

O MemoryMesh roda inteiramente na sua máquina. Ele indexa seus arquivos em um armazenamento local SQLite + ChromaDB e os expõe por meio de 15 ferramentas MCP. Ele nunca toca a rede, a menos que você configure um conector. Qualquer cliente MCP — Claude Desktop, Cursor, seu próprio agente — obtém memória persistente com uma mudança de configuração.

Como funciona

O indexador observa seus arquivos, divide-os em pedaços com parsers cientes de formato e armazena embeddings localmente. O mecanismo de busca funde resultados densos e esparsos, e um re-ranker de cross-encoder pontua os candidatos.

                   ┌──────────────────────────────┐
  MCP clients ───▶ │         MemoryMesh           │
(Claude Desktop,   │  ┌────────────────────────┐  │
 Cursor, agents)   │  │ MCP Tools (FastMCP):   │  │
                   │  │  search_memory         │  │
                   │  │  list_sources          │  │
                   │  │  get_document          │  │
                   │  │  index_now             │  │
                   │  └──────────┬─────────────┘  │
                   │             ▼                 │
                   │     Search Engine             │
                   │   dense + BM25 → RRF          │
                   │             │                 │
                   │   ┌─────────┴──────────┐      │
                   │   ▼                    ▼      │
                   │ ChromaDB            BM25      │
                   │ (embeddings)     (sparse)     │
                   │   ▲                    ▲      │
                   │   └──────── Indexer ───┘      │
                   │                ▲              │
                   │           Watchdog            │
                   └────────────────┬──────────────┘
                                    ▼
                             Your filesystem

Indexação: o observador de arquivos detecta mudanças → a deduplicação SHA-256 ignora arquivos inalterados → parser (txt/md/pdf/docx/code/obsidian/email/calendar/browser) → chunker (tree-sitter para código, por cabeçalho para markdown, recursivo para texto) → embeddings sentence-transformers → ChromaDB + BM25.

Busca: consulta → expansão de consulta (variantes lexicais + HyDE) → busca paralela densa + esparsa → Fusão de Rank Recíproco (k=60) → re-ranker bge-reranker-v2-m3 → resultados top-k com caminho, pré-visualização, pontuação e metadados.

RAG (opcional): ask_memory → recuperação search_memory → Ollama generate() → resposta fundamentada com fontes citadas.

O que está incluído

O MemoryMesh vem com busca híbrida (embeddings densos + BM25 + RRF + re-ranker cross-encoder), camadas de memória quente/morna/fria com decaimento de esquecimento configurável e uma linha do tempo de eventos episódicos. 47 conectores puxam dados de Jira, Notion, GitHub, Slack, e-mail, histórico do navegador, Spotify e mais. 15 ferramentas MCP expõem tudo para qualquer cliente compatível com MCP. Um observador de arquivos em tempo real re-indexa arquivos alterados em segundos, sem acionamento manual.

Lista completa de recursos

Recurso	Status
Indexação local de arquivos (txt, md, code, pdf, docx)	✅
Parser de cofre Obsidian (frontmatter + wikilinks)	✅
Parser de exportação HTML do Notion	✅
Exportações de conversas de IA (Claude, ChatGPT JSON)	✅
Indexação de e-mail (`.mbox` via stdlib)	✅
Indexação de calendário (`.ics` / iCalendar)	✅
Histórico do navegador (Chrome / Firefox / Brave SQLite)	✅
Busca híbrida — densa + BM25 + RRF	✅
Re-ranker cross-encoder (`bge-reranker-v2-m3`)	✅
Expansão de consulta — variantes lexicais + HyDE	✅
RAG com LLM local via Ollama (ferramenta `ask_memory`)	✅
Indexação de resumo multi-vetor para recall abstrato	✅
Servidor MCP — 15 ferramentas, stdio + streamable-http	✅
Indexação incremental em tempo real (watchdog + debounce)	✅
Chunking de código com Tree-sitter (Python, JS, TS, Go, Rust…)	✅
Recuperador de Documento Pai (`extended_preview`)	✅
Multiplataforma — Windows / Linux / macOS	✅
Reconciliação pós-crash	✅
OCR opcional para PDFs escaneados (Tesseract / EasyOCR)	✅
Log de auditoria de privacidade (apenas hashes de consulta, sem texto claro)	✅
CI do GitHub Actions (Ubuntu / Windows / macOS)	✅
Docker + docker-compose	✅
Camada de permissão por agente (ACL + limitação de taxa + revogação)	✅
Memória hierárquica (camadas quente / morna / fria + política de esquecimento)	✅
Linha do tempo de memória episódica (ferramentas `query_timeline`, `record_event`)	✅
Ferramentas de controle de memória (`pin_memory`, `forget_memory`)	✅
Cache LRU de embeddings (`CachedEmbeddingProvider`)	✅
Endpoint de saúde (`GET /health` em :8766)	✅
Embeddings de imagem CLIP reais (`memorymesh[multimodal]`)	✅
Transcrição de áudio Whisper real (`memorymesh[multimodal]`)	✅
Grafo de conhecimento — co-ocorrência de entidades (ferramenta `/graph`, `graph_memory`)	✅
Criptografia em repouso (Fernet AES-128, `memorymesh keygen`)	✅
API REST (11 endpoints em `/api`, docs OpenAPI em `/api/docs`)	✅
Extensão do VS Code (`extensions/vscode/`)	✅
Extensão do navegador — Manifest V3 (`extensions/browser/`)	✅
47 conectores de fontes de dados (Jira, Notion, GitHub, Slack, Spotify…)	✅
Suíte de testes unitários + integração	✅

Ferramentas MCP

Uma vez em execução, estas ferramentas estão disponíveis para qualquer cliente compatível com MCP:

Ferramenta	Descrição
`search_memory(query, top_k, mode, source)`	Busca híbrida sobre todo o conteúdo indexado. Retorna caminho, pré-visualização, pontuação, tipo de arquivo, fonte e `extended_preview` opcional para contexto mais amplo.
`list_sources()`	Lista todas as fontes configuradas com contagens de arquivos e status de indexação.
`get_document(path, max_bytes)`	Lê o conteúdo completo de um arquivo indexado (até 1 MB por padrão).
`index_now(path)`	Força a reindexação imediata de um arquivo ou diretório, ignorando o observador.
`ask_memory(question, top_k, model)`	RAG: recupera passagens relevantes e as envia para um modelo Ollama local para uma resposta fundamentada. Requer Ollama em execução local.
`pin_memory(chunk_id)`	Fixar um chunk na camada quente — nunca rebaixado, nunca com pontuação decaída.
`forget_memory(chunk_id)`	Suprimir um chunk dos resultados de busca futuros sem excluir o arquivo de origem.
`query_timeline(since_days, event_type, limit)`	Consultar o log de eventos episódicos: o que foi recuperado / indexado nos últimos N dias?
`sync_source(source_type, dry_run)`	Puxar e indexar documentos de um conector externo configurado (Jira, Notion, GitHub…).
`get_entity(name, entity_type)`	Procurar uma entidade nomeada (pessoa, projeto, conceito) e seus IDs de chunk associados.
`related_documents(path, top_k, exclude_self)`	Encontrar documentos semanticamente semelhantes ao caminho de arquivo fornecido.
`search_by_date(since_days, until_days, source, limit)`	Buscar chunks indexados por intervalo de data de última modificação.
`forget_source(source, dry_run)`	Remover todos os dados indexados de uma fonte nomeada do índice.
`summarize_source(source, max_chunks)`	Gerar um resumo breve do conteúdo mais recente em uma fonte (requer Ollama).
`graph_memory(min_mentions, entity_type)`	Retornar o grafo de conhecimento de co-ocorrência de entidades como nós e arestas.

Todas as ferramentas são retrocompatíveis — novos campos são adicionados sem alterar assinaturas existentes.

Como o MemoryMesh se compara

Como o MemoryMesh se compara a projetos semelhantes:

Recurso	MemoryMesh	LangChain	LlamaIndex	PrivateGPT	AnythingLLM	MemGPT	Haystack
Nativo para MCP	✅	❌	❌	❌	❌	❌	❌
Busca híbrida (densa + BM25 + RRF)	✅	Parcial	Parcial	❌	❌	❌	✅
Observador em tempo real + deduplicação SHA-256	✅	❌	❌	❌	❌	❌	❌
Reconciliação pós-crash	✅	❌	❌	❌	❌	❌	❌
100% local, zero telemetria	✅	✅	✅	✅	✅	✅	✅
Multiplataforma (Win/Linux/Mac)	✅	✅	✅	Parcial	Parcial	✅	✅
Sem dependência de framework	✅	—	—	❌	❌	❌	—
Permissões por agente	✅	❌	❌	❌	❌	❌	❌

Nativo para MCP significa que foi construído para MCP desde o primeiro dia — não adicionado depois. As 15 ferramentas seguem versionamento aditivo — novos campos são adicionados sem remover os existentes.

Permissões por agente significa identidade por cliente, ACL por fonte e operação, limitação de taxa por token-bucket e revogação de token são incorporados ao núcleo — não adicionados como middleware.

Configuração

Tudo fica em config.yaml. Veja config.example.yaml para uma referência totalmente comentada. Destaques principais:

sources:
  - name: documents
    path: ~/Documents
    recursive: true
    extensions: [.txt, .md, .pdf, .docx]

  - name: projects
    path: ~/Projects
    recursive: true
    extensions: [.py, .js, .ts, .go, .rs, .md]

  - name: obsidian
    path: ~/obsidian-vault
    source_type: obsidian     # activates wikilink + frontmatter parser

  - name: emails
    path: ~/Mail
    source_type: email        # parses .mbox files

embeddings:
  model: all-MiniLM-L6-v2    # swap to paraphrase-multilingual-MiniLM-L12-v2 for PT/EN

search:
  default_top_k: 10
  hybrid:
    enabled: true
  reranker:
    enabled: true             # cross-encoder reranker (recommended)
    model: BAAI/bge-reranker-v2-m3
  query_expansion:
    enabled: true
    n_lexical_variants: 1

# Optional: local LLM for ask_memory tool + HyDE query expansion
ollama:
  enabled: false              # set true after: ollama pull llama3
  model: llama3

server:
  transport: stdio            # stdio | streamable-http

Lista de ignorados global protege caminhos sensíveis por padrão: .env, *.key, id_rsa*, secrets/, .ssh/, .aws/, .git/, node_modules/.

Benchmarks

Os resultados de benchmark serão publicados aqui. Os scripts já estão em benchmarks/ e podem ser executados localmente — contribuições com números reproduzíveis são bem-vindas.

bench_indexing.py — throughput de indexação (chunks/s, MB/s) em um corpus sintético
bench_search_latency.py — latência de busca p50/p95/p99 nos modos híbrido/denso/esparso
bench_embedding_models.py — comparação de velocidade vs. qualidade entre três modelos de embedding

Privacidade e segurança

Três compromissos que não mudam entre versões:

Nenhum dado sai da sua máquina. Sem telemetria. Sem chamadas de API externas, a menos que você opte explicitamente — e mesmo assim, há um WARNING no log.
O listener HTTP vincula-se apenas a 127.0.0.1 por padrão. Expor a outras interfaces requer uma substituição explícita de configuração.
Os logs nunca contêm conteúdo de documentos ou consultas em texto claro. O log de auditoria registra hashes de consultas, não consultas.

A criptografia em repouso está disponível a partir da v0.8.0. Execute memorymesh keygen para gerar uma chave, depois habilite encryption.enabled: true em config.yaml. O armazenamento de metadados SQLite pode ser exportado como um backup criptografado com memorymesh backup.

Roteiro

Versão	Foco	Status
v0.1	Núcleo: busca híbrida, 4 ferramentas MCP, transporte stdio, indexador	✅ lançado
v0.2	CI/CD, Recuperador de Documento Pai, Docker, endurecimento de segurança	✅ lançado
v0.3	Re-ranker, expansão de consulta + HyDE, RAG (Ollama), 6 novos parsers, framework de avaliação	✅ lançado
v0.5	Permissões por agente (ACL/limite de taxa/revogação), camadas quente/morna/fria, linha do tempo episódica, ferramentas de controle de memória, cache de embeddings, endpoint de saúde, stubs CLIP/Whisper	✅ lançado
v0.8	CLIP+Whisper reais, Grafo de conhecimento, criptografia em repouso, API REST (11 endpoints), extensões VS Code + navegador, 47 conectores, 15 ferramentas MCP	✅ lançado
v1.0	Integração com Agent OS — camada de memória para sistemas multiagente	~6 meses
v2.0	Agentes de hardware — ESP32/Arduino consultando o hub via BLE/WiFi	~12 meses

Detalhes completos em ROADMAP.md.

Solução de problemas

UnicodeDecodeError em um arquivo de texto — O MemoryMesh tenta UTF-8, UTF-8 BOM, cp1252, latin-1 em ordem. Se um arquivo ainda falhar, ele é registrado e ignorado.
O observador não dispara em uma unidade de rede / montagem WSL — defina watcher.use_polling: true em config.yaml.
Tesseract não encontrado — instale-o em todo o sistema e garanta que esteja em PATH. Windows: instalador UB-Mannheim.
Incompatibilidade do modelo de embedding após alterar a configuração — execute memorymesh reindex --all. A CLI se recusa a iniciar se o ID do modelo armazenado no ChromaDB não corresponder à configuração.

Contribuindo

Contribuições são bem-vindas — relatórios de bugs, novos conectores, exemplos de integração e melhorias na documentação ajudam. Abra uma issue para discutir antes de enviar um PR grande.

Agradecimentos

Arquitetura informada pelo estudo de LlamaIndex, LangChain, PrivateGPT, AnythingLLM, MemGPT e Haystack — entendendo o que cada um faz bem e o que não faz. E a chroma-mcp e ao MCP Python SDK por mostrar como é o MCP nativo na prática.

MIT. Veja LICENSE.