mnemos: Uma Camada de Memória Persistente para Agentes de Codificação de IA (Go, Nativo MCP, Sem Python)

mnemos é uma camada de memória persistente para agentes de codificação de IA, construída como um único binário Go estático (~15 MB) sem Python, sem Docker e sem CGO. Ele usa SQLite puro em Go via modernc.org/sqlite e fornece recuperação híbrida (BM25 + vetores via RRF) com Ollama opcional para embeddings. É nativo do MCP, funcionando com Claude Code, Cursor, Windsurf e Codex CLI.

Verificador e Benchmarks

O autor construiu um verificador que executa o mesmo agente duas vezes (com e sem mnemos) sob o mesmo prompt e modelo, para medir o ganho concreto. Três modos de verificação acompanham o binário:

• mnemos verify retrieval – verifica se a memória correta aparece para sua consulta de gatilho
• mnemos verify behavior – executa Claude com mnemos ligado vs desligado, conta quantas vezes a transcrição corresponde a uma asserção
• mnemos verify capture – verifica se o agente registra correções fornecidas a ele durante uma tarefa

Resultados do lado de leitura (n=5 execuções pareadas no Claude Code):

• session_start_on_edit: 5/5 com, 0/5 sem (+100%)
• oss_first_for_protocol: 5/5 com, 0/5 sem (+100%)
• no_ai_attribution_in_commit: 5/5 vs 5/5 (sem ganho)
• no_cgo_proposal: 5/5 vs 5/5 (sem ganho)
• migration_locked_refused: 5/5 vs 5/5 (sem ganho)

Agregado +40%. A memória vence onde o conhecimento prévio do modelo está errado ou ausente (convenções contrárias, memória recursiva de ferramentas). Em práticas recomendadas amplamente conhecidas, não há ganho, mas também nenhuma degradação.

Captura no Lado de Escrita

Linha de base inicial: agentes registraram apenas 7% das correções fornecidas a eles durante uma tarefa. "Salve isso para sessões futuras" foi ignorado 3/3 vezes. Após duas rodadas de correções, a captura atingiu 53%.

• Rodada 1 (ajustes na descrição da ferramenta): Adicionados exemplos de frases de gatilho como "nós tentamos X" ou "daqui em diante use Y". Subiu de 7% para 13% (ruído).
• Rodada 2 (correção estrutural): Adicionado um hook UserPromptSubmit que faz correspondência de padrões com frases com formato de correção e emite um bloco diretivo no contexto do prompt. O agente ainda possui a chamada de ferramenta estruturada, mas o gatilho não pode ser ignorado. Subiu de 13% para 53%.

O padrão de falha restante: decisões arquiteturais enterradas em prompts de tarefas maiores ainda estão em 0/3 mesmo com a diretiva. O enquadramento mais forte da tarefa parece sobrepô-la.

Especificações Técnicas

• Binário Go estático único, ~15 MB
• SQLite puro em Go via modernc.org/sqlite
• Recuperação híbrida: BM25 + vetores via RRF, detecta automaticamente Ollama, funciona bem sem ele
• Nativo do MCP: funciona com Claude Code, Cursor, Windsurf, Codex CLI
• Armazenamento bitemporal, scanner de injeção de prompt na fronteira de escrita, promoção determinística de correção para habilidade (sem LLM no loop de consolidação)
• Prioridade local: nada sai da sua máquina a menos que você aponte explicitamente para OpenAI para embeddings

Ambiente do Verificador

O verificador está em verify/ no repositório. Os fixtures são em YAML e os cenários são fáceis de adicionar. O autor observa que n=5 é pequeno e está trabalhando em um benchmark tau-bench pass@k em seguida.

Repositório: https://github.com/polyxmedia/mnemos