brain-refresh

Brain Refresh

Refreshes the qmd index so search reflects the current state of the vault. Wraps pnpm qmd:reindex (incremental) and the qmd CLI's force-embed flag.

Brain Discovery

All commands target the default brain registered in ~/.claude-second-brain/config.toml. Resolve the brain root via the CLI and run qmd through the CLI proxy:

BRAIN_PATH=$(npx -y claude-second-brain path)
npx -y claude-second-brain qmd -- status

Pass --brain <name> before the -- to target a non-default brain.

When to Use

• After a /brain-ingest session (or several) — batch the refresh, don't run after every file edit
• After manual edits to wiki/ or raw-sources/ files
• When /brain-search results feel stale or miss recently added content
• After upgrading @tobilu/qmd or changing the embedding model — use force mode

Procedure

All pnpm qmd:* commands must run from $BRAIN_PATH; the CLI proxy (claude-second-brain qmd) works from anywhere.

Default — Incremental Refresh

Run:

cd "$BRAIN_PATH" && pnpm qmd:reindex

This script does two things:

1. Update — scans collections for new, changed, or deleted files and updates the index
2. Embed — generates vector embeddings for any chunks that need them

Only chunks that changed get re-embedded, so this is fast on subsequent runs.

Force Mode (force argument)

When the user passes force, re-embed every chunk — not just the changed ones. Use after embedding-model changes or if embeddings appear corrupted.

# Step 1 — update the file index first
cd "$BRAIN_PATH" && pnpm qmd:reindex

# Step 2 — force re-embed everything
npx -y claude-second-brain qmd -- embed -f

Force mode is slow — confirm with the user before proceeding if the wiki is large.

Verify

After refresh, confirm with:

npx -y claude-second-brain qmd -- status

Document and embedding counts should be non-zero and reflect recent activity. If embeddings show as 0 or far below document count, re-run the refresh.