memory-mcp-1file

🏠 🍎 🪟 🐧 - Um servidor de Memória autocontido com arquitetura de binário único (DB e modelos embutidos, sem dependências). Fornece memória semântica e baseada em grafos persistente para agentes de IA.

GitHub

Experimente este MCPPatrocinado

Documentação

🧠 Memory MCP Server

Um servidor de Model Context Protocol (MCP) de alto desempenho, 100% Rust, que fornece memória persistente, semântica e baseada em grafos para agentes de IA.

Funciona perfeitamente com:

Claude Desktop
Claude Code (CLI)
Gemini CLI
Cursor
OpenCode
Cline / Roo Code
Qualquer outro cliente compatível com MCP.

🏆 A Vantagem "Tudo-em-Um"

Diferente de outras soluções de memória que exigem uma stack complexa (Python + Vector DB + Graph DB), este projeto é um único executável autocontido.

✅ Sem Banco de Dados Externo (SurrealDB embutido)
✅ Sem Chaves de API, Sem Nuvem, Sem Python — Tudo roda 100% localmente via um runtime ONNX embutido. O modelo de embeddings está embutido no binário e roda na CPU. Nada sai da sua máquina.
✅ Zero Configuração (Basta executar um container Docker ou binário)

Ele combina:

Busca Vetorial (FastEmbed) para similaridade semântica.
Grafo de Conhecimento (PetGraph) para relacionamentos entre entidades.
Indexação de Código com grafo de símbolos (chamadas, extends, implements) para compreensão profunda do codebase.
Recuperação Híbrida (Reciprocal Rank Fusion) para melhores resultados.

🏗️ Arquitetura

graph TD
    User[AI Agent / IDE]
    
    subgraph "Memory MCP Server"
        MS[MCP Server]
        
        subgraph "Core Engines"
            ES[Embedding Service]
            GS[Graph Service]
            CS[Codebase Service]
        end
        
        MS -- "Store / Search" --> ES
        MS -- "Relate Entities" --> GS
        MS -- "Index" --> CS
        
        ES -- "Vectorize Text" --> SDB[(SurrealDB Embedded)]
        GS -- "Knowledge Graph" --> SDB
        CS -- "AST Chunks" --> SDB
    end

    User -- "MCP Protocol" --> MS

Clique aqui para a Documentação Detalhada da Arquitetura

🤖 Integração com Agentes (System Prompt)

A memória é inútil se o seu agente não a consulta. Para obter o efeito de "Memória de Longo Prazo", você deve instruir seu agente a seguir um protocolo rigoroso.

Fornecemos um Memory Protocol (AGENTS.md) testado em batalha que você pode adaptar.

🛡️ Fluxos de Trabalho Principais (Proteção de Contexto)

O protocolo implementa fluxos específicos para lidar com Compactação da Janela de Contexto e Reinícios de Sessão:

🚀 Início de Sessão: O agente deve buscar por TASK: in_progress imediatamente. Isso restaura o contexto completo do que estava acontecendo antes do término da última sessão ou da compactação do contexto.
⏳ Auto-Continuação: Um mecanismo de segurança onde o agente apresenta a tarefa encontrada ao usuário e aguarda (ou continua automaticamente), garantindo que não alucine uma nova tarefa.
🔄 Sincronização Tripla: Atualiza Memória, Lista de Tarefas e Arquivos simultaneamente. Se um falhar (ex.: contexto perdido), os outros servem como backup.
🧱 Sistema de Prefixos: Todas as memórias usam prefixos (TASK:, DECISION:, RESEARCH:) para que a busca semântica possa atingir com precisão o tipo certo de informação, reduzindo ruído.

Esses fluxos transformam o agente de um "chatbot sem estado" em um "worker com estado" que sobrevive a reinícios e limpeza de contexto.

Trecho Recomendado de System Prompt

Em vez de espalhar instruções por arquivos específicos de IDE (como .cursorrules), estabeleça AGENTS.md como a Fonte Única de Verdade.

Instrua seu agente (no system prompt base) a:

Ler AGENTS.md no início de cada sessão.
Seguir os protocolos definidos nele.

Aqui está um prompt de referência mínimo para iniciar esse comportamento:

# 🧠 Memory & Protocol
You have access to a persistent memory server and a protocol definition file.

1.  **Protocol Adherence**:
    - READ `AGENTS.md` immediately upon starting.
    - Strictly follow the "Session Startup" and "Sync" protocols defined there.

2.  **Context Restoration**:
    - Run `search_text("TASK: in_progress")` to restore context.
    - Do NOT ask the user "what should I do?" if a task is already in progress.

Por que isso importa?

Sem este protocolo, o agente perde o contexto após compactação ou reinícios de sessão. Com este protocolo, ele mantém o contexto completo da tarefa atual, garantindo que nenhuma etapa ou detalhe seja perdido, mesmo quando o histórico do chat é limpo.

