Cómo funciona Pinky Brain

Explicación de extremo a extremo: qué hace, quién crea los documentos, cómo se indexan y se buscan, y cómo se conecta a un proyecto / a Claude Code.

1. La idea en una frase

Los .md con frontmatter son la fuente de verdad del conocimiento; pinky_brain los indexa (SQLite + búsqueda híbrida) y los recupera cuando un agente o un humano los necesita. El índice es derivado y desechable — se reconstruye desde los .md.

2. Dos partes que conviene no confundir

ParteQué esQuién la maneja
El conocimientolos archivos .md (gotchas, patrones, decisiones, diary)lo crea el agente o el humano (ver §3)
El motorel código Rust que indexa y busca (CLI + MCP + hooks)pinky_brain
pinky no inventa documentos. El motor solo guarda, indexa y busca. Decidir qué y cuándo guardar es comportamiento del agente, guiado por una regla.

3. ¿Quién crea los documentos? (la pregunta clave)

Tres fuentes, ninguna es "magia del binario":

  1. El agente, siguiendo la regla rules/use-pinky-brain.md. Esa regla es la "skill" que le dice al agente BUSCÁ antes de actuar, GUARDÁ tras descubrir un gotcha/patrón/decisión, dejá breadcrumbs, escribí diary. Cuando el agente cumple una de esas condiciones, crea un .md con frontmatter en documentation/ (del proyecto) o en ~/.pinky/brain/ (global).
  2. El hook stop (de pinky-hooks): al terminar una sesión/tarea, **agrega una entrada de diary** automáticamente en documentation/diary/YYYY-MM-DD.md.
  3. Vos, a mano: cualquier .md con el frontmatter correcto cuenta.

Sin la regla (#1), pinky igual funciona como buscador, pero el conocimiento no se captura solo: es la regla la que convierte "descubrí algo" en "lo guardé".

4. El ciclo de vida del conocimiento

   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
  • Crear: nace un .md (regla, hook o a mano).
  • Indexar: pinky reindex <carpeta> parsea el frontmatter, corta el cuerpo en chunks, los embebe (modelo local multilingual-e5-small) y los guarda en el índice SQLite (FTS5 + sqlite-vec). Es incremental: solo re-indexa lo que cambió.
  • Buscar: búsqueda híbrida — full-text (BM25) + vector (semántica), fusionados con Reciprocal Rank Fusion, opcionalmente con rerank léxico (--rerank).
  • Mantener: dedup (casi-duplicados), stale (entradas viejas a re-verificar), rollup (resumen de diaries), telemetry (qué se usa / qué nunca), eval (calidad del retrieval).

5. Los tres puntos de acceso al motor

El mismo índice se usa de tres formas:

  1. CLI pinky — para vos / scripts: reindex, search, dedup, stale, rollup, backlinks, eval, telemetry, stats, doctor.
  2. MCP pinky-mcp — para el agente: expone la tool brain_search (y brain_stats). El agente la llama para consultar el conocimiento sin grepear. Se registra en Claude Code (make mcp-register).
  3. Hooks pinky-hooks — automatizan el uso desde Claude Code:
    • SessionStart: muestra stats del brain al iniciar.
    • PreToolUse(Read): inyecta conocimiento relevante antes de leer un archivo.
    • PreToolUse(Write/Edit): avisa gotchas relacionados antes de escribir.
    • Stop: escribe la entrada de diary.

6. Formato de un documento

Todo .md indexable lleva frontmatter YAML. Ejemplo de 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 se vuelven metadata indexada (para filtrar y para el decay por antigüedad).

7. Dos niveles de conocimiento

  • De proyecto: vive en <proyecto>/documentation/, versionado con el código.
  • Global (entre proyectos): ~/.pinky/brain/ — un repo git aparte, sincronizable entre tus máquinas con git pull/push.

El índice (brain.db) nunca se versiona; se reconstruye con reindex.

8. Cómo conectarlo a un proyecto + 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 eso: el agente busca antes de actuar (brain_search), guarda lo que descubre (regla), y deja diary al terminar (hook). El conocimiento crece solo a medida que trabajás.

9. Resumen

  • pinky_brain = motor de conocimiento (guardar + indexar + buscar), no un autor.
  • Los documentos los crean el agente (regla), el hook stop, o vos.
  • Un solo índice, tres accesos: CLI, MCP (para el agente), hooks (Claude Code).
  • Búsqueda híbrida, mantenimiento (dedup/stale/rollup/telemetry/eval), 2 niveles (proyecto/global). Ver PLAN.md para la arquitectura completa.