skillmem

skillmem

Habilidades autoaprimoráveis para Claude Code — seu agente aprende, recorda, reforça e esquece.

skillmem dá ao Claude Code uma camada local e persistente de habilidades e memória. Após cada tarefa não trivial, o agente pode registrar como foi feita como uma habilidade; antes da próxima tarefa, ele recorda as relevantes; habilidades que continuam se mostrando úteis ficam mais fortes, e habilidades que ninguém usa desaparecem — do jeito que a memória humana funciona.

• $0 por gravação e por leitura — sem chamadas de LLM, sem nuvem, sem chaves de API. SQLite puro no seu disco.
• Busca híbrida bilíngue, totalmente local — FTS5 BM25 + stemming Snowball (EN/RU) + um modelo de embeddings ONNX multilíngue. Uma consulta em russo encontra uma habilidade em inglês e vice-versa, tudo em CPU, offline.
• Modelo de força de Ebbinghaus — reinforce aumenta a força de uma habilidade, a decadência programada desvanece as não utilizadas, e varreduras de ciclo de vida movem habilidades mortas para um arquivo com backup (nunca excluídas).
• Histórico à prova de adulteração — cada edição é anexada a uma cadeia de hash SHA256; skillmem verify detecta qualquer adulteração posterior.
• Integração profunda com Claude Code — 6 hooks + 8 ferramentas MCP instaladas com um único comando.
• Multiplataforma — macOS (launchd), Windows (schtasks), Linux (timers de usuário systemd, fallback cron).
• Sem dependência de fornecedor — export-all despeja tudo em markdown simples com frontmatter YAML; reimportar o despejo produz os mesmos registros.

Por quê

Agentes repetem seus erros porque cada sessão começa do zero. Ferramentas de "memória" existentes armazenam fatos; skillmem armazena procedimentos — gatilho, passos, resultado, lições — e os classifica por quantas vezes realmente ajudaram. O caminho de gravação não custa nada, então o agente pode se dar ao luxo de aprender com cada tarefa.

Início rápido

macOS / Linux:

bash install.sh                 # installs python + uv if needed, venv, symlinks

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -File install.ps1

Ou a partir de um checkout:

uv venv && uv pip install -e '.[semantic]'
source .venv/bin/activate       # or prefix the commands below with `uv run`
skillmem init --claude-code     # wires MCP server + hooks into Claude Code
skillmem doctor                 # health check: DB, schema, semantic status

init --claude-code registra o servidor MCP em ~/.claude.json e os hooks em ~/.claude/settings.json (idempotente, com backups). Use --hooks minimal apenas para o hook Stop→migrate, ou --hooks none apenas para MCP.

Plugin Claude Code e MCP Registry (em breve)

O repositório já contém um plugin Claude Code (.claude-plugin/ + hooks/hooks.json — servidor MCP e todos os hooks em uma única instalação) e um manifesto MCP Registry (server.json). Ambos entram no ar assim que o pacote skillmem for publicado no PyPI; até lá, use os instaladores acima. Quando estiverem no ar:

/plugin marketplace add liza-studio/skillmem
/plugin install skillmem@liza-studio

O plugin requer o pacote Python skillmem no PATH e substitui a fiação de skillmem init --claude-code — use um ou outro, não ambos (veja docs/PUBLISHING.md).

Claude Desktop (aplicativo de chat)

O servidor MCP também funciona no aplicativo de chat Claude Desktop — adicione em claude_desktop_config.json (Configurações → Desenvolvedor → Editar Config):

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

Você obtém todas as 8 ferramentas mem_* sob demanda (busca, aprendizado, recordação, reforço…). Os hooks automáticos (auto-recall em cada prompt, resumo da sessão) são um mecanismo do Claude Code e não são executados no aplicativo de chat.

Como funciona

 learn ──▶ recall ──▶ reinforce ──▶ decay
   │          │            │           │
   │          │            │           └─ daily job: unused skills lose strength;
   │          │            │              fully faded ones are archived (backed up)
   │          │            └─ strength +0.15 when a skill proves useful
   │          └─ hybrid BM25 + vector search, strength-weighted ranking
   └─ after a hard task: trigger / steps / outcome / lessons

