By name: brain description: "Personal knowledge base CLI — your long-term memory across sessions. Use when the user asks about 记录, 知识库, memo, note, dsat, insight, knowledge, preference, todo, checkpoint, or any persistent capture/recall task. Also load at the start of any non-trivial task and run brain brief to absorb durable preferences and recent context in one shot."
Brain Knowledge System
Pure-data CLI for capture + search across sessions. No LLM calls — intelligence comes from this agent.
Session Start
Before any non-trivial task:
brain cat BRAIN.md— philosophy, triggers, user-owned rules. BRAIN.md is part of memory, not just a command reference. Re-read when uncertain or when the user mentions a trigger word.brain brief— preferences + recent memo / notes / open todos.brain search "<topic>"whenever the user references prior work.
If SKILL.md (this file) and BRAIN.md disagree, BRAIN.md wins.
Trigger Words
| User says... | Do this |
|---|---|
| "checkpoint" / "存档" / "记一下" | 写一条 episodic 记录：brain memo add -s <slug> -m "..." (≤200 chars, past tense). If substantive long content exists (narrative/decisions/debug/analysis/code), write the note FIRST (brain note add -s <slug>) and add --ref notes/<path> to the memo. Same slug across the pair. |
| "preference" / "from now on" / "以后..." | brain preference add -s <slug> -m "<rule>" |
| "todo" / "记个 TODO" | brain todo add -s <slug> -m "..." -p P1 |
| Hits an anti-pattern / mistake | brain dsat add -m "..." -t <tag> immediately |
| Non-obvious finding | brain insight add -s <slug> |
| "what did we...", "last time..." | brain search first; cite slugs. Search is rg literal/regex — cover synonyms via 'a|b|中文' or repeatable -e; fall back to <layer> list --since 7d if nothing hits. |
| Stable conclusion ready | brain knowledge add -c <cat> -n <name> |
Commands
| Task | Command |
|---|---|
| Session brief (preferences + recent activity) | brain brief [--since 7d] [--limit 20] |
| Quick capture (≤5 lines) | brain memo add -s slug -m "..." -t tag |
| Process doc / debug log | brain note add -s "slug" — appends to existing slug across days; -w forces fresh |
| Mistake / anti-pattern | brain dsat add -m "..." -t tag |
| Non-obvious finding | brain insight add -s "slug" |
| Stable conclusion | brain knowledge add -c category -n name [--from file] |
| Durable collab rule | brain preference add -s slug -m "rule" |
| Task tracking | brain todo add -s slug -m "..." -p P1 -t tag |
| Todo events | `brain todo block |
| List a layer | brain <layer> list [--since 7d] [-t tag] [--limit N] |
| Show full content for a slug | `brain <memo |
| List knowledge w/ titles | brain knowledge list [-c category] [-t tag] [--since 7d] [--limit N] |
| List tools w/ descriptions | brain tools list |
| Search (rg literal/regex; OR via -e or |) | brain search "q1" [-e q2 -e q3] [-l layer] |
| Write / append / cp / diff / commit | brain <op> <path> — writes auto-sync |
| Shell ops (full shell, pipes, globs) | brain exec <cmd...> — $SHELL -c at brain root, auto-syncs + lints |
| Sandboxed shortcuts (brain root only) | brain cat / brain ls / brain rm |
| Raw shortcuts (arbitrary code; no path sandbox) | brain python (=python3) / brain bash |
| Mark old entries superseded (dream prune) | brain supersede <new-path> <old-path>... [--force] |
| Validate frontmatter | brain lint |
TODO Lifecycle
brain todo add → brain todo start <slug> → brain todo done <slug>
Session lifecycle
Codex's Stop hook (installed by brain install codex) prompts you at session end. First judge: is this turn worth sedimenting? Worth: decisions, mistakes, plans, unfinished work, non-obvious findings. Not worth: pure Q&A, reading files, confirming config. If not worth, just stop — don't write a junk memo.
If worth:
- Valuable long content (narrative, decisions, debug trail, analysis, code excerpts)? Write the note FIRST —
brain note add -s <slug>(body from stdin or $EDITOR). Skip when there's nothing worth narrating beyond a one-liner. - Write the memo —
brain memo add -s <slug> -t auto,session -m "<≤200 字符, past tense>". If step 1 was done, add--ref notes/<path>so memo points back. Reuse the slug across turns on the same topic; switch only on topic shift. slug names the task (fix-xxx/import-yyy/review-mr-zzz), never a timestamp. brain sync push --quiet— commit + push (the hook does this too as a second action).
After recording, just stop. The memo is the record; no extra summary to the user.
Rules
- Paths are relative to brain root — works from any CWD; never print or assume the brain's absolute filesystem location
- Read BRAIN.md at session start and whenever uncertain; BRAIN.md > SKILL.md on conflict.
- memo vs note routing.
brain memo= one-line "what was done" (≤200 chars).brain note= substantive long content (narrative/decisions/debug/analysis/code excerpts) — write it when it exists, otherwise skip. When paired: write the note first, then the memo with--ref notes/<path>, same slug. - "checkpoint" trigger (user-initiated) follows the same routing.
- Structured adds (memo/dsat/insight/todo/preference/note) auto-sync (write-through)
- For knowledge/ and tools/ — edit files directly, then
brain commit brain cpvalidates frontmatter on copy to structured layers- Full reference:
brain cat BRAIN.md
Shell delegation
Read, list, remove, and tool execution all delegate to the user's shell via
brain exec:
brain exec cat knowledge/code-gateway.md brain exec ls -la memo/2026/06/ brain exec rm memo/2026/06/02/foo.md brain exec ./tools/xray.py UID
After the command exits, brain runs brain lint (silent if clean,
surfaces findings if structured-layer frontmatter is broken) and auto-syncs.
For common cases there are also direct shortcuts that pass args verbatim (no shell re-parse) and inherit the same lint + auto-sync:
brain cat