How Pinky Brain works

End-to-end explanation: what it does, who creates the documents, how they are indexed and searched, and how it connects to a project / to Claude Code.

1. The idea in one sentence

The .md files with frontmatter are the source of truth of the knowledge; pinky_brain indexes them (SQLite + hybrid search) and retrieves them when an agent or a human needs them. The index is derived and disposable — it is rebuilt from the .md files.

2. Two parts worth not confusing

PartWhat it isWho manages it
The knowledgethe .md files (gotchas, patterns, decisions, diary)created by the agent or the human (see §3)
The enginethe Rust code that indexes and searches (CLI + MCP + hooks)pinky_brain
pinky does not invent documents. The engine only stores, indexes and searches. Deciding what and when to save is agent behavior, guided by a rule.

3. Who creates the documents? (the key question)

Three sources, none of them "binary magic":

  1. The agent, following the rule rules/use-pinky-brain.md. That rule is the "skill" that tells the agent SEARCH before acting, SAVE after discovering a gotcha/pattern/decision, leave breadcrumbs, write diary. When the agent meets one of those conditions, it creates a .md with frontmatter in documentation/ (of the project) or in ~/.pinky/brain/ (global).
  2. The stop hook (from pinky-hooks): when a session/task ends, it **adds a diary entry** automatically in documentation/diary/YYYY-MM-DD.md.
  3. You, by hand: any .md with the correct frontmatter counts.

Without the rule (#1), pinky still works as a search engine, but the knowledge is not captured on its own: it is the rule that turns "I discovered something" into "I saved it".

4. The knowledge life cycle

   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
  • Create: a .md is born (rule, hook or by hand).
  • Index: pinky reindex <carpeta> parses the frontmatter, splits the body into chunks, embeds them (local model multilingual-e5-small) and stores them in the SQLite index (FTS5 + sqlite-vec). It is incremental: it only re-indexes what changed.
  • Search: hybrid search — full-text (BM25) + vector (semantic), fused with Reciprocal Rank Fusion, optionally with lexical rerank (--rerank).
  • Maintain: dedup (near-duplicates), stale (old entries to re-verify), rollup (diary summary), telemetry (what is used / what never is), eval (retrieval quality).

5. The three access points to the engine

The same index is used in three ways:

  1. CLI pinky — for you / scripts: reindex, search, dedup, stale, rollup, backlinks, eval, telemetry, stats, doctor.
  2. MCP pinky-mcp — for the agent: it exposes the brain_search tool (and brain_stats). The agent calls it to query the knowledge without grepping. It is registered in Claude Code (make mcp-register).
  3. Hooks pinky-hooks — they automate usage from Claude Code:
    • SessionStart: shows brain stats on startup.
    • PreToolUse(Read): injects relevant knowledge before reading a file.
    • PreToolUse(Write/Edit): warns about related gotchas before writing.
    • Stop: writes the diary entry.

6. Format of a document

Every indexable .md carries YAML frontmatter. Example of a 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 become indexed metadata (for filtering and for the age-based decay).

7. Two levels of knowledge

  • Project-level: lives in <proyecto>/documentation/, versioned with the code.
  • Global (across projects): ~/.pinky/brain/ — a separate git repo, syncable between your machines with git pull/push.

The index (brain.db) is never versioned; it is rebuilt with reindex.

8. How to connect it to a project + to 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

With that: the agent searches before acting (brain_search), saves what it discovers (rule), and leaves diary when finishing (hook). The knowledge grows on its own as you work.

9. Summary

  • pinky_brain = knowledge engine (store + index + search), not an author.
  • The documents are created by the agent (rule), the stop hook, or you.
  • A single index, three accesses: CLI, MCP (for the agent), hooks (Claude Code).
  • Hybrid search, maintenance (dedup/stale/rollup/telemetry/eval), 2 levels (project/global). See PLAN.md for the complete architecture.