🔌 Configuração do Cliente

Configuração Universal com Docker (Qualquer IDE/CLI)

Para usar este servidor MCP com qualquer cliente (Claude Code, OpenCode, Cline, etc.), use a seguinte estrutura de comando Docker.

Requisitos Principais:

Volume de Memória: -v mcp-data:/data (Persiste seu grafo, embeddings e pesos de modelo em cache)
Volume do Projeto: -v $(pwd):/project:ro (Permite que o servidor leia e indexe seu código)
Processo Init: --init (Garante que o servidor seja encerrado corretamente)

[!TIP] Um único volume persiste tudo: O único mount -v mcp-data:/data cobre tanto o banco de dados SurrealDB quanto o modelo de embeddings de ~1,2 GB (armazenado em /data/models/). Não há necessidade de um volume separado para /data/models — ele já é um subdiretório de /data e é preservado automaticamente. Sem um volume nomeado, o Docker cria um novo volume anônimo a cada docker run, fazendo com que o modelo seja baixado novamente (~1,2 GB) toda vez.

Configuração JSON (Claude Desktop, etc.)

Adicione isto ao seu arquivo de configuração (ex.: claude_desktop_config.json):

{
  "mcpServers": {
    "memory": {
      "command": "docker",
      "args": [
        "run",
        "--init",
        "-i",
        "--rm",
        "--memory=3g",
        "-v", "mcp-data:/data",
        "-v", "/absolute/path/to/your/project:/project:ro",
        "ghcr.io/pomazanbohdan/memory-mcp-1file:latest"
      ]
    }
  }
}

Nota: Substitua /absolute/path/to/your/project pelo caminho real que você deseja indexar. Em alguns ambientes (como extensões do Cursor ou VSCode), você pode usar variáveis como ${workspaceFolder}, mas caminhos absolutos são mais confiáveis para Docker.

Cursor (Instruções Específicas)

Vá para Cursor Settings > Features > MCP Servers.
Clique em + Add New MCP Server.
Type: stdio
Name: memory

Command:

docker run --init -i --rm --memory=3g -v mcp-data:/data -v "/Users/yourname/projects/current:/project:ro" ghcr.io/pomazanbohdan/memory-mcp-1file:latest

(Lembre-se de atualizar o caminho do projeto ao trocar de workspace se precisar de indexação de código)

OpenCode / CLI

docker run --init -i --rm --memory=3g \
  -v mcp-data:/data \
  -v $(pwd):/project:ro \
  ghcr.io/pomazanbohdan/memory-mcp-1file:latest

NPX / Bunx (Sem necessidade de Docker)

Você pode executar o servidor diretamente via npx ou bunx. O pacote npm baixa automaticamente o binário pré-compilado correto para sua plataforma.

Claude Desktop

Adicione em claude_desktop_config.json:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "memory-mcp-1file"]
    }
  }
}

Claude Code (CLI)

claude mcp add memory -- npx -y memory-mcp-1file

Cursor

Vá para Cursor Settings > Features > MCP Servers.
Clique em + Add New MCP Server.
Type: command
Name: memory
Command: npx -y memory-mcp-1file

Ou adicione em .cursor/mcp.json:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "memory-mcp-1file"]
    }
  }
}

Windsurf / VS Code

Adicione às suas configurações MCP:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "memory-mcp-1file"]
    }
  }
}

Bun

{
  "mcpServers": {
    "memory": {
      "command": "bunx",
      "args": ["memory-mcp-1file"]
    }
  }
}

Nota: Diferente do Docker, npx/bunx executa o binário localmente — ele já tem acesso ao seu sistema de arquivos, então não é necessário montar diretórios. Para personalizar o caminho de armazenamento de dados, passe --data-dir via args:
"args": ["-y", "memory-mcp-1file", "--", "--data-dir", "/path/to/data"]

Gemini CLI

Adicione ao seu ~/.gemini/settings.json:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "memory-mcp-1file"]
    }
  }
}

Ou com Docker:

{
  "mcpServers": {
    "memory": {
      "command": "docker",
      "args": [
        "run", "--init", "-i", "--rm", "--memory=3g",
        "-v", "mcp-data:/data",
        "-v", "${workspaceFolder}:/project:ro",
        "ghcr.io/pomazanbohdan/memory-mcp-1file:latest"
      ]
    }
  }
}

✨ Principais Recursos

