memory engine

Uma memória viva que decai, aprende e evolui com sua IA.

Documentação

🧠 Memory Engine MCP

Memória de longo prazo local-first e ciente de grafos para assistentes de IA.
SQLite + busca semântica + grafo de conhecimento + ferramentas MCP para agentes que precisam de continuidade.

Funciona com Claude Desktop · Claude Code · Cursor · Cline · Windsurf · OpenClaw · qualquer cliente MCP

Por que Memory Engine?

A maioria dos servidores de memória MCP são simples armazenamentos chave-valor ou wrappers de busca de texto puro.

Memory Engine é diferente: ele modela memória como átomos tipados conectados por ligações tipadas, e então recupera contexto com um pipeline de ranqueamento híbrido que combina:

busca de texto completo (SQLite FTS5)
similaridade semântica via embeddings locais do Ollama
confiança, recência e peso
expansão de grafo a partir de memórias relacionadas

O objetivo não é apenas armazenamento. O objetivo é um sistema de memória que possa recordar, conectar, decair, curar e aprender ao longo do tempo.

Destaques

Local-first — banco de dados SQLite, embeddings locais opcionais via Ollama, sem API em nuvem obrigatória.
Nativo MCP — expõe 35 ferramentas através do FastMCP.
Recuperação ciente de grafo — expande os principais resultados através de ligações bidirecionais para contexto mais rico.
Busca semântica — recuperação baseada em significado com nomic-embed-text.
Coexistência com Markdown — importa notas existentes de forma unidirecional sem substituir sua memória legível por humanos.
Memória de erros — lembra erros e correções, com promoção automática a preferências após falhas repetidas.
Curador cognitivo — passagem de manutenção não destrutiva para compactação, sugestões de ligações, detecção de duplicatas e classificação de átomos isolados.
Observador de sessões — ingestão canônica de SQLite do OpenClaw (schema 17), resumos cientes de reset e fallback legado JSONL.
Backup e restauração — snapshots completos de SQLite, exportação/importação JSON, restaurações verificadas com backups de segurança automáticos.
Autenticação e endurecimento — token de API opcional, bind seguro, validação de entrada, limitação de taxa.
Suíte de testes — 144 testes cobrindo CRUD, ranqueamento, migrações, autenticação, backup, concorrência e ingestão de transcrições.
Benchmark — suíte de qualidade de recuperação via CLI com Precision@K, MRR, percentis de latência.

Arquitetura

AI assistant / MCP client
        │
        ▼
FastMCP server — 35 tools
        │
        ▼
Memory engine — hybrid ranking, graph recall, decay, learning
        │
        ├── SQLite — atoms, bonds, FTS5, JSON metadata, versions
        ├── Ollama — optional local embeddings
        ├── Curator — conservative maintenance
        └── Session watcher — OpenClaw SQLite + JSONL fallback

Ferramentas MCP

Memória

Ferramenta	Propósito
`remember`	Criar ou atualizar um átomo
`recall`	Recuperação híbrida inteligente com expansão de grafo
`working_set`	Construir um pacote de contexto orientado a tarefas
`semantic_search`	Busca semântica pura
`get_atom`	Ler um átomo com ligações
`list_atoms`	Navegar átomos por domínio/tipo/status
`merge_atoms`	Mesclar átomos duplicados
`export_atom`	Exportar um átomo como markdown

Grafo de conhecimento

Ferramenta	Propósito
`link` / `unlink`	Criar ou remover ligações tipadas
`search_graph`	Percorrer o grafo a partir de um átomo
`suggest_bonds`	Sugerir ligações para um átomo
`suggest_bonds_all`	Sugerir ou criar ligações em lote

Aprendizado e manutenção

Ferramenta	Propósito
`curator_run`	Passagem de curadoria conservadora
`cognitive_status`	Métricas de saúde do grafo e da memória
`learning_run`	Detectar contradições, átomos fracos, candidatos a mesclagem, lacunas
`ask_pending` / `answer_human`	Esclarecimento com humano no circuito
`decay_run`	Executar ciclo de decaimento
`cleanup_sessions`	Remover átomos de sessão expirados
`cleanup_duplicates`	Remover átomos de sessão duplicados
`reindex_embeddings`	Reconstruir embeddings

Memória de erros e preferências

Ferramenta	Propósito
`error_check`	Verificar falhas passadas antes de executar uma tarefa
`error_log`	Registrar um erro e a correção
`error_list`	Navegar erros não resolvidos/resolvidos
`preference_search`	Buscar preferências estruturadas

Importação e introspecção

Ferramenta	Propósito
`import_markdown`	Importar notas markdown em átomos
`memory_summary`	Resumo em 3 níveis: global → domínio → detalhe
`stats`	Estatísticas do banco de dados
`version`	Versão do servidor
`recall_session`	Buscar uma sessão do OpenClaw
`session_summary`	Resumir uma sessão do OpenClaw
`memory_contradict`	Substituir um átomo antigo por um mais novo e contraditório
`list_contradictions`	Listar registros explícitos de contradição/substituição
`classify_memory_tier`	Inferir a classe de 3 níveis (episódica/semântica/procedural)
`memory_impact`	Análise de impacto: o que depende deste átomo

Backup, restauração e exportação

Ferramenta	Propósito
`backup_database`	Criar, listar, verificar ou limpar snapshots SQLite
`restore_database`	Restaurar a partir de um backup (com backup de segurança automático)
`export_all`	Exportar todos os dados de memória como JSON portátil
`import_data`	Importar de JSON (modo mesclagem ou substituição)

