mnemon-mcp

mnemon-mcp

Memória persistente em camadas para agentes de IA. Local-first. Zero-nuvem. Um único arquivo SQLite.

Página Inicial · npm · GitHub

Seu agente de IA esquece tudo após cada sessão. O Mnemon resolve isso.

Ele dá a qualquer cliente compatível com MCP — OpenClaw, Claude Code, Cursor, Windsurf, ou o seu próprio — uma memória estruturada de longo prazo apoiada por um único banco de dados SQLite na sua máquina. Sem chaves de API, sem nuvem, sem telemetria. Apenas npm install e seu agente se lembra.

Por que Memória em Camadas?

Armazenamentos simples de chave-valor tratam "o que aconteceu ontem" da mesma forma que "nunca faça commit sem testes". Isso está errado — diferentes tipos de conhecimento têm diferentes tempos de vida e padrões de acesso.

O Mnemon organiza memórias em quatro camadas:

Uma entrada de diário da última terça-feira e uma regra de codificação que nunca muda vivem em camadas diferentes — porque deveriam.

Qualidade da Recuperação

A recuperação é medida contra um conjunto dourado de 50 casos em um corpus bilíngue (RU/EN) real de 797 memórias, através do servidor MCP real — não uma reimplementação. Números atuais (metodologia e histórico):

O híbrido supera ambas as pernas individualmente, o que é todo o argumento para fundi-las: a busca lexical tem o melhor recall bruto, a busca vetorial tem o melhor ranking, e o RRF mantém ambos em vez de calculá-los como média.

O documento de avaliação também rastreia as falhas — desvio de pontuação sob crescimento do corpus, o bug de ponderação de campo BM25 que a avaliação capturou, os dois casos em que a fusão ainda perde para a busca lexical pura, e o que o conjunto dourado não cobre. Números que você não pode auditar são marketing; leia como estes são produzidos.

Arquitetura

flowchart LR
    C["MCP client<br/>Claude Code · Cursor · …"] -- "stdio / HTTP" --> T["10 tools · 4 resources · 3 prompts"]
    T --> R["retrieval pipeline<br/>FTS5 · vector · RRF fusion"]
    T --> M["memories + supersede chains"]
    I["KB import pipeline<br/>markdown → memories"] --> M
    M -- triggers --> F["FTS5 index (stemmed EN+RU)"]
    R --> F
    R --> V["sqlite-vec (optional, BYOK)"]

Um único arquivo SQLite armazena memórias, o índice FTS5 e o índice vetorial opcional. Escritas passam por transações que mantêm o invariante da cadeia de substituição; leituras executam o pipeline de recuperação em etapas descrito em Busca.

O quadro completo — limites de módulos, caminhos de escrita/leitura, invariantes e limitações conhecidas — está em docs/ARCHITECTURE.md. Decisões de design são registradas como ADRs: núcleo SQLite+FTS5, recuperação híbrida RRF, driver síncrono, modelo de memória em camadas.

Início Rápido

Instalação

npm install -g mnemon-mcp

Ou a partir do código-fonte:

git clone https://github.com/nikitacometa/mnemon-memory-mcp.git
cd mnemon-memory-mcp && npm install && npm run build

Configure Seu Cliente MCP

openclaw mcp register mnemon-mcp --command="mnemon-mcp"

{
  "mnemon-mcp": {
    "command": "mnemon-mcp"
  }
}

{
  "mcpServers": {
    "mnemon-mcp": {
      "command": "mnemon-mcp"
    }
  }
}

{
  "mcpServers": {
    "mnemon-mcp": {
      "command": "mnemon-mcp"
    }
  }
}

{
  "mnemon-mcp": {
    "command": "node",
    "args": ["/absolute/path/to/mnemon-mcp/dist/index.js"]
  }
}

Verificação

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | mnemon-mcp

Você deve ver 10 ferramentas na resposta. O banco de dados (~/.mnemon-mcp/memory.db) é criado automaticamente na primeira execução.

É isso. Seu agente agora tem memória persistente.

O Que Ele Pode Fazer

10 Ferramentas MCP

Recursos e Prompts MCP

Recursos — dados ao vivo que seu agente pode ler:

Prompts — fluxos de trabalho pré-construídos:

Busca

Quatro modos, todos com suporte a filtros de camada / entidade / escopo / data / confiança:

Modo FTS (padrão sem embeddings) — busca de texto completo tokenizada com ranking BM25. Consultas com múltiplas palavras usam AND; se houver poucos resultados, OR complementa com penalidade de pontuação. Relaxamento progressivo de AND tenta os 3 termos mais específicos antes de cair para OR completo.

Modo Híbrido (padrão quando embeddings estão configurados) — combina FTS5 + busca vetorial via Fusão de Rank Recíproco. Detecta entidades entre aspas em consultas (ex.: 'Essentialism') e executa sub-consultas ponderadas para recuperação de referências cruzadas.

Modo Vetorial — busca pura de similaridade por cosseno sobre embeddings.

