Como o Pinky Brain funciona

Explicação de ponta a ponta: o que faz, quem cria os documentos, como eles são indexados e pesquisados, e como se conecta a um projeto / ao Claude Code.

1. A ideia em uma frase

Os .md com frontmatter são a fonte da verdade do conhecimento; o pinky_brain os indexa (SQLite + busca híbrida) e os recupera quando um agente ou um humano precisa deles. O índice é derivado e descartável — é reconstruído a partir dos .md.

2. Duas partes que convém não confundir

ParteO que éQuem a gerencia
O conhecimentoos arquivos .md (gotchas, padrões, decisões, diary)criado pelo agente ou pelo humano (ver §3)
O motoro código Rust que indexa e pesquisa (CLI + MCP + hooks)pinky_brain
pinky não inventa documentos. O motor apenas salva, indexa e pesquisa. Decidir o que e quando salvar é comportamento do agente, guiado por uma regra.

3. Quem cria os documentos? (a pergunta-chave)

Três fontes, nenhuma delas é "mágica do binário":

  1. O agente, seguindo a regra rules/use-pinky-brain.md. Essa regra é a "skill" que diz ao agente BUSQUE antes de agir, SALVE após descobrir um gotcha/padrão/decisão, deixe breadcrumbs, escreva diary. Quando o agente cumpre uma dessas condições, cria um .md com frontmatter em documentation/ (do projeto) ou em ~/.pinky/brain/ (global).
  2. O hook stop (do pinky-hooks): ao terminar uma sessão/tarefa, **adiciona uma entrada de diary** automaticamente em documentation/diary/YYYY-MM-DD.md.
  3. Você, à mão: qualquer .md com o frontmatter correto conta.

Sem a regra (#1), o pinky ainda funciona como buscador, mas o conhecimento não é capturado sozinho: é a regra que converte "descobri algo" em "salvei isso".

4. O ciclo de vida do conhecimento

   CREAR                INDEXAR              BUSCAR                 MANTENER
 (.md nuevo)  ──▶  pinky reindex   ──▶  brain_search / pinky   ──▶  dedup · stale
 agente/hook/        (parse + chunk        search (BM25+vector       · rollup
 humano              + embed → SQLite)     + RRF [+ rerank])         · telemetry
  • Criar: nasce um .md (regra, hook ou à mão).
  • Indexar: pinky reindex <carpeta> faz o parse do frontmatter, quebra o corpo em chunks, os embeda (modelo local multilingual-e5-small) e os salva no índice SQLite (FTS5 + sqlite-vec). É incremental: só reindexa o que mudou.
  • Buscar: busca híbrida — full-text (BM25) + vetor (semântica), fundidos com Reciprocal Rank Fusion, opcionalmente com rerank léxico (--rerank).
  • Manter: dedup (quase-duplicados), stale (entradas antigas a re-verificar), rollup (resumo de diaries), telemetry (o que se usa / o que nunca), eval (qualidade do retrieval).

5. Os três pontos de acesso ao motor

O mesmo índice é usado de três formas:

  1. CLI pinky — para você / scripts: reindex, search, dedup, stale, rollup, backlinks, eval, telemetry, stats, doctor.
  2. MCP pinky-mcp — para o agente: expõe a tool brain_search (e brain_stats). O agente a chama para consultar o conhecimento sem fazer grep. Registra-se no Claude Code (make mcp-register).
  3. Hooks pinky-hooks — automatizam o uso a partir do Claude Code:
    • SessionStart: mostra as stats do brain ao iniciar.
    • PreToolUse(Read): injeta conhecimento relevante antes de ler um arquivo.
    • PreToolUse(Write/Edit): avisa gotchas relacionados antes de escrever.
    • Stop: escreve a entrada de diary.

6. Formato de um documento

Todo .md indexável leva frontmatter YAML. Exemplo de um gotcha:

---
type: gotcha            # gotcha | pattern | decision | diary | guide | note
project: sgsvp
created: 2026-06-30
last_verified: 2026-06-30
tags: [postgres, pool]
---
# Título del gotcha

Cuerpo en markdown. La primera línea `# ...` se usa como título si no hay `title`
en el frontmatter.

type, tags, project, created, last_verified tornam-se metadata indexada (para filtrar e para o decay por antiguidade).

7. Dois níveis de conhecimento

  • De projeto: vive em <proyecto>/documentation/, versionado junto com o código.
  • Global (entre projetos): ~/.pinky/brain/ — um repo git à parte, sincronizável entre suas máquinas com git pull/push.

O índice (brain.db) nunca é versionado; é reconstruído com reindex.

8. Como conectá-lo a um projeto + ao Claude Code

# 1. Instalar los binarios (pinky, pinky-mcp, pinky-hooks)
make up                                   # en el repo de pinky_brain

# 2. Indexar el conocimiento del proyecto
pinky reindex ./documentation --project miproyecto

# 3. Darle la tool al agente (registra el MCP en Claude Code)
make mcp-register                         # → claude mcp add pinky -- pinky-mcp

# 4. Que el agente capture conocimiento: agregá la regla a tu CLAUDE.md
#    o cargala como rule/skill — ver rules/use-pinky-brain.md

# 5. (opcional) Configurar los hooks de Claude Code apuntando a `pinky-hooks`
#    SessionStart / PreToolUse(Read|Write) / Stop

Com isso: o agente busca antes de agir (brain_search), salva o que descobre (regra), e deixa diary ao terminar (hook). O conhecimento cresce sozinho à medida que você trabalha.

9. Resumo

  • pinky_brain = motor de conhecimento (salvar + indexar + buscar), não um autor.
  • Os documentos são criados pelo agente (regra), pelo hook stop, ou por você.
  • Um único índice, três acessos: CLI, MCP (para o agente), hooks (Claude Code).
  • Busca híbrida, manutenção (dedup/stale/rollup/telemetry/eval), 2 níveis (projeto/global). Ver PLAN.md para a arquitetura completa.