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

🧠 Servidor MCP de Memória

Um servidor de Protocolo de Contexto de Modelo (MCP) de alta performance, 100% em 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
OpenAI Codex (CLI / IDE)
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 + Banco de Dados Vetorial + Banco de Dados de Grafos), 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 contêiner Docker ou binário)

Ele combina:

Busca Vetorial (FastEmbed) para similaridade semântica.
Grafo de Conhecimento (PetGraph) para relações entre entidades.
Indexação de Código com grafo de símbolos (chamadas, extensões, implementações) para compreensão profunda do código.
Recuperação Híbrida (Fusão de Classificação Recíproca) 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

Protocolo MCP & Transportes

O servidor usa rmcp 3.2 e suporta ambos os ciclos de vida do protocolo:

Requisições sem estado MCP 2026-07-28: clientes podem começar com server/discover; cada requisição carrega a versão do protocolo e os metadados do cliente em _meta. O processo não armazena sessão MCP, Mcp-Session-Id, ou currentProject mutável.
Compatibilidade MCP 2025-11-25: clientes que usam o ciclo de vida legado initialize/initialized continuam suportados.

Este binário expõe MCP via stdio. Execute um processo por workspace local e monte esse workspace em /project ao usar Docker. HTTP Streamable não está habilitado ou anunciado nesta versão, portanto não introduz gerenciamento de sessão HTTP ou superfície de autenticação de servidor compartilhado. A indexação de código recebe um caminho explícito via index_project; a busca de código pode ser restringida com project_id quando um processo contém múltiplos projetos indexados. A negociação de raízes não é usada.

🤖 Integração com Agentes (Prompt de Sistema)

A memória é inútil se 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 Protocolo de Memória (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 de 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 da última sessão terminar ou do contexto ser compactado.
⏳ Continuação Automática: 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 mirar com precisão o tipo certo de informação, reduzindo ruído.

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

Trecho Recomendado de Prompt de Sistema

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 prompt de sistema 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 nenhum passo 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)

[!DICA] Um 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 o modelo ser baixado novamente (~1,2 GB) toda vez.

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

Adicione isso 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 Configurações do Cursor > Recursos > Servidores MCP.
Clique em + Adicionar Novo Servidor MCP.
Tipo: stdio
Nome: memory

Comando:

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 Docker necessário)

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 a 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 Configurações do Cursor > Recursos > Servidores MCP.
Clique em + Adicionar Novo Servidor MCP.
Tipo: command
Nome: memory
Comando: npx -y memory-mcp-1file

Ou adicione a .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"]
    }
  }
}

OpenAI Codex CLI (escopo de projeto)

Este repositório inclui um .codex/config.toml de projeto confiável que inicia memory-mcp-1file@0.9.2 via STDIO local, armazena dados em .codex/data, e expõe uma lista de permissões de 16 ferramentas do projeto. As ferramentas destrutivas delete_memory, delete_project e reset_all_memory são intencionalmente excluídas da configuração do projeto. A indexação nativa do Codex é restrita ao repositório atual por MEMORY_MCP_ALLOWED_INDEX_ROOT.

A configuração do Codex com escopo de projeto é carregada somente após você confiar explicitamente no repositório. No Windows, verifique o pacote de forma independente primeiro:

npx -y memory-mcp-1file@0.9.2 -- --help

Depois execute codex a partir do repositório e verifique o servidor com:

/mcp

ou:

codex mcp list
codex mcp get memory

A configuração required = true torna uma falha de inicialização do Memory MCP visível em vez de executar silenciosamente o projeto sem seu fluxo de trabalho de memória. A lista de permissões de ferramentas controla quais ferramentas MCP o Codex carrega; não é um sandbox de processo. Confie no repositório e no pacote npm antes de habilitar esta configuração.

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"
      ]
    }
  }
}

✨ Recursos Principais

Memória Semântica: Armazena texto com embeddings vetoriais (granite por padrão) para recuperação "baseada em vibração".
Memória de 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 de projetos locais (fragmentação baseada em AST) para Rust, Python, TypeScript, JavaScript, Go, Java e Dart/Flutter. Rastreia relações de chamadas, imports, extensões, implementações e mixins 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 19 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, opcionalmente vinculando uma substituição.
`get_valid`	Obtém memórias válidas. `timestamp` opcional (ISO 8601) para consulta em ponto específico no tempo.

