/sibyl-save - Sincronização de Memória de Sessão + Extração de Skills (Sibyl Memory Plugin)
Parte da coleção de skills abertas da Sibyl Labs. Licenciada sob MIT. Construído por Sibyl Labs, LLC.
Uma skill companheira para o Sibyl Memory Plugin. Ela captura tudo o que aconteceu nesta sessão e injeta no banco de dados de memória local do plugin (~/.sibyl-memory/memory.db) através da própria interface do plugin, e então extrai padrões reutilizáveis em novos skills.
Ela não escreve arquivos de memória brutos. Toda a memória passa pelo plugin para que o tiering, a indexação full-text e o limite do nível gratuito sejam respeitados. Como o plugin expõe as mesmas ferramentas MCP em todos os harnesses que suporta (Claude Code, Codex e qualquer host MCP; Hermes via Python SDK), esta única skill é multi-harness por construção.
Requisitos
O Sibyl Memory Plugin, instalado e configurado:
pip install sibyl-memory-cli
sibyl init # ativação via navegador/carteira, escreve ~/.sibyl-memory/
sibyl setup claude-code # ou: codex | hermes (conecta a interface de memória ao seu harness)
Esta skill então se comunica com o plugin através de uma de duas superfícies:
- MCP (Claude Code, Codex, Cursor, qualquer host MCP): as 8 ferramentas
memory_*abaixo. - Python SDK (Hermes ou qualquer agente Python):
sibyl_memory_client.MemoryClient/sibyl_memory_hermes.SibylMemoryProvider.
A interface do plugin
| Propósito | Ferramenta MCP | SDK Python |
|---|---|---|
| Salvar um fato / entidade | memory_remember(category, name, body) | client.set_entity(category, name, body) |
| Recuperar uma entidade | memory_recall(category, name) | client.get_entity(category, name) |
| Listar entidades | memory_list(category, limit) | client.list_entities(category) |
| Pesquisa full-text | memory_search(query, limit, tiers) | client.search(query) |
| Definir um documento de estado | memory_set_state(key, body) | client.set_state(key, body) |
| Obter um documento de estado | memory_get_state(key) | client.get_state(key) |
| Gravar um evento de diário | memory_record_event(kind, body, category, name) | client.write_event(...) |
| Arquivar / esquecer | memory_forget(category, name, reason) | client.archive_entity(category, name, reason) |
Os exemplos abaixo usam os nomes MCP. No Hermes ou agente Python, use a coluna SDK.
Mapeamento de tiers
| Conteúdo da sessão | Tier | Chamada |
|---|---|---|
| Ponteiro de sessão / resumo / itens futuros | HOT (estado) | memory_set_state("session", ...) |
| Prioridades ranqueadas | HOT (estado) | memory_set_state("priorities", ...) |
| Entrada de log da sessão | COLD (diário) | memory_record_event("session_save", ...) |
| Projetos / pessoas / produtos | WARM (entidades) | memory_remember(category, name, body) |
| Itens fechados / mortos | ARCHIVE | memory_forget(category, name, reason) |
| Config desta skill + marcador delta | HOT (estado) | memory_set_state("sibyl_save:config" / "sibyl_save:last_save", ...) |
Modos
- run (padrão):
/sibyl-save,save session,sync memory. Injeta o contexto da sessão no plugin e oferece extração de skills. - setup:
/sibyl-save setup,/sibyl-save config. Interativo. Constrói ou edita a configuração (armazenada no plugin na chave de estadosibyl_save:config). Execute uma vez antes do primeiro uso. - preview (simulação):
/sibyl-save preview,/sibyl-save --dry-run. Executa a análise completa e relata todas as escritas planejadas. Não chama nada que mude o banco de dados. Não avança o marcador delta.
Modo: setup (configuração dinâmica)
Objetivo: escrever a configuração no plugin na chave de estado sibyl_save:config. Seja interativo e mínimo. Infira o que puder; pergunte apenas o que não puder.
- Harness. Detecte ou pergunte qual harness é (claude-code, codex, cursor, hermes, outro). Isso direciona onde a Fase 2 escreve os arquivos de skill.
- Saída de skills. Onde novos skills são escritos para este harness. Padrão para Claude Code:
.claude/skills/<nome>/SKILL.md. Para outros harnesses, confirme o local e formato do skill. Armazene comoskill_output: {dir, format}. - Prioridades. Chave de estado para a lista ranqueada (padrão
priorities) e um limite. Limite padrão 15. Teto máximo 30: nunca aceite um valor acima de 30. Uma lista com mais de 30 itens é um backlog, não um conjunto de prioridades. - Categorias de entidades. Quais categorias WARM você acompanha (padrão
project,person,product). O usuário adiciona ou remove. - Captura adicional. Opcionalmente, nomeie chaves de estado ou categorias de entidades extras que o save deve preencher a cada execução (um documento de estado de métricas, uma categoria de contatos). Este é o ponto de extensão.
- Padrão de simulação. Alterne
dry_run_default(padrão falso). - Escreva a configuração via
memory_set_state("sibyl_save:config", {...}). Não toque no marcador delta.
Formato da configuração: veja examples/sibyl-save-config.example.json. Reexecutar o setup edita a configuração no local.
Modo: run
Fase 1: Sincronização de Memória (no banco de dados do plugin)
Etapa 0 - Carregar configuração + delta
memory_get_state("sibyl_save:config"). Se ausente, mude para setup. memory_get_state("sibyl_save:last_save") para a âncora delta (o que mudou desde o último salvamento). Se dry_run_default for verdadeiro e nenhum modo foi fornecido, execute como preview.
Etapa 1 - Ler estado atual
memory_get_state("session")ememory_get_state(<chave de prioridades>)memory_list(category, limit)para categorias monitoradas, ememory_recall/memory_searchpara entidades tocadas nesta sessão- quaisquer chaves de estado ou categorias adicionais nomeadas na configuração
Etapa 1.5 - Verificação e reconciliação de prioridades
Leia o documento de estado de prioridades e reconcilie no local (reescreva com memory_set_state). Condições e a ação necessária:
- Item COMPLETED ainda listado: remova-o; registre o fechamento via
memory_record_event("priority_closed", {...}). - RANK_DRIFT / DUP_RANK (ranks não contíguos 1..N, ou um rank se repete): renumerar para 1..N.
- OVER_CAP (mais itens que o limite): mova os itens de menor prioridade para um documento de estado de backlog até ficar no limite ou abaixo.
- STALE_ITEM (>14 dias sem toque): apresente ao usuário.
- Entidade TERMINAL (a entidade referenciada está arquivada/morta): feche a prioridade.
- Ref de entidade QUEBRADA (aponta para entidade inexistente): corrija para uma
category/namereal.
Aplique o limite em toda escrita (nunca exceda 30).
Etapa 2 - Analisar a sessão
Revise a conversa desde a âncora delta (ou desde o início da sessão no primeiro salvamento). Extraia:
- Entidades tocadas - projetos, pessoas, produtos criados, lidos ou modificados
- Ações tomadas - coisas concretas que aconteceram, com identificadores
- Decisões tomadas - escolhas estratégicas e sua justificativa
- Itens futuros - ações para a próxima sessão, verbo primeiro ("implantar...", "acompanhar...", "verificar...")
- Avisos - riscos ativos, bloqueios, prazos, quase-erros
- Lições aprendidas - melhorias operacionais (alimentam a Fase 2)
- Capturas adicionais - dados para quaisquer chaves de estado / categorias extras na configuração
Etapa 3 - Injetar no banco de dados do plugin
No modo preview, não chame nada que mude. Relate as escritas planejadas (Etapa 4) e pare.
- Estado da sessão -
memory_set_state("session", { last_session, summary, forward, entities_touched, warnings }). Itens futuros são apenas referências de ação, nunca snapshots de saldo ou qualquer coisa que fique obsoleta. - Evento de diário -
memory_record_event("session_save", { evaluated, acted, forward, extra }). Um evento por salvamento (append-only por design). - Prioridades -
memory_set_state(<chave de prioridades>, { updated, cap, items }), limitado. Excedente para um documento de estado de backlog. - Entidades - para cada entidade alterada,
memory_remember(category, name, body). Novas entidades são apenas novas chamadasmemory_remember; o plugin as indexa, então não há registro separado para manter. - Fechados / mortos -
memory_forget(category, name, reason). - Capturas adicionais - aplique cada chave de estado / categoria extra configurada.
- Marcador delta -
memory_set_state("sibyl_save:last_save", { ts: <agora> }). Pule no preview.
Etapa 4 - Relatar
Resumo conciso: entidades escritas, documentos de estado atualizados, id do evento de diário, prioridades adicionadas/fechadas, capturas adicionais e itens futuros para a próxima sessão. No modo preview, rotule cada linha com "would" e confirme que nada foi escrito.
Fase 2: Extração de Skills (nativo do harness)
Skills são apresentados da mesma forma independentemente do harness: identificar, propor e então criar como um arquivo de skill nativo para o harness atual.
Etapa 5 - Identificar padrões reutilizáveis
Varra a sessão em busca de operações que atendam QUALQUER um destes: repetido (mais de uma vez nesta sessão), recorrente (provável novamente), multi-etapas (3+ etapas sequenciais), não óbvio (um workaround que vale a pena manter), propenso a erros (precisa de checklist). Para cada candidato, avalie nome (frase de verbo imperativo curta), gatilho, parâmetros, complexidade (quaisquer etapas perigosas), frequência.
Etapa 6 - Propor candidatos
Apresente cada um como uma linha única com nome, descrição e frequência estimada. Então pergunte: "Criar estes? Ou pular algum?"
Etapa 7 - Criar skills aprovados (nativo do harness)
Leia skill_output da configuração para saber onde e em que formato este harness espera skills. Padrões:
| Harness | Local do skill | Formato |
|---|---|---|
| claude-code | .claude/skills/<nome>/SKILL.md | YAML frontmatter (nome, descrição) + corpo Markdown |
| codex | ~/.codex/prompts/<nome>.md (confirmar no setup) | Prompt Markdown |
| cursor | .cursor/ comando/regra (confirmar no setup) | por convenção do Cursor |
| outro | de skill_output.dir | de skill_output.format |
Para cada skill aprovado, escreva o arquivo no local configurado com frases de gatilho, instruções passo a passo, descrições de parâmetros, verificações de segurança para qualquer etapa perigosa e um exemplo de invocação. Relate o caminho.
NÃO crie skills que: dupliquem um skill existente (verifique o local do skill primeiro), sejam muito específicos da sessão para recorrer, envolvam um único comando trivial ou exijam edição de arquivos que suas regras operacionais protegem (exponha-os, não auto-edite).
Regras (não negociáveis)
- Nunca armazene dados vivos (saldos, preços, contagens) como fatos duráveis. Capture referências, não snapshots.
- Itens futuros da sessão são orientados a ação e começam com verbo.
- Um evento de diário por salvamento (append-only; nunca reescreva o histórico).
- Prioridades são limitadas (padrão 15, nunca acima de 30). Excedente vai para um documento de estado de backlog.
- Entidades são endereçadas por
category+name; deixe o plugin ser o índice. Sem registro paralelo. - Todas as escritas de memória passam pela interface do plugin. Nunca escreva arquivos em
~/.sibyl-memory/nem abramemory.dbdiretamente: o cliente lida com bloqueio e o limite do nível gratuito. - Trate skills existentes como somente leitura. Crie novos em vez de editar no local, a menos que explicitamente solicitado.
Licença e proveniência
MIT (veja LICENSE). O comentário de marca d'água no topo de cada arquivo Markdown é atribuição e proveniência, não uma restrição de uso. Verifique uma cópia com node scripts/watermark.mjs verify. Detalhes em WATERMARK.md.