Pinky Brain Configuration

Pinky is configured with flags (CLI) and environment variables (all three pieces: CLI, MCP and hooks). Additionally, ~/.pinky/config.toml (optional) defines defaults for those env vars — a thin layer so you don't repeat them on every machine.

Full precedence: flag > env var > ~/.pinky/config.toml > default.

Central config (`~/.pinky/config.toml`)

TOML subset: key = "value" lines, # comments. It only sets defaults for env vars not already set (an explicit env always wins):

lang = "en"              # PINKY_LANG
db = "brain.db"          # PINKY_DB
save_dir = "documentation"   # PINKY_SAVE_DIR
diary_dir = "documentation/diary"  # PINKY_DIARY_DIR
project = "myproject"    # PINKY_PROJECT
hash_embed = false       # PINKY_HASH_EMBED (only when true)
log = "warn"             # PINKY_LOG

Precedence in the CLI: flag > env var > default. E.g.: --db x.db wins over PINKY_DB, which wins over the default brain.db.

Environment variables

Variable	Used by	Default	What it does
`PINKY_DB`	CLI · MCP · hooks	`brain.db`	Path of the SQLite index (derived and disposable). Set it the same in all three pieces so that CLI and agent see the same base. `pinky init` registers the MCP with `PINKY_DB=brain.db`, the same default as the CLI, so `pinky reindex` and the agent share the index.
`PINKY_HASH_EMBED`	CLI · MCP	(not set)	If present, uses the deterministic embedder (without downloading the ONNX model). Useful offline/CI. In the CLI it is equivalent to `--hash-embed`.
`PINKY_SAVE_DIR`	MCP	`documentation`	Folder where `brain_save` writes the source-of-truth `.md` files.
`PINKY_PROJECT`	MCP	(global)	If set, the entries the MCP saves stay in the `project:<value>` scope (filterable by project).
`PINKY_DIARY_DIR`	hooks	(stdout)	Folder where the `stop` hook writes the diary (`YYYY-MM-DD.md`). Without it, the line goes to stdout.
`PINKY_LOG` / `RUST_LOG`	all	`warn`	Logging level (`error`/`warn`/`info`/`debug`/`trace`). Always goes to stderr (it does not pollute the MCP's stdout nor the CLI's data output).
`PINKY_EMBED_SOCKET`	CLI · MCP	`~/.pinky/embed.sock`	Socket of the shared embeddings daemon (see below).
`PINKY_EMBED_IDLE_SECS`	daemon	`900`	Seconds without requests before the daemon exits and frees the model. `0` = stay resident.
`PINKY_EMBED_INPROC`	CLI · MCP	(not set)	Loads the model inside each process (the pre-0.2.3 behavior). Costs ~1.2 GB per process; only useful to debug the daemon.
`PINKY_EMBED_NO_SPAWN`	CLI · MCP	(not set)	Never auto-spawn the daemon: if it is not running, fall back to an in-process model. For CI.
`PINKY_GRAPH_EXPAND`	CLI · MCP	(on)	`0` disables both graph-aware ranking steps: the expansion (an entry one explained hop from a strong hit can take one of the existing result slots) and the diversification (past 2 hits from the same community the rest are demoted). Neither changes how many results come back.
`FASTEMBED_CACHE_DIR`	all	`~/.pinky/models`	Where the ONNX model is cached. Pinned centrally because fastembed's default is `./.fastembed_cache` relative to the cwd, which produced one 465 MB copy per project. An existing cache (`~/.fastembed_cache`, `./.fastembed_cache`) is reused before falling back to the central one, so upgrading never re-downloads.

The shared embeddings daemon

MCP over stdio spawns one server process per chat. With the model loaded in-process that meant ~1.2 GB resident per open chat — 10 chats ≈ 12 GB.

Since 0.2.3 the model lives in a single daemon and every pinky-mcp / pinky talks to it over a unix socket:

chat 1 ─ pinky-mcp (~10 MB) ┐
chat 2 ─ pinky-mcp (~10 MB) ├─→ ~/.pinky/embed.sock ─→ pinky embed-daemon (~1.2 GB, one)
chat N ─ pinky-mcp (~10 MB) ┘

You do not have to run or configure anything: the first search of the day starts the daemon, and it exits by itself after PINKY_EMBED_IDLE_SECS without requests. Nothing is loaded for a chat that never queries the brain.

pinky embed-daemon --status     # is it up? which model, which pid
pinky embed-daemon --stop       # free its memory now
pinky embed-daemon --idle-secs 0  # run it in the foreground, resident

pinky doctor reports the daemon's state alongside the index checks.

Global CLI flags

Flag	What it does
`--db <path>`	Index to use (equiv. `PINKY_DB`).
`--hash-embed`	Deterministic embedder without model (equiv. `PINKY_HASH_EMBED`).
`--json`	Output in JSON, for scripting. Available in all commands with output to stdout. In `search`, it also disables telemetry logging (programmatic use).
`--version`	Binary version (`pinky`, `pinky-mcp` and `pinky-hooks` report it).

Diagnostics

pinky doctor prints the effective config of the index: schema version, count of entries/chunks, model it was indexed with vs. the active embedder (it warns if they do not match) and the binary version. With --json it is suitable for monitoring.

pinky --db brain.db doctor
pinky --db brain.db --json doctor

Autocompletion

pinky completions zsh  > ~/.zfunc/_pinky        # zsh
pinky completions bash > /etc/bash_completion.d/pinky
pinky completions fish > ~/.config/fish/completions/pinky.fish