Memória Semântica: Armazena texto com embeddings vetoriais (qwen3 por padrão) para recuperação baseada em "vibe".
Memória em Grafo: Rastreia entidades (User, Project, Tech) e suas relações (uses, likes). Suporta travessia baseada em PageRank.
Inteligência de Código: Indexa diretórios locais de projetos (chunking baseado em AST) para Rust, Python, TypeScript, JavaScript, Go, Java e Dart/Flutter. Rastreia relacionamentos de chamadas, imports, extends, implements e mixin entre símbolos.
Validade Temporal: Memórias podem ter datas de valid_from e valid_until.
Backend SurrealDB: Banco de dados rápido, embutido e de arquivo único.

🛠️ Ferramentas Disponíveis

O servidor expõe 18 ferramentas ao modelo de IA, organizadas em categorias lógicas.

🧠 Gerenciamento Principal de Memória

Ferramenta	Descrição
`store_memory`	Armazena uma nova memória com conteúdo e metadados opcionais.
`update_memory`	Atualiza campos de memória.
`delete_memory`	Exclui memória por ID.
`list_memories`	Lista memórias (mais recentes primeiro).
`get_memory`	Obtém memória completa por ID.
`invalidate`	Exclusão suave de memória, com opção de vincular substituição.
`get_valid`	Obtém memórias válidas. `timestamp` opcional (ISO 8601) para consulta em ponto específico no tempo.

🔎 Busca e Recuperação

Ferramenta	Descrição
`recall`	Busca híbrida (Vetorial + Palavras-chave + Grafo via RRF). Padrão para memórias.
`search_memory`	Busca memórias. `mode`: `vector` (padrão) ou `bm25`.

🕸️ Grafo de Conhecimento

Ferramenta	Descrição
`knowledge_graph`	Operações unificadas de KG. `action`: `create_entity` \| `create_relation` \| `get_related` \| `detect_communities`.

💻 Inteligência de Codebase

Ferramenta	Descrição
`index_project`	Indexa diretório do codebase para busca de código.
`delete_project`	Exclui projeto indexado.
`recall_code`	Recuperação de código. `mode`: `vector` ou `hybrid` (padrão). Híbrido usa fusão vetorial+BM25+grafo.
`search_symbols`	Busca símbolos de código por nome.
`symbol_graph`	Navega pelo grafo de símbolos. `action`: `callers` \| `callees` \| `related`.
`project_info`	Informações do projeto. `action`: `list` \| `status` \| `stats`.

⚙️ Sistema e Manutenção

Ferramenta	Descrição
`get_status`	Obtém status do sistema e progresso de inicialização.
`reset_all_memory`	PERIGO: Redefine todos os dados do banco (requer `confirm=true`).

⚙️ Configuração

Variáveis de ambiente ou argumentos de CLI:

Arg	Env	Padrão	Descrição
`--data-dir`	`DATA_DIR`	`./data`	Localização do banco de dados
`--model`	`EMBEDDING_MODEL`	`e5_multi`	Modelo de embeddings (`qwen3`, `gemma`, `bge_m3`, `nomic`, `e5_multi`, `e5_small`)
`--mrl-dim`	`MRL_DIM`	(nativo)	Dimensão de saída para modelos com suporte a MRL (ex.: 64, 128, 256, 512, 1024 para Qwen3). Padrão é a dimensão máxima nativa do modelo (1024 para Qwen3).
`--batch-size`	`BATCH_SIZE`	`8`	Tamanho máximo de lote para inferência de embeddings
`--cache-size`	`CACHE_SIZE`	`1000`	Capacidade do cache LRU para embeddings
`--timeout`	`TIMEOUT_MS`	`30000`	Timeout em milissegundos
`--idle-timeout`	`IDLE_TIMEOUT`	`0`	Timeout de inatividade em minutos. 0 = desabilitado
`--log-level`	`LOG_LEVEL`	`info`	Nível de verbosidade
(Nenhum)	`HF_TOKEN`	(Nenhum)	Token HuggingFace (necessário APENAS para modelos restritos como `gemma`)
(Nenhum)	`EMBEDDING_QUEUE_CAPACITY`	`256`	Tamanho máximo da fila de embeddings em segundo plano
(Nenhum)	`EMBEDDING_BATCH_SIZE`	`8`	Quantos arquivos processar em um chunk de embeddings
(Nenhum)	`INDEX_BATCH_SIZE`	`20`	Quantos arquivos processar em um chunk incremental
(Nenhum)	`INDEX_DEBOUNCE_MS`	`2000`	MS de espera antes de liberar eventos de indexação (debounce)
(Nenhum)	`MANIFEST_DIFF_INTERVAL_MINS`	`10`	Minutos entre verificações periódicas de arquivos ausentes

🧠 Modelos Disponíveis

Você pode trocar o modelo de embeddings usando o argumento --model ou a variável de ambiente EMBEDDING_MODEL.

