Brain Advisor
Convention: See
conventions/brain-first.md(viaget_skill conventions/brain-first). This skill is the proactive voice of the brain — it tells the owner how to run it better.
Contract
This skill guarantees:
- Read-only. The
advisortool never mutates. It computes a ranked list of actions from existing brain state. - Print, never execute. You SHOW the user the findings and ASK before running any fix. The user owns every decision.
- Bounded nagging. On a cadence, surface only what changed or what's critical; don't repeat an ignored low-severity item every run.
When to run
- On demand when the user asks "how do I get more out of this brain?"
- On a weekly cadence via the scheduled-checkup recipe below (even idle brains get a "here's how to run this better" ping).
How to run it
Call the advisor tool (from the shell: memrain call advisor '{}').
The payload is { version, generated_at, worst, findings: [...] }, with
worst as the severity gate: clean, warn, or critical. Each finding has:
severity—critical|warn|infotitle— one-line why-it-mattersfix— the exact action to fix it (amemrainshell command or an MCP tool call, stated explicitly)
What to do with the findings
- Read the findings, highest severity first.
- Summarize the top 1-3 to the user in their own channel/voice. Lead with any
criticalitem (e.g. pending migrations). - For each, show the suggested
fixand ask whether to run it. - If they say yes, run exactly the stated fix yourself — a
memraincommand on the host or the named MCP tool call — nothing more. Version-drift findings route toskills/brain-upgrade(the deploy loop), not to an ad-hoc command. - Never run a fix the user didn't approve.
Scheduled checkup recipe (weekly)
Install a weekly checkup via the operator's host scheduler (a systemd timer)
or the agent harness's own scheduler — see skills/cron-scheduler for the
recipe. Keep the prompt THIN — the job just reads this skill and runs the
advisor:
- Schedule: weekly, one quiet-hours-respecting slot (e.g. Monday 09:00 local).
- Job prompt:
Read skills/advisor/SKILL.md and call the advisor tool. If anything is critical or new since last run, ping me with the top items and the exact fix commands. Ask before fixing. - Idempotent: the advisor is read-only, so a double-fire is harmless.
Keep a run-history page in the brain (page_append reports/advisor-history)
so on each fire you can tell the user what is new since last run rather
than re-listing everything.
Output Format
When you surface advisor findings to the user, lead with severity and keep it scannable:
Brain checkup — 2 things worth your attention
CRITICAL Schema migrations are pending.
Fix: memrain doctor, then apply migrations (want me to run it?)
WARN The server is behind the latest release.
Fix: skills/brain-upgrade (pull + rebuild on the host)
- One block per finding, highest severity first.
- Always show the exact
fixaction and ASK before running it. - If nothing is pressing, say so in one line ("brain looks healthy") — don't manufacture work.
Anti-Patterns
- Running a fix without asking. The advisor is read-only by contract. Never
run any
fixaction without the user's explicit yes. - Dumping the raw JSON at the user. Translate findings into their voice; lead with what matters.
- Re-nagging ignored low-severity items every run. Use the "new since last
run" delta (the
reports/advisor-historypage); respect the user's prior non-action. - Treating
infolikecritical. Only block/insist oncriticalfindings (pending migrations).infois a gentle nudge. - Expecting the
advisortool to report workspace install state. Over MCP the advisor returns brain-state signals only; whether this workspace has the brain's skills installed is checked vialist_brain_skillpack(ormemrain skillpackon the host).