Come funziona Pinky Brain

Spiegazione da capo a fine: cosa fa, chi crea i documenti, come vengono indicizzati e cercati, e come si collega a un progetto / a Claude Code.

1. L'idea in una frase

I .md con frontmatter sono la fonte di verità della conoscenza; pinky_brain li indicizza (SQLite + ricerca ibrida) e li recupera quando un agente o un umano ne ha bisogno. L'indice è derivato e usa e getta — si ricostruisce dai .md.

2. Due parti da non confondere

ParteCos'èChi la gestisce
La conoscenzai file .md (gotchas, pattern, decisioni, diary)la crea l'agente o l'umano (vedi §3)
Il motoreil codice Rust che indicizza e cerca (CLI + MCP + hooks)pinky_brain
pinky non inventa documenti. Il motore si limita a salvare, indicizzare e cercare. Decidere cosa e quando salvare è comportamento dell'agente, guidato da una regola.

3. Chi crea i documenti? (la domanda chiave)

Tre fonti, nessuna è "magia del binario":

  1. L'agente, seguendo la regola rules/use-pinky-brain.md. Quella regola è la "skill" che dice all'agente CERCA prima di agire, SALVA dopo aver scoperto un gotcha/pattern/decisione, lascia breadcrumbs, scrivi diary. Quando l'agente soddisfa una di queste condizioni, crea un .md con frontmatter in documentation/ (del progetto) o in ~/.pinky/brain/ (globale).
  2. L'hook stop (di pinky-hooks): al termine di una sessione/task, **aggiunge una voce di diary** automaticamente in documentation/diary/YYYY-MM-DD.md.
  3. Tu, a mano: qualsiasi .md con il frontmatter corretto è valido.

Senza la regola (#1), pinky funziona comunque come motore di ricerca, ma la conoscenza non si cattura da sola: è la regola che trasforma "ho scoperto qualcosa" in "l'ho salvato".

4. Il ciclo di vita della conoscenza

   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
  • Creare: nasce un .md (regola, hook o a mano).
  • Indicizzare: pinky reindex <carpeta> fa il parsing del frontmatter, taglia il corpo in chunk, li incorpora (modello locale multilingual-e5-small) e li salva nell'indice SQLite (FTS5 + sqlite-vec). È incrementale: re-indicizza solo ciò che è cambiato.
  • Cercare: ricerca ibrida — full-text (BM25) + vettoriale (semantica), fusi con Reciprocal Rank Fusion, opzionalmente con rerank lessicale (--rerank).
  • Mantenere: dedup (quasi-duplicati), stale (voci vecchie da ri-verificare), rollup (riassunto dei diaries), telemetry (cosa si usa / cosa mai), eval (qualità del retrieval).

5. I tre punti di accesso al motore

Lo stesso indice si usa in tre modi:

  1. CLI pinky — per te / script: reindex, search, dedup, stale, rollup, backlinks, eval, telemetry, stats, doctor.
  2. MCP pinky-mcp — per l'agente: espone la tool brain_search (e brain_stats). L'agente la chiama per consultare la conoscenza senza fare grep. Si registra in Claude Code (make mcp-register).
  3. Hooks pinky-hooks — automatizzano l'uso da Claude Code:
    • SessionStart: mostra le stats del brain all'avvio.
    • PreToolUse(Read): inietta conoscenza rilevante prima di leggere un file.
    • PreToolUse(Write/Edit): segnala gotchas correlati prima di scrivere.
    • Stop: scrive la voce di diary.

6. Formato di un documento

Ogni .md indicizzabile ha un frontmatter YAML. Esempio di un 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 diventano metadata indicizzata (per filtrare e per il decadimento per anzianità).

7. Due livelli di conoscenza

  • Di progetto: vive in <proyecto>/documentation/, versionato con il codice.
  • Globale (tra progetti): ~/.pinky/brain/ — un repo git a parte, sincronizzabile tra le tue macchine con git pull/push.

L'indice (brain.db) non viene mai versionato; si ricostruisce con reindex.

8. Come collegarlo a un progetto + a 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

Con questo: l'agente cerca prima di agire (brain_search), salva ciò che scopre (regola), e lascia diary al termine (hook). La conoscenza cresce da sola man mano che lavori.

  • pinky_brain = motore di conoscenza (salvare + indicizzare + cercare), non un autore.
  • I documenti li creano l'agente (regola), l'hook stop, o tu.
  • Un solo indice, tre accessi: CLI, MCP (per l'agente), hooks (Claude Code).
  • Ricerca ibrida, manutenzione (dedup/stale/rollup/telemetry/eval), 2 livelli (progetto/globale). Vedi PLAN.md per l'architettura completa.