Como o Memora Dá aos Assistentes Claude Code Memória de Longo Prazo e um Grafo de Conhecimento

Qualquer pessoa que já tentou atribuir tarefas longas a agentes como Claude Code ou Codex CLI conhece essa sensação. Ontem você passou meio dia rastreando um bug de autorização não óbvio, discutiu restrições arquiteturais e esboçou um plano de refatoração. Hoje você abre uma nova sessão e o modelo sugere aquela exata solução que você rejeitou ontem.

Arquivos de memória de texto simples como MEMORY.md se tornam descontrolados dentro de algumas semanas. O contexto fica obstruído com duplicatas, fatos contraditórios e planos desatualizados. O projeto Memora resolve isso através do Model Context Protocol (MCP), transformando notas dispersas de agentes em um grafo de conhecimento estruturado.

O Que Está Por Trás do Capô e Por Que Isso Importa

O Memora funciona como um servidor MCP em Python, armazenando dados em um banco de dados SQLite local ou armazenamento em nuvem (Cloudflare D1, S3, R2). O ponto-chave aqui não é apenas salvar strings, mas como o sistema processa novos fatos.

Quando um agente conclui uma tarefa e deseja salvar o contexto, ele chama o comando de absorção de dados (absorb). Um modelo de linguagem embutido compara o novo fato com registros existentes e o classifica: duplicata, atualização, contradição, conexão ou conhecimento fundamentalmente novo.

Se a informação atualiza uma entrada antiga, o Memora constrói uma cadeia de versões. O registro antigo não é excluído sem deixar vestígios—ele é marcado como desatualizado, preservando o histórico de alterações. Durante pesquisas normais, o agente vê apenas o snapshot atual, mas pode recuperar a retrospectiva completa se necessário.

O Que Diferencia Este Projeto na Prática

O repositório reúne várias soluções de engenharia que a memória RAG padrão para agentes carece severamente.

1. Deduplicação Inteligente e Resumos Temáticos

Em vez de alimentar o modelo com dezenas de pedaços de texto semelhantes, a ferramenta consolida fatos por tópico. O método memory_digest(topic) reúne todas as memórias relevantes, TODOs abertos, bugs descobertos e suas conexões em uma única chamada.

Duplicatas são rastreadas automaticamente:

# Поиск похожих записей через векторную близость и LLM-анализ
memory_find_duplicates(min_similarity=0.7, max_similarity=0.95, limit=10, use_llm=True)

# Объединение записей с нужной стратегией
memory_merge(source_id=123, target_id=456, merge_strategy="append")

Ao comparar, o LLM dá um veredito claro: duplicata, pensamento similar ou coisas diferentes—complementando a avaliação com raciocínio e uma recomendação.

2. Documentos Estruturados e Fragmentos Atômicos

Frequentemente um agente precisa lembrar não uma frase curta, mas um relatório de pesquisa inteiro ou uma decisão arquitetural (ADR). Se você salvar markdown como um único pedaço, a busca semântica granular nele terá desempenho ruim.

O Memora faz parsing de markdown em uma árvore de fragmentos:

• tabelas se tornam afirmações separadas;
• listas numeradas se tornam itens de plano;
• listas de referência se tornam referências;
• seções de risco são parseadas como riscos.

Cada fragmento está disponível para busca vetorial independentemente, e o documento original pode ser recuperado por completo a qualquer momento. Fragmentos são protegidos contra exclusão ou mesclagem acidental por verificações do sistema.

3. Grafo Interativo e Painel Web

Além do servidor MCP, uma interface web local inicia na porta 8765. Você pode visualizar o grafo de conhecimento, filtrar conexões por tags, acompanhar linhas do tempo de ações e conversar com o banco de dados através de um chat RAG embutido.

O chat da interface web suporta chamadas de função. Você pode perguntar ao modelo diretamente do navegador: "Delete note #42" ou "Update requirements in task #10", e ele fará alterações no banco de dados.

Configuração e Armadilhas com Embeddings

Instale o pacote via pip:

pip install memora-mcp

Para embeddings locais sem chamar APIs externas, a opção [local] é útil:

pip install "memora-mcp[local]"

A conexão com o Claude Code é configurada no arquivo .mcp.json na raiz do projeto:

{
  "mcpServers": {
    "memora": {
      "command": "memora-server",
      "args": [],
      "env": {
        "MEMORA_DB_PATH": "~/.local/share/memora/memories.db",
        "MEMORA_ALLOW_ANY_TAG": "1",
        "MEMORA_GRAPH_PORT": "8765",
        "MEMORA_EMBEDDING_STRICT": "1"
      }
    }
  }
}

Os autores do projeto alertam honestamente sobre um erro comum de configuração. O Memora pode separar o provedor para LLM (ex., OpenRouter) e o provedor para representações vetoriais (ex., Cloudflare Workers AI ou OpenAI).

Se você usa o OpenRouter para raciocínio, lembre-se: ele não tem endpoint de embeddings. Se você cometer um erro na configuração e não definir o flag MEMORA_EMBEDDING_STRICT=1, o servidor volta silenciosamente para busca por palavras-chave TF-IDF primitiva. O banco de dados continuará respondendo, mas a qualidade da busca vetorial diminuirá de forma imperceptível. O modo estrito lançará um erro imediatamente se o endpoint de vetorização estiver indisponível.

Para usuários do Neovim, há um bônus interessante na forma de integração com o Telescope: o plugin memora.lua permite buscar memórias com um atalho de teclado diretamente enquanto edita código.

Para Quem Este Projeto É Indicado

O Memora é uma boa escolha para quem usa ativamente Claude Code, Codex CLI ou agentes personalizados baseados em MCP para projetos de longa duração. Ele aborda o principal ponto de dor do desenvolvimento agentic—a perda de contexto entre reinicializações de sessão.

Se você precisa de uma base de conhecimento que não fica poluída com duplicatas e visualiza claramente as conexões entre tarefas e decisões arquiteturais, definitivamente vale a pena experimentar a ferramenta. O código fonte está disponível sob a licença MIT no repositório agentic-box/.