claude-memory-fts

claude-memory-fts

Servidor MCP de memória de longo prazo para Claude Code. Armazena fatos em um banco de dados SQLite local com busca híbrida (FTS5 + similaridade vetorial semântica) e injeção automática de contexto.

Recursos

• Busca híbrida — busca por palavras-chave FTS5 + similaridade vetorial semântica, mescladas via Reciprocal Rank Fusion (RRF)
• Compreensão semântica — encontre memórias por significado, não apenas por palavras-chave (alimentado por embeddings all-MiniLM-L6-v2)
• Injeção automática de contexto — as 30 memórias mais importantes injetadas em cada prompt via hook
• Classificação por importância — fatos classificados por frequência de acesso, decaimento de recência e peso da categoria
• Rastreamento de acesso — rastreia com que frequência cada memória é acessada
• Upsert — atualiza automaticamente fatos existentes em vez de duplicá-los
• Categorizado — organize por tipo: preferência, decisão, técnico, projeto, fluxo de trabalho, pessoal, geral
• Recursos MCP — expõe o recurso memory://context para contexto de sessão
• Zero configuração — funciona imediatamente, armazena dados em ~/.claude/memory.db

Instalação

# Add to Claude Code
claude mcp add memory -- npx claude-memory-fts

# Auto-configure context injection hook (recommended)
npx claude-memory-fts --setup-hook

O comando --setup-hook automaticamente:

1. Cria ~/.claude/scripts/memory-context.sh
2. Adiciona um hook UserPromptSubmit a ~/.claude/settings.json
3. As 30 principais memórias são injetadas em cada prompt automaticamente

Comandos CLI

Comando	Descrição
npx claude-memory-fts	Inicia o servidor MCP (usado pelo Claude Code)
npx claude-memory-fts --context	Exibe os 30 principais fatos (usado pelo script de hook)
npx claude-memory-fts --setup-hook	Configura automaticamente o hook de injeção de contexto

Configuração

Variável de Ambiente	Padrão	Descrição
MEMORY_DB_PATH	~/.claude/memory.db	Caminho para o arquivo do banco de dados SQLite

Exemplo com caminho personalizado:

claude mcp add memory -e MEMORY_DB_PATH=/path/to/my/memory.db -- npx claude-memory-fts

Ferramentas

memory_save

Salva um fato na memória de longo prazo.

Parâmetro	Tipo	Obrigatório	Descrição
fact	string	sim	A informação a ser lembrada
category	string	não	Um de: preference, decision, personal, technical, project, workflow, general

memory_search

Busca híbrida: executa FTS5 e busca semântica em paralelo, mescla resultados com RRF. Recorre a LIKE para correspondências parciais.

Parâmetro	Tipo	Obrigatório	Descrição
keyword	string	sim	Palavra-chave ou frase de busca
limit	number	não	Máximo de resultados (padrão: 10)

memory_update

Atualiza o conteúdo ou a categoria de uma memória por ID.

Parâmetro	Tipo	Obrigatório	Descrição
id	number	sim	ID da memória
fact	string	não	Novo conteúdo (omitir para manter o atual)
category	string	não	Nova categoria (omitir para manter a atual)

memory_list

Lista todas as memórias salvas agrupadas por categoria.

Parâmetro	Tipo	Obrigatório	Descrição
category	string	não	Filtrar por categoria
limit	number	não	Máximo de resultados (padrão: 50)

memory_delete

Exclui uma memória por ID.

Parâmetro	Tipo	Obrigatório	Descrição
id	number	sim	ID da memória

Recursos

memory://context

Recurso MCP que expõe os 30 principais fatos classificados por pontuação de importância:

• Frequência de acesso — fatos acessados com frequência pontuam mais (limitado a 20 pontos)
• Recência — fatos atualizados recentemente pontuam mais (10 pontos, decai ao longo de 90 dias)
• Peso da categoria — preferência/decisão (3), fluxo de trabalho/técnico (2), projeto/pessoal (1), geral (0)

Como Funciona

Pipeline de Busca

1. FTS5 + BM25 e similaridade vetorial semântica são executados em paralelo
2. Os resultados são mesclados e deduplicados usando Reciprocal Rank Fusion (k=60)
3. Fatos que aparecem em ambas as listas são naturalmente impulsionados
4. Se ambos retornarem vazio, recorre à correspondência de substring LIKE
5. A contagem de acesso é rastreada em cada resultado de busca

Embeddings

• Modelo: all-MiniLM-L6-v2 (384 dimensões, ~23MB)
• Gerado localmente via @xenova/transformers — sem chamadas de API, nenhum dado sai da sua máquina
• Os embeddings são criados ao salvar e preenchidos retroativamente na inicialização do servidor
• Similaridade de cosseno com limite de 0.3 para filtrar ruído

Armazenamento

• SQLite com modo WAL para leituras/gravações concorrentes rápidas
• Tabela virtual FTS5 sincronizada via triggers para indexação de texto completo em tempo real
• Embeddings armazenados como colunas BLOB junto aos fatos

Desenvolvimento

git clone https://github.com/kurovu146/claude-memory-mcp.git
cd claude-memory-mcp
npm install
npm run build
npm test

Licença

MIT