Um binário só, arquivos markdown, um índice derivado

1. 1

   HookZero LLM

   A CLI do agente dispara um hook de ciclo de vida. É fire and forget com um orçamento de 200 ms: os hooks nativos guardam o evento num spool local e um helper destacado faz a entrega. O servidor responde 202, ou 429 quando está saturado.

2. 2

   SanitizaçãoZero LLM

   O router de /hook remove segredos e limita tamanhos. Este é o único caminho de texto não confiável até o store.

3. 3

   Writer únicoZero LLM

   O evento sanitizado entra numa fila só, drenada por uma thread só, que é dona da única conexão de escrita.

4. 4

   ObservaçõesZero LLM

   Os eventos caem no SQLite como uma trilha de auditoria operacional. É uma projeção limitada da sessão, nunca uma transcrição completa.

5. 5

   Fim da sessãoZero LLM

   Regras, sem modelo, transformam as observações em sessions/<id>.md e abrem uma linha de Handoff para o próximo agente, numa transação só.

6. 6

   ConsolidaçãoLLM opcional

   Com um provedor configurado, um LLM reescreve o resumo ou o desdobra em concepts/, decisions/, gotchas/ e procedures/. Roda a partir de uma fila com retry, fora da latência dos hooks.

7. 7

   Commit e indexaçãoZero LLM

   Cada escrita de página é atômica (tmp, rename, fsync), commitada no git e indexada na mesma transação SQLite que a linha dela.

8. 8

   Consulta e briefingZero LLM

   memory_query busca no índice. No próximo SessionStart, o hook pega o handoff aberto e um briefing estruturado para aquele diretório.

• Full-text

  SQLite FTS5 sobre títulos e corpos das páginas, com stopwords filtradas nas consultas simples.

• Match de entidades

  Um índice léxico de nomes vindos das entidades e tags do frontmatter, com peso pela frequência inversa de páginas.

• Vizinhos no grafo

  Um salto pela tabela de links: wikilinks, links markdown, arestas tipadas e links entre projetos. SQL puro, sem banco de grafos.

• Observações

  Full-text sobre as observações brutas do projeto. Cada sessão que casa vota uma vez, pela melhor observação, na própria página de sessão, então o detalhe que nunca chegou à página ainda a encontra. Ligado por padrão desde a 3.0.

• Vetores, opcionais

  Similaridade de cosseno sobre embeddings do modelo local que roda dentro do processo. Ligado por padrão desde a 2.0, nunca obrigatório, e força bruta de propósito.

Depois da fusão

• Reciprocal Rank Fusion com k=60 junta os fluxos pela posição no ranking, então nenhum fluxo precisa de calibração de score.
• Um multiplicador de autoridade com limite empurra então as disputas apertadas para o lado de regras, decisões, procedimentos e gotchas mantidos. Páginas episódicas e históricas continuam aparecendo na busca, e nada é excluído de cara.
• Rerank opcional por LLM: uma chamada por consulta sobre até 30 títulos e trechos. Qualquer falha mantém a ordem local. Ainda não existe um reranker local.
• Se as páginas compiladas não trouxerem nada, uma busca limitada nas observações brutas devolve raw_hits.
• Os filtros entram antes do ranking: kind, tag, tier e um prefixo de caminho restringem todas as faixas, então uma página rara não é empurrada para fora por uma comum.
• Dois sinais opcionais começam em zero: um reduz a autoridade de uma página com feedback de desatualizada ou errada em aberto; o outro favorece uma página que a mesma sessão leu ou marcou como útil para uma consulta parecida. Uma reescrita zera os dois.
• Passe explain=true para ver, em cada resultado, as posições por fluxo, as contribuições do RRF e o multiplicador.

ARCHITECTURE.md, com todas as 16 invariantesDecisões de design e opções rejeitadas