1. learn — após uma tarefa que exigiu depuração real, o agente chama mem_learn com um slug, gatilho, passos, resultado e lições.
2. recall — antes da próxima tarefa, mem_recall (ou os hooks automáticos) traz as habilidades mais relevantes, fundindo sinais lexicais e semânticos via Fusão de Rank Recíproco.
3. reinforce — quando uma habilidade recordada ajudou, mem_reinforce aumenta sua força, então habilidades comprovadas ficam mais bem classificadas na próxima vez.
4. decay — uma execução programada de skillmem decay aplica o esquecimento estilo Ebbinghaus; habilidades intocadas por meses migram para stale, e depois para um estado archived (excluídas do recall, restauráveis com um comando, com snapshot para JSONL antes).

Ferramentas MCP

Ferramenta	O que faz
mem_search	Busca híbrida de texto completo (FTS5 BM25 + recall vetorial opcional) em todas as memórias
mem_get	Busca uma memória por slug, com histórico e wikilinks
mem_list	Lista memórias por tipo/projeto, mais recentes primeiro
mem_write	Insere uma nova memória; recusa sobrescritas silenciosas e quase duplicatas
mem_update	Atualiza uma memória existente; a versão antiga é mantida no histórico com cadeia de hash
mem_learn	Registra uma habilidade pós-ação (gatilho / passos / resultado / lições)
mem_recall	Encontra habilidades relevantes para uma tarefa, ponderadas por força; auto-reforça
mem_reinforce	Aumenta explicitamente a força de uma habilidade após ela se mostrar útil

Hooks

Evento	Hook	O que injeta
SessionStart	mcp-guard	Avisa quando servidores MCP configurados estão ausentes em relação a uma linha de base
SessionStart	inject	Briefing compacto apenas com títulos das suas memórias user/feedback
SessionStart	session-history	Resumos das últimas 3 sessões neste projeto
UserPromptSubmit	verify-gate	Lembrete "Busque antes de afirmar" em prompts sensíveis ao tempo (gatilhos bilíngues EN/RU)
UserPromptSubmit	auto-recall	Feedback relevante + habilidades correspondidas com o prompt
PreToolUse	tool-recall	Habilidades/avisos correspondidos com o comando Bash ou caminho de arquivo editado
Stop	session-recap	Destila a sessão em uma nota markdown via claude -p (o idioma do resumo espelha a sessão)
Stop	migrate	Indexa novas notas de sessão no banco de dados

Todos os hooks são de melhor esforço: um banco de dados quebrado ou modelo ausente nunca bloqueia o Claude Code.

Destaques da CLI

skillmem learn skill-x -t "..." --trigger "..." --steps "..." --outcome success
skillmem recall "deploy the bot to prod"
skillmem skills                  # list skills with strength bars
skillmem decay --days 14         # manual decay + lifecycle sweep
skillmem search "hash chain" --kind feedback
skillmem verify --strict         # check the tamper-evidence chain
skillmem export-all ./vault      # markdown round-trip, no lock-in
skillmem import-vault ~/Obsidian/Notes
skillmem schedule install        # decay daily 04:15, export weekly Sun 04:30

Desinstalação

skillmem uninstall               # removes MCP entry, hooks, scheduled jobs; keeps the DB
skillmem uninstall --purge-db    # ...and deletes the database

As edições de configuração são feitas atomicamente com backups com carimbo de data/hora, e JSON corrompido nunca é sobrescrito.

Benchmarks

Qualidade de recuperação em LongMemEval (Wu et al., ICLR 2025), conjunto oracle completo, recuperação híbrida (FTS5 BM25 + stemming Snowball + embeddings paraphrase-multilingual-MiniLM-L12-v2, fusão RRF), k=5, apenas CPU:

Tipo de pergunta	n	hit@5	MRR
Geral	479	0.871	0.622
single-session-assistant	56	0.982	0.746
knowledge-update	72	0.944	0.676
single-session-user	64	0.938	0.719
multi-session	125	0.848	0.568
single-session-preference	30	0.833	0.465
temporal-reasoning	132	0.780	0.579

Mediana de 0,76 s por consulta em CPU de laptop, sem chamadas de LLM, sem rede. O pipeline é determinístico: execuções repetidas produzem números idênticos. Reproduza com python bench/longmemeval.py --sample 0 -k 5 (veja bench/README.md para o arquivo oracle e regras de relatório — não publicamos porcentagens simples sem declarar o modo de recuperação e o modelo de embeddings, e incentivamos outras ferramentas a fazer o mesmo).

Licença

Apache-2.0 — veja LICENSE.

---

Construído por Liza Studio.