Interface Web (opcional)

Memory Engine inclui uma interface web opcional para exploração de grafos, inspeção de átomos, navegação de contradições e análise de impacto.

# In docker-compose.yml, add:
#   environment:
#     - MEM_UI_PORT=6000
#   expose:
#     - "6000"

Ou execute de forma independente:

python3 web_ui.py
# Open http://localhost:6000

Memory Engine Web UI — graph explorer
Interface Web: grafo interativo, detalhes de átomos, navegador de contradições, painel de estatísticas

Início rápido com Docker

Opção A — Usar a imagem pré-construída (recomendado)

# docker-compose.yml
services:
  memory-engine:
    image: ghcr.io/simoneb79/memory-engine-mcp:1.9.0
    ports:
      - "8085:8085"
    volumes:
      - memory-data:/data
    restart: unless-stopped

volumes:
  memory-data:

docker compose up -d

Fixar a versão. Use uma tag explícita como :1.7.0 em produção. Evite :latest — ela pode mudar sem aviso.

Opção B — Compilar a partir do código-fonte

git clone https://github.com/SimoneB79/memory-engine-mcp.git
cd memory-engine-mcp
cp docker-compose.yml docker-compose.local.yml
# Edit volume paths in docker-compose.local.yml if needed
docker compose -f docker-compose.local.yml up -d --build

Endpoint padrão:

http://localhost:8085/sse

Exemplo de configuração de cliente MCP:

{
  "mcpServers": {
    "memory-engine": {
      "url": "http://localhost:8085/sse",
      "transport": "sse"
    }
  }
}

Consulte docs/INSTALL.md para exemplos com Docker, Python local, Claude Desktop, Cursor e OpenClaw.

Python local

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python server.py

Configuração

Arquivo de configuração principal: config.json

Variáveis de ambiente importantes:

Variável	Padrão	Propósito
`MEMORY_DB_PATH`	`/data/memory.db`	Caminho do banco de dados SQLite
`MARKDOWN_SOURCE`	`/workspace/memory`	Diretório Markdown para importação
`MEMORY_HOST`	`127.0.0.1`	Endereço de bind do servidor (padrão seguro)
`MEMORY_PORT`	`8085`	Porta SSE
`MEMORY_API_TOKEN`	(nenhum)	Token de API opcional para autenticação (ver Segurança)
`OPENCLAW_AGENT_DB`	(nenhum)	Banco de dados SQLite preferido do OpenClaw por agente (schema 17)
`OPENCLAW_SESSIONS_DIR`	`/sessions`	Fallback legado JSONL quando nenhum banco de agente está configurado
`SESSION_DIGEST_DIR`	`/data/session_digests`	Saída opcional de resumo de sessão

Para o mount SQLite, tratamento de WAL/SHM, filtragem e limite de segurança, consulte Ingestão de transcrições do OpenClaw.

A busca semântica requer Ollama acessível a partir do contêiner ou host. Padrão:

{
  "ollama": {
    "enabled": true,
    "host": "http://ollama:11434",
    "model": "nomic-embed-text"
  }
}

Se você não usa Ollama, defina ollama.enabled como false; a recuperação FTS ainda funciona.

Modelo de memória

Átomos possuem:

title
body
type: fact, decision, event, preference, log, procedure, note, etc.
domain: namespace de projeto ou tópico
confidence
weight
tags
TTL opcional

Ligações conectam átomos com tipos de relação:

is_a · part_of · depends_on · contradicts · refines · derived_from · detail_of · related_to

Exemplo de uso

remember(
    title="Use PostgreSQL for analytics",
    body="SQLite is kept for local memory, PostgreSQL is used for multi-user analytics.",
    type="decision",
    domain="project:analytics",
    confidence=0.9,
    tags=["database", "architecture"]
)

recall(query="what database did we choose for analytics?", limit=5)

working_set(
    query="continue the analytics backend work",
    domain="project:analytics",
    limit=8,
    graph_depth=1
)

Segurança

Por padrão, Memory Engine executa em modo aberto (sem autenticação) — seguro para stdio ou ambientes locais confiáveis.

Para habilitar autenticação por token de API:

// config.json
{
  "security": {
    "api_token": "your-secret-token",
    "allow_remote": false
  }
}

Ou via variável de ambiente:

MEMORY_API_TOKEN=your-secret-token

Quando a autenticação está habilitada:

Requisições MCP SSE devem incluir Authorization: Bearer <token>
Endpoints da API da Interface Web exigem ?token=<token> ou cabeçalho Bearer
O servidor faz bind em 127.0.0.1 a menos que allow_remote: true
Validação de entrada (limites de tamanho de título/corpo) e limitação de taxa estão sempre ativas

Consulte CHANGELOG.md para a lista completa de recursos de segurança.

Publicação e registros

Este repositório está preparado para descoberta MCP:

Nome no Registro MCP: io.github.simoneb79/memory-engine-mcp
Metadados do registro: server.json
Rótulo de verificação Docker/OCI: incluído em Dockerfile
Exemplo de configuração de cliente: mcp.json

Consulte docs/PUBLISHING.md para a lista de verificação de publicação.

Status do repositório

Repositório público no GitHub: https://github.com/SimoneB79/memory-engine-mcp
Listagem existente: https://mcpmarket.com/server/memory-engine
Licença: MIT

Licença

MIT — consulte LICENSE.

Feito com 🧠 por SimoneB79