Módulo 4.3 — Sinapsis engine

📝 Append-only por princípio

Sinapsis não edita nada. Toda observação é uma entry nova, com timestamp, autor, contexto. Editar = escrever uma nova entry com supersedes_id apontando pra anterior. Isso te dá histórico completo, audit grátis e zero risco de corromper estado por race condition entre sessões paralelas.

📌 Anatomia de uma entry

Cada arquivo em ~/.claude/sinapsis/observations/<DATE>.jsonl é uma linha JSON. Exemplo real de uma decisão registrada hoje:

{
  "id": "obs_01HXKQ7P3F4ZT8VN6M2RJW9D1A",
  "ts": "2026-05-18T20:46:11-03:00",
  "client": "cliente-alpha",
  "project": "rebranding-q2",
  "type": "decision",
  "actor": "operator",
  "tags": ["pricing", "tier-pro"],
  "text": "Manter tier Pro em R$ 297 até julho. Churn caiu 2.1pp pós-anúncio.",
  "supersedes_id": null,
  "source": "session:claude-code",
  "session_id": "ses_8f3a"
}

Se amanhã mudarmos pra R$ 327, escrevemos nova entry com supersedes_id: "obs_01HXKQ7P3F4ZT8VN6M2RJW9D1A". Histórico intacto.

✓ Fazer

✓Nova entry com supersedes_id na velha.
✓Marcar type claro: decision, fact, preference, artifact.
✓Sempre incluir client — multi-cliente exige.
✓Rotacionar por dia (1 .jsonl/dia) pra leitura barata.
✓IDs ULID — ordem temporal embutida.

✗ Evitar

✗Sobrescrever entry "pra arrumar typo" — perde rastro.
✗Deletar entry obsoleta — use type: "retracted".
✗Misturar clientes no mesmo arquivo sem campo client.
✗JSON malformado — quebra dream cycle silenciosamente.
✗Editar arquivo .jsonl à mão. Use SDK.

Formato

JSONL — 1 entry por linha.

Rotação

1 arquivo por dia.

ULID — ordem temporal.

Audit

Grátis — append-only é log.

🌙 Dream cycle (cron 3h da manhã)

Às 3h da manhã (launchd no macOS, crontab no Linux) o dream cycle consolida as observações das últimas 24h num único daily-summaries/<DATE>.md. É o "sono" do Sinapsis — quando ele transforma ruído em sinal.

Timeline do dream (5 passos)

Pega as observações