Modo Exato — LIKE correspondência de substring para buscas precisas de frases.

Pontuações: bm25 × (0.3 + 0.7 × importance) × decay(layer) × recency

Impulso de recência: 1 / (1 + daysSince / 365) — recompensa suavemente memórias criadas recentemente sem penalizar as antigas.

Stemming

Stemmer Snowball aplicado tanto no momento da indexação quanto no momento da consulta para inglês e russo. Isso significa que "running" corresponde a "runs", e "книги" corresponde a "книга". Palavras de parada são filtradas das consultas para melhorar a precisão.

Versionamento de Fatos

O conhecimento evolui. O Mnemon não exclui fatos antigos — ele os encadeia:

v1: "Team uses React 17"  →  superseded_by: v2
v2: "Team uses React 19"  →  supersedes: v1 (active)

A busca retorna apenas a versão mais recente. memory_inspect com include_history: true revela a cadeia completa. memory_delete reativa o predecessor — nada é perdido.

Busca Vetorial (Opcional, BYOK)

Habilite a busca de similaridade semântica fornecendo sua própria API de embeddings:

# OpenAI
MNEMON_EMBEDDING_PROVIDER=openai MNEMON_EMBEDDING_API_KEY=sk-... mnemon-mcp

# Ollama (local, free)
MNEMON_EMBEDDING_PROVIDER=ollama mnemon-mcp

Isso desbloqueia dois modos de busca adicionais:

• mode: "vector" — busca pura de similaridade por cosseno
• mode: "hybrid" — FTS5 + vetor combinados via Fusão de Rank Recíproco

Requer sqlite-vec (instalado como dependência opcional). Novas memórias são incorporadas na adição; as existentes podem ser preenchidas retroativamente.

Importando uma Base de Conhecimento

Tem uma pasta de arquivos Markdown? Importe-os em massa:

cp config.example.json ~/.mnemon-mcp/config.json   # edit this first
npm run import:kb -- --kb-path /path/to/your/kb     # incremental (skips unchanged files)

A configuração mapeia padrões glob para camadas de memória:

{
  "owner_name": "your-name",
  "extra_stop_words": [],
  "mappings": [
    {
      "glob": "journal/*.md",
      "layer": "episodic",
      "entity_type": "user",
      "entity_name": "$owner",
      "importance": 0.6,
      "split": "h2"
    },
    {
      "glob": "people/*.md",
      "layer": "semantic",
      "entity_type": "person",
      "entity_name": "from-heading",
      "importance": 0.8,
      "split": "h3"
    }
  ]
}

Campos de Configuração

Transporte HTTP

Para configurações remotas ou com múltiplos clientes:

MNEMON_AUTH_TOKEN=your-secret MNEMON_HOST=0.0.0.0 MNEMON_PORT=3000 npm run start:http

Vincula a 127.0.0.1 por padrão. Vincular a qualquer outro host requer MNEMON_AUTH_TOKEN — o servidor se recusa a expor o armazenamento de memória à rede sem autenticação (substituível com MNEMON_ALLOW_INSECURE_HTTP=1 em uma rede confiável). Limitação de taxa (100 req/min/IP por padrão), CORS opcional, limite de corpo de 1MB, autenticação segura contra timing, desligamento gracioso em SIGTERM.

Referência de Configuração

Referência de Ferramentas

Como se Compara

Análise competitiva estendida com fontes: docs/COMPETITORS.md.

Desenvolvimento

npm run dev        # run via tsx (no build step)
npm run build      # TypeScript → dist/
npm run lint       # eslint (flat config)
npm test           # vitest — unit + integration + MCP dispatch + HTTP transport + hybrid RRF
npm run bench      # performance benchmarks
npm run db:backup  # backup database

O CI executa build + lint + testes no Node 20 e 22, depois faz smoke-tests do servidor compilado via JSON-RPC real (tools/list deve corresponder ao conjunto exato de ferramentas).

Stack: TypeScript 5.9 (modo estrito), better-sqlite3, @modelcontextprotocol/sdk, stemmer Snowball, Zod, vitest.

Consulte CONTRIBUTING.md para diretrizes de código.

Princípios de Design

• Isolado por padrão — zero telemetria, sempre. Fora da caixa, nada sai da máquina; o único componente que fala com a rede é o embedder opcional, e apenas com o provedor que você configurar (incluindo um Ollama local).
• Arquivo único — um banco de dados SQLite, zero operações, backup instantâneo via cópia de arquivo.
• Busca determinística — FTS5, não embeddings, é o padrão. Interpretável, reproduzível, sem necessidade de GPU.
• Estruturado em vez de plano — camadas codificam padrões de acesso; cadeias de substituição codificam tempo.
• Mínimo — 4 dependências de produção. Funciona em qualquer lugar onde o Node roda.
• Medido, não presumido — mudanças na recuperação são avaliadas contra um conjunto dourado, regressões incluídas.

Licença

MIT