pks brain refresh

Refresh runs the whole brain pipeline — ingest, extract, synth, wiki, adr — in sequence for the current project. Instead of one confirmation prompt per phase, it produces a single combined cost estimate up front and asks once.

It is the command to put on a habit: run it at the end of a working week and the repository's brain catches up with everything you did.

1. Prerequisites

• A git repository. Every AI phase writes to ./.pks/brain/, so refresh exits with code 1 outside a repo.
• Claude Code session history at ~/.claude/projects.
• Claude billing or an API key, unless you run with --no-ai.

2. Plan the whole pipeline

pks brain refresh --dry-run

Every phase is planned and one combined estimate is printed.

Note. Ingest actually executes during a dry run and writes to the global ~/.pks-cli/brain/ layer. That is deliberate — ingest is free and deterministic, and its real output count is what makes the estimate for the AI phases accurate. Only the AI phases are simulated.

3. Run it

pks brain refresh

The combined gate fires once, when the total estimated cost across all non-skipped AI phases reaches $1.00. Pass -y to skip it.

Downstream phases are skipped automatically when extract produced no new output, which avoids re-synthesizing identical inputs. That decision is re-evaluated after the real extract run against the actual count, so a run that planned to synthesize can still skip synth, wiki, and adr if every extract failed.

4. Narrow the window

pks brain refresh --since 7d -y

--since applies to both ingest and extract. It accepts 7d, 24h, 30m, or an ISO date, and it is the main lever for keeping a routine refresh cheap.

5. Skip phases

pks brain refresh --skip-ingest --skip-adr

Each phase has its own skip flag: --skip-ingest, --skip-extract, --skip-synth, --skip-wiki, --skip-adr. Use them to re-render one part of the tree without re-running the rest.

To force the downstream phases even when extract produced nothing new:

pks brain refresh --force

6. Run without spending

pks brain refresh --no-ai

Ingest still runs in full; synth, wiki, and adr emit their deterministic skeletons. This is a reasonable weekly baseline when you only want the raw layer and the cluster index kept current.

7. Verify

pks brain status

The refresh suggestions section is the fastest check: it names sessions with no extract, extracts older than their source, and extracts made with a stale prompt version. An empty list means the brain is current.

Options

Troubleshooting

A dry run modified the global brain directory. Expected. Ingest is never simulated. Add --skip-ingest if you want a plan that touches nothing.

Synth, wiki, and adr were skipped without asking. Extract produced no new output. Pass --force to run them anyway.

Exit code 1 immediately. The working directory is not inside a git repository.

The estimate is much higher than expected. The first refresh on a machine with long history plans every session. Add --since 7d and build up in slices.

See also

• Quickstart: build your first brain — the same pipeline run one phase at a time
• pks brain extract — the phase that dominates the cost estimate
• pks brain status — the dashboard that tells you when a refresh is due
• pks brain CLI reference — every command and flag in the group