🔎 Busca & 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 Código

Ferramenta	Descrição
`index_project`	Indexa diretório do código 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 no grafo de símbolos. `action`: `callers` \| `callees` \| `related`.
`project_info`	Informações do projeto. `action`: `list` \| `status` \| `stats`.

⚙️ Sistema & 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`).
`how_to_use`	Mostra exemplos de uso de ferramentas e combinações de parâmetros.

⚙️ 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`	`granite`	Modelo de embeddings (`granite`, `e5_multi`, `qwen3`, `gemma`, `bge_m3`, `nomic`, `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). O padrão é a dimensão máxima nativa do modelo (384 para Granite, 1024 para Qwen3).
`--batch-size`	`BATCH_SIZE`	`8`	Tamanho máximo do lote para inferência de embeddings
`--cache-size`	`CACHE_SIZE`	`1000`	Capacidade do cache LRU para embeddings
`--timeout`	`TIMEOUT_MS`	`30000`	Tempo limite em milissegundos
`--idle-timeout`	`IDLE_TIMEOUT`	`0`	Tempo limite de inatividade em minutos. 0 = desativado
`--log-level`	`LOG_LEVEL`	`info`	Nível de detalhamento
(Nenhum)	`HF_TOKEN`	(Nenhum)	Token do HuggingFace (OBRIGATÓ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 lote de embeddings
(Nenhum)	`INDEX_BATCH_SIZE`	`20`	Quantos arquivos processar em um lote incremental
(Nenhum)	`INDEX_DEBOUNCE_MS`	`2000`	MS de espera antes de liberar eventos de índice (debounce)
(Nenhum)	`MANIFEST_DIFF_INTERVAL_MINS`	`10`	Minutos entre verificações periódicas de arquivos ausentes

🧠 Modelos Disponíveis

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

Quando nenhuma das opções é fornecida, o binário usa Granite. A precedência de configuração é: argumento explícito --model, depois EMBEDDING_MODEL, e então o padrão Granite embutido.

Valor do Argumento	Repositório HuggingFace	Dimensões	Tamanho	Caso de Uso
`granite`	`ibm-granite/granite-embedding-97m-multilingual-r2`	384	~195 MB	Padrão. Recuperação multilíngue e de código com ModernBERT e pooling CLS.
`e5_multi`	`intfloat/multilingual-e5-base`	768	1.1 GB	Modelo multilíngue legado, 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 com 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.

granite produz embeddings CLS nativos de 384 dimensões, normalizados por L2. O caminho atual de CPU Candle limita as entradas a 512 tokens para limitar o custo de memória da atenção quadrática; o modelo em si suporta até 32K tokens.

📉 Aprendizado de Representação Matryoshka (MRL)

Modelos marcados com (MRL) suportam truncar dinamicamente o vetor de embedding 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 (ex.: 1024 para Qwen3).

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

🔒 Modelos Restritos e Autenticação (Gemma)

Por padrão, o servidor usa Granite, um modelo Apache 2.0 que baixa 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:

Vá para google/embeddinggemma-300m no Hugging Face.
Faça login e clique em "Concordar em acessar o repositório".
Gere um Token de Acesso 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)

[!AVISO] Alterando Modelos e Compatibilidade de Dados

Instalações novas usam granite (384 dimensões) por padrão. Diretórios de dados existentes criados com e5_multi (768 dimensões) permanecem utilizáveis apenas ao iniciar explicitamente com --model e5_multi.

Alternar para um modelo com dimensões diferentes requer um novo diretório de dados (ou volume apagado) e uma reindexação completa.

Mesmo alternar entre modelos com as mesmas dimensões (ex.: e5_multi <-> nomic) não é recomendado porque seus espaços semânticos diferem.

🔮 Roteiro 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 futuras versões:

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

Problema: Memórias brutas acumulam ruído ao longo do tempo (ex.: 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 (ex.: "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 sobrepujar 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

Limite atual: Índices de código já suportam filtragem explícita por project_id, enquanto registros de memória permanecem em todo o processo.
Trabalho futuro: Estender o escopo de namespace/projeto para operações de memória e grafo, para que um servidor compartilhado possa isolar múltiplos espaços de trabalho de agentes.

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