Valor do Argumento	Repositório HuggingFace	Dimensões	Tamanho	Caso de Uso
`e5_multi`	`intfloat/multilingual-e5-base`	768	1,1 GB	Padrão. Modelo multilíngue, bom equilíbrio entre qualidade e desempenho.
`qwen3`	`Qwen/Qwen3-Embedding-0.6B`	1024 (MRL)	1,2 GB	Melhor modelo open-source de 2026, contexto de 32K, suporte a MRL.
`gemma`	`onnx-community/embeddinggemma-300m-ONNX`	768 (MRL)	~195 MB	Alternativa mais leve com suporte a MRL. (Requer acordo de licença proprietária)
`bge_m3`	`BAAI/bge-m3`	1024	2,3 GB	Recuperação híbrida multilíngue de última geração. Pesado.
`nomic`	`nomic-ai/nomic-embed-text-v1.5`	768	1,9 GB	Alta qualidade, contexto longo, compatível com BERT.
`e5_small`	`intfloat/multilingual-e5-small`	384	134 MB	Mais rápido, RAM mínima. Bom para desenvolvimento/testes.

📉 Matryoshka Representation Learning (MRL)

Modelos marcados com (MRL) suportam truncar dinamicamente o vetor de embeddings de saída para uma dimensão menor (ex.: 512, 256, 128) com perda mínima de precisão. Isso economiza armazenamento no banco de dados e acelera a busca vetorial. Use o argumento --mrl-dim para especificar o tamanho desejado. Se omitido, o padrão é a dimensão base nativa do modelo (por exemplo, 1024 para Qwen3).

Aviso: Depois que seu banco de dados for criado com uma dimensão específica, você não poderá alterá-la sem apagar o diretório de dados.

🔒 Modelos Restritos e Autenticação (Gemma)

Por padrão, o servidor usa e5_multi, que é totalmente open-source e faz download automaticamente sem qualquer autenticação.

No entanto, se você optar por usar Gemma (--model gemma), você deve autenticar porque é um "Modelo Restrito" com licença proprietária.

Para usar Gemma:

Acesse google/embeddinggemma-300m no Hugging Face.
Faça login e clique em "Agree to access repository".
Gere um Access Token em HF Tokens (acesso de leitura é suficiente).
Inicie o servidor com o token:

# Using environment variable
HF_TOKEN="hf_your_token_here" memory-mcp --model gemma

# Or via .env file (see .env.example)

[!WARNING] Alterando Modelos e Compatibilidade de Dados

Se você mudar para um modelo com dimensões diferentes (por exemplo, de e5_small para e5_multi), seu banco de dados existente será incompatível. Você deve excluir o diretório de dados (volume) e reindexar seus dados.

Alternar entre modelos com as mesmas dimensões (por exemplo, e5_multi <-> nomic) é teoricamente possível, mas não recomendado, pois os espaços semânticos diferem.

🔮 Roadmap Futuro (Pesquisa e Ideias)

Com base na análise de sistemas de memória avançados como Hindsight (veja a documentação deles para detalhes sobre esses mecanismos), estamos explorando estes recursos de "Arquitetura Cognitiva" para versões futuras:

1. Reflexão Meta-Cognitiva (Consolidação)

Problema: Memórias brutas acumulam ruído ao longo do tempo (por exemplo, 10 memórias separadas sobre corrigir o mesmo bug).
Solução: Implementar um processo em segundo plano reflect (ou ferramenta) que periodicamente escaneia memórias recentes para:
- Desduplicar entradas redundantes.
- Resolver conflitos (se duas memórias se contradizem, manter a mais recente ou sinalizar para revisão).
- Sintetizar fatos de baixo nível em "Insights" de alto nível (por exemplo, "Usuário prefere Rust a Python" derivado de 5 escolhas de código).

2. Decaimento Temporal e "Presença"

Problema: Memórias antigas às vezes podem sobrepor o contexto atual na busca semântica.
Solução: Integrar Decaimento Temporal no algoritmo de Fusão de Rank Recíproco (RRF).
- Dar um impulso calculado a memórias recentes para consultas que implicam "estado atual".
- Permitir que o agente priorize "memória de trabalho" sobre "arquivos históricos" dinamicamente.

3. Bancos de Memória com Namespaces

Problema: Executar um contêiner docker por projeto é pesado em recursos.
Solução: Adicionar suporte para escopo namespace ou project_id.
- Permite que uma única instância do servidor hospede "Bancos de Memória" isolados para diferentes projetos ou personas de agentes.
- Permite "Alternar Contexto" sem reiniciar o contêiner.

4. Pontuação de Confiança Epistêmica

Problema: O agente trata uma suposição da mesma forma que um fato verificado.
Solução: Adicionar uma pontuação de confidence (0.0 - 1.0) aos esquemas de memória.
- Permite armazenar hipóteses ("Acho que o bug está em auth.rs", confiança: 0.3).
- Ferramentas de recuperação podem filtrar memórias de baixa confiança ao responder perguntas factuais.

Licença

MIT