Lê todos os observations/*.jsonl das últimas 24h. Filtra entries com supersedes_id apontando pra elas (já obsoletas). Resultado: ~50-300 obs típicas por operador ativo.

Agrupa por cliente e projeto

Buckets: cliente-alpha/rebranding-q2, cliente-beta/landing, _global/preferences. Cada bucket vira uma seção do summary final.

Prompt LLM (Haiku, barato)

Pra cada bucket: "Resuma essas entries em 3-7 bullets factuais. Marque decisões com [D], fatos com [F], preferências com [P]. Cite obs_id de origem em cada bullet."

Parse e validação

Cada bullet validado contra schema mínimo (tipo, autor, ref a obs_id origem). Bullet sem ref vai pra _unsourced/ e dispara warning no próximo SessionStart.

Escreve daily-summary

Output em ~/.claude/sinapsis/daily-summaries/2026-05-18.md. SessionStart do dia seguinte lê o summary de ontem — continuidade real, sem você narrar nada de novo.

💡 Tip — SessionStart lê o daily de ontem

Quando você abre o Claude Code de manhã, o hook SessionStart injeta o daily-summaries/<ontem>.md no contexto. Você nunca começa do zero — o agente lembra das decisões de ontem sem você precisar narrar de novo. Essa é a continuidade.

Horário

03:00 local. Disco ocioso.

Modelo

Haiku — ~R$ 0,02/dia.

Duração

30-90s pra ~500 obs.

Output

1 .md por dia, por cliente.

🎓 Learnings consolidados

Daily summaries são cronológicos. Learnings são atemporais — regras que o agente extraiu de padrões repetidos. Moram em context/learnings.md e seguem o formato Rule + Why + How to apply.

📖 Exemplo real — context/learnings.md

# Learnings — cliente-alpha
_Última consolidação: 2026-05-18 (dream cycle)_

## L-001 — Pricing nunca muda sem A/B de 14 dias
- **Rule**: Não alterar tier/preço sem teste A/B mínimo de 14 dias.
- **Why**: 3 mudanças anteriores (out/24, jan/25, mar/25) sem teste
  causaram churn médio +4.2pp nos 30 dias seguintes.
- **How to apply**: Antes de aprovar mudança, criar brief
  `projects/briefs/pricing-test-<data>/` com hipótese e métrica.

## L-002 — Voice: nunca usar "solução" em copy de site
- **Rule**: Banir "solução" do copy. Trocar por "ferramenta",
  "atalho" ou nome específico do produto.
- **Why**: ICP é cético com jargão corporativo. CTR cai 18%
  em headlines com "solução" (medido em 6 LPs em 2025).
- **How to apply**: Skill `brand-audit` flagga uso. Reescrever
  antes de publicar.

## L-003 — Reuniões com diretoria: deck antes, fala depois
- **Rule**: Mandar deck 24h antes. Em reunião, só responder perguntas.
- **Why**: 4 reuniões em 2025 onde apresentei ao vivo viraram
  brainstorm e perderam decisão. Quando mandei antes, decidiu em 30min.
- **How to apply**: Skill `meeting-prep` exige flag `--async-first`.

Origem

Dream cycle promove daily-summary virando learning quando padrão se repete 3x+.

Escopo

Por cliente. _global/learnings.md pra regras universais do operador.

Uso

SessionStart injeta learnings do cliente ativo. Custom skill referencia por ID.

Conceito-chave

Learning > instruction. Tem razão, não só ordem.

Revisão

/evolve 1x/semana revalida com humano antes de gravar.

📊 Dashboard Sinapsis

O comando /dashboard-sinapsis gera um HTML estático local (~/.claude/sinapsis/dashboard.html) e abre no browser via open/xdg-open. Nada vai pra rede — tudo é leitura dos arquivos locais.

📊 Dados típicos no dashboard

~25.000 obs/cliente/ano — volume típico após dream limpar duplicatas e supersedidas em 1 cliente ativo de operador médio.
Última execução do dream — verde se < 30h, amarelo 30-48h, vermelho > 48h.
Custo mensal Haiku — soma das chamadas do dream cycle (geralmente R$ 0,60-1,80/mês por operador).
Top 10 tags — quais temas dominam suas obs (pricing, brand, infra, etc).
Entries sem cliente — orfãs. Deve ser sempre 0.
Learnings ativos — quantos por cliente, qual mais aplicado.

🛠️ Como funciona

1. Comando gera HTML com dados embedados.
2. Abre em browser via open (mac) ou xdg-open.
3. Atualiza ao re-executar — não é live.
4. Zero deps, zero rede, zero servidor.

📈 Pra que serve

Detectar dream que parou de rodar.
Ver se cliente novo está gerando obs.
Sanity check de custo antes de mês fechar.
Mostrar pro cliente "olha, sua memória existe".

⚙️ Comandos globais

4 comandos vivem em ~/.claude/commands/ — disponíveis em qualquer projeto. Cada um é um .md com frontmatter e instruções pro agente.

`/evolve`

Promove obs repetidas pra learning. Roda interativo: pergunta confirmação antes de escrever em learnings.md.

Use: 1x por semana, no /eod de sexta.

`/instinct-status`

Mostra quais learnings o agente está aplicando ativamente nesta sessão. Útil pra debugar "por que o agente decidiu X".

Use: quando agente sugerir algo estranho.

`/passive-status`

Reporta o que Sinapsis está observando passivamente (hooks ligados, último write, próximo dream).

Use: depois de mudar configuração.

`/system-status`

Health-check completo: cron ativo, disco disponível, daily de ontem existe, learnings coerentes.

Use: SessionStart automático em alguns setups.

🚨 Alerta — Dream desligado enche o disco

Se o cron do dream cycle parar (launchd corrompido, crontab apagado, máquina hibernada por dias), observations/ acumula sem consolidar. Em semanas vira GB de .jsonl que ninguém lê — e o SessionStart fica lento porque tenta carregar tudo.

Antídoto: /system-status no SessionStart com alerta vermelho se último dream > 48h. Reinstale o cron com bun run install-dream.

Localização

~/.claude/commands/

Escopo

Global — todo projeto.

Formato

.md com frontmatter.

Versionamento

vendor/ no repo iAmasters OS.

🔀 Sinapsis vs SQLite do intelecto

Pergunta frequente: "por que não usar SQLite com FTS?" Resposta: são camadas diferentes e se compõem. SQLite é working memory (alta frequência, schema rígido, dura a sessão). Sinapsis é long-term memory (baixa frequência, semântica livre, dura para sempre).

🧩 Comparativo direto

Eixo	SQLite (intelecto)	Sinapsis (memória)
Latência	< 1ms (índice em RAM)	10-100ms (read .md)
Evolução	Schema rígido. Migration dói.	Append-only. Tipo novo = só usar.
Custo	Quase zero. Disco apenas.	~R$ 0,02/dia (Haiku dream).
Complexidade	SQL + ORM + migrations.	jsonl + .md. Lê com cat.
Audit	Trigger + tabela history.	Grátis — append é log.
Uso típico	Cache de sessão, FTS rápido.	Continuidade entre sessões.

Compõem. No iAmasters OS o intelecto usa SQLite pra working memory dentro da sessão (cache de FTS, contagem de tokens, índice de skills). No final, hook Stop escreve as obs importantes em Sinapsis. Dia seguinte, SessionStart injeta o daily-summary — SQLite começa frio, mas com contexto fresco do Sinapsis.

Working memory

SQLite. Dura a sessão.

Long-term memory

Sinapsis. Dura para sempre.

Bridge

Hook Stop escreve em Sinapsis.

📝 Resumo do módulo

✓

Append-only por princípio — toda entry é nova, editar = supersedes_id.

✓

Dream cycle às 3h — pega obs, agrupa, prompt Haiku, parse, escreve daily.

✓

Learnings em context/learnings.md — formato Rule + Why + How to apply.

✓

Dashboard local — HTML estático, sem rede, métricas de saúde.

✓

4 comandos globais — /evolve, /instinct-status, /passive-status, /system-status.

✓

Compõe com SQLite — working memory vs long-term memory.

Próximo módulo:

4.4 — Install gate: estado JSON, fases bloqueantes, idempotência total

← Voltar para Trilha 4 Próximo Módulo →