brain
Skill2 starsChanged 5 days agoMITView on GitHub
Read, write, and search the project brain (notes, decisions, questions, insights, tasks, milestones). The single interface for all project knowledge and task management.
25 other projects use a version of this.
Adopted by
Most recently taken up by
- jzhao234/big-braintheir own version, first seen Nov 8, 2026
- jonmagic/skillstheir own version, first seen Nov 8, 2026
- keli-wen/agy-stafftheir own version, first seen Nov 8, 2026
- Aiqbee/aiqbee-aitheir own version, first seen Nov 8, 2026
- SeanningTatum/brain-axitheir own version, first seen Nov 1, 2026
- sophonfinance-wq/finance-automation-portfoliotheir own version, first seen Nov 1, 2026
Other versions25 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 25
- keli-wen/agy-staff★ 873same name
- H-mmer/pentest-agents★ 815same name
- Anantys-oss/koan★ 49same name
- sophonfinance-wq/finance-automation-portfolio★ 16same name
- henriquecaner/brain-agent★ 13same name
- Aiqbee/aiqbee-ai★ 7same name
- jonmagic/skills★ 6same name
- tonydzi/second-brain-starter-kit★ 6same name
- aidemd-mcp/server★ 4same name
- gufranco/claude-engineering-rules★ 3same name
15 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository24 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- 1passwordSkill
- brainstormSkill
- bridgeSkill
- claude-switcherSkill
- clear-cacheSkill
- commitSkill
- cross-artifactSkill
- ctoSkill
- diskSkill
- killSkill
- lookSkill
- parseSkill
- pbarSkill
- planSkill
- pruneSkill
- pushSkill
- reportSkill
- researchSkill
- swarmSkill
- vibe-auditSkill
- video-editorSkill
- webSkill
- wikiSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
38 rules. 0 are common, 24 are distinctive, and 14 are very specific to this project.
0
Common
Most of the 20 edited versions we read keep these.
24
Distinctive
This author's own choices. Worth a look.
14
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 55
Start from the auto-loaded state above.
- Distinctive: line 66
If a pillar was specified, filter tasks to that pillar only.
- Distinctive: line 73
Run Recalculate tiers at the end.
- Distinctive: line 87
What shipped this session: Check recent commits since the current session started (or last few hours if no session):
- Very specific: line 107
Find decisions that were made but not logged: Check conversation context for architectural choices, technical decisions, or direction …
- Distinctive: line 120
Fix stale state: Look for obvious inconsistencies:
- Distinctive: line 145
If no prior audit, use 7 days ago as the baseline.
- Distinctive: line 149
Check git history since the last audit:
- Distinctive: line 184
Should it be dropped, deferred, or kept and reprioritized?
- Very specific: line 236
Check if documents in cowork/ reference superseded or dropped decisions:
- Distinctive: line 247
If staleness is found, list affected docs and propose updates.
- Distinctive: line 251
Run the Focus procedure (see below).
- Distinctive: line 268
Read the current mantra (the block between the mantra marker lines in CLAUDE.md, already in your context) and recent high-signal entries:
- Distinctive: line 277
Write it via the Mantra subcommand procedure.
- Very specific: line 313
Create a new entry. Usage: add <type> where type is one of: note, decision, question, insight, task, milestone.
- Distinctive: line 318
Ask the user for:
- Distinctive: line 348
Run the Update procedure (tasks done, decisions logged, plan progress, stale state).
- Very specific: line 350
Compound lesson: If a reusable lesson emerged, write it as an insight tagged lesson: one sentence stating the rule, then Why and How to …
- Distinctive: line 361
Search using FTS5 (ranked by relevance via BM25):
- Distinctive: line 370
If FTS5 returns no results, fall back to LIKE:
- Distinctive: line 378
If no results from either method, suggest related queries based on existing tags.
- Distinctive: line 392
If not a question, error.
- Distinctive: line 393
Ask the user: "What's the answer/decision?" (or infer from conversation context).
- Very specific: line 394
Create the decision with parent_id linking back to the question:
- Distinctive: line 415
Verify both entries exist.
- Distinctive: line 416
Update the dependent entry's meta:
- Very specific: line 422
If depends_on already exists in meta, append to the array rather than replacing.
- Very specific: line 429
Update tags on an entry. Usage: tag <id> <tags>
- Distinctive: line 433
Read the current entry:
- Distinctive: line 455
If nothing meaningful, say so and skip.
- Very specific: line 473
Set completed_at when marking tasks done: Always set completed_at = datetime('now', 'localtime') — this drives plan momentum detection.
- Very specific: line 474
Decisions are permanent: Don't update a decision — create a new one that supersedes it (supersedes column) and mark the old one superseded …
- Very specific: line 475
Questions resolve into decisions: Use resolve <id> to create the linked decision.
- Very specific: line 476
Decision dependencies: Use depends to track what builds on what.
- Distinctive: line 478
Pillar consistency: Check existing pillars before creating new ones.
- Very specific: line 480
Meta is structured: Use json_set / json_extract.
- Very specific: line 481
plan_idis a zero-padded string: Always '003', never bare 3. - Very specific: line 495
If .claude/kit.json has a rules."brain" entry, read it and apply it as an additional instruction for this skill.
“Common” is measured: kept by at least 6 in 10 of the 20 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Focus Items
!sqlite3 -separator ' | ' cowork/brain/BRAIN.db "SELECT '#' || id, title, pillar FROM logs WHERE focus = 1 AND status = 'active';" 2>/dev/null || echo "No focus items set"
Active Tasks by Pillar
!sqlite3 -separator ' | ' cowork/brain/BRAIN.db "SELECT '#' || id, title, pillar, CASE WHEN focus=1 THEN '*' ELSE '' END FROM logs WHERE type = 'task' AND status IN ('active','blocked') ORDER BY pillar, priority ASC, created_at ASC;" 2>/dev/null || echo "No active tasks"
Open Questions
!sqlite3 -separator ' | ' cowork/brain/BRAIN.db "SELECT '#' || id, title FROM logs WHERE type = 'question' AND status = 'active';" 2>/dev/null || echo "None"
Recent Entries
!sqlite3 -separator ' | ' cowork/brain/BRAIN.db "SELECT '#' || id, type, title FROM logs WHERE tier IN ('hot','warm') AND status = 'active' ORDER BY created_at DESC LIMIT 12;" 2>/dev/null || echo "No entries yet"
Existing Tags
!sqlite3 cowork/brain/BRAIN.db "SELECT DISTINCT tags FROM logs WHERE tags IS NOT NULL AND tags != '';" 2>/dev/null || echo "None yet"
Brain
Manage all project knowledge in cowork/brain/BRAIN.db — decisions, questions, insights, tasks, notes, and milestones. One skill, one database, one source of truth.
Input
Optional argument: $ARGUMENTS
Dispatch on the first word:
- (empty) — Review: daily "what's going on" view
update— Update: sync brain to reflect what just happened — mark completed tasks, log decisions, fix stale stateaudit— Audit: deep health check since last auditfocus— Focus: set 2-3 focus itemsadd <type>— Add: create a new entry (note, decision, question, insight, task, milestone)done— Done: close the session — sync the brain, consider the mantra and a lessonmantra— Mantra: consider updating the mantra based on recent worksearch <query>— Search: full-text search across title, body, and tagsresolve <question_id>— Resolve: answer a question by creating a linked decisiondepends <id> <depends_on_id>— Depends: mark that an entry depends on a decisiontag <id> <tags>— Tag: update tags on an existing entry- A bare pillar name (e.g.
platform,backend) — Review filtered to that pillar's tasks
Review (default)
The daily "what's going on" view. Shows focus, tasks, questions, and recent decisions in one pass. The dynamic context above already loaded the current state — use it as your starting point.
Procedure
- Start from the auto-loaded state above. Query deeper if needed:
-- Tasks with bodies for context SELECT id, title, body, tags, pillar, priority, status, meta FROM logs WHERE type = 'task' AND status IN ('active', 'blocked') ORDER BY pillar, priority ASC, created_at ASC; -- Recent decisions SELECT id, created_at, title, substr(body, 1, 120) FROM logs WHERE type = 'decision' AND status = 'active' ORDER BY created_at DESC LIMIT 10; - If a pillar was specified, filter tasks to that pillar only.
- Present findings conversationally:
- Focus items first, with brief status check
- Active tasks grouped by pillar
- Blocked items highlighted with why
- Open questions that need resolution
- Recent decisions that set direction
- Run Recalculate tiers at the end.
Update subcommand
Sync the brain to reflect what actually happened this session. Run after a block of work to make sure the DB matches reality — tasks that got done are marked done, decisions that were made are logged, stale state is cleaned up.
Usage: update
This is lighter than an audit. An audit looks back over days/weeks and asks strategic questions. Update looks at the current session and asks "does the brain match what just happened?"
Procedure
- What shipped this session. Check recent commits since the current session started (or last few hours if no session):
Also check conversation context for work that was done.git log --oneline --since='3 hours ago' - Find tasks that should be done. Cross-reference what shipped against active tasks:
For each active task, check: was this completed by the work that just happened? If yes, mark it done:SELECT id, title, pillar, status, meta FROM logs WHERE type = 'task' AND status = 'active' ORDER BY pillar, created_at DESC;UPDATE logs SET status = 'done', completed_at = datetime('now', 'localtime'), body = body || char(10) || '--- Done: <what was accomplished>' WHERE id = <id>; - Find decisions that were made but not logged. Check conversation context for architectural choices, technical decisions, or direction changes that happened during the session but weren't captured via
/brainstormor/brain add. Log any missing ones:INSERT INTO logs (type, title, body, tags, importance) VALUES ('decision', '<title>', '<rationale>', '<tags>', <importance>); - Check plan progress. If a plan was actively worked on, verify the plan file reflects current state — items checked off, status lines updated, RESUME banner in the right place. Report each gap or fix with the plan's path and line (
/plan, Pointing at a line):SELECT id, title, meta FROM logs WHERE type = 'task' AND json_extract(meta, '$.plan_id') IS NOT NULL AND status = 'active'; - Fix stale state. Look for obvious inconsistencies:
- Tasks marked active that the codebase shows are done
- Decisions that were superseded by newer decisions during this session
- Focus items that were completed and should be cleared
- Present changes. Summarize what was updated: tasks marked done, decisions logged, state fixed. Don't silently modify — show the user what changed.
- Run Recalculate tiers.
Audit subcommand
Deep health check — surfaces stale work, unresolved questions, unacted decisions, and what shipped since the last audit. Ends by recalibrating focus. Not on a fixed schedule — run whenever the brain needs a checkup.
Usage: audit
Step 1 — Find the last audit
SELECT id, created_at, body FROM logs
WHERE type = 'milestone' AND tags LIKE '%audit%'
ORDER BY created_at DESC LIMIT 1;If no prior audit, use 7 days ago as the baseline.
Step 2 — What shipped
Check git history since the last audit:
git log --oneline --since='<last_audit_date>'Query completed entries since the last audit:
SELECT id, type, title, body FROM logs
WHERE status = 'done' AND created_at > '<last_audit_date>'
ORDER BY created_at DESC;Summarize what was accomplished. Group by pillar or theme. Start here — celebrate progress before digging into problems.
Step 3 — Stale work
Find active tasks and questions that haven't been accessed since the last audit:
SELECT id, type, title, pillar, created_at, importance
FROM logs
WHERE status = 'active' AND type IN ('task', 'question')
AND created_at < '<last_audit_date>'
AND focus = 0
AND (json_extract(meta, '$.plan_id') IS NULL
OR json_extract(meta, '$.plan_id') NOT IN (
SELECT DISTINCT json_extract(meta, '$.plan_id') FROM logs
WHERE completed_at >= datetime('now', '-14 days', 'localtime')
))
ORDER BY created_at ASC;For each stale item (old, not focused, no plan momentum):
- Is it still relevant? Check codebase and recent decisions for context changes.
- Should it be dropped, deferred, or kept and reprioritized?
Present findings. Don't auto-drop — propose and wait for direction.
Step 4 — Open questions
SELECT id, title, body, created_at, tags FROM logs
WHERE type = 'question' AND status = 'active'
ORDER BY importance DESC, created_at ASC;For each:
- Has the answer emerged from recent work or decisions? If so, propose resolving it.
- Is it blocking anything?
SELECT id, title FROM logs WHERE json_extract(meta, '$.depends_on') LIKE '%<question_id>%'; - How long has it been open?
Step 5 — Unacted decisions
Decisions are only valuable if they lead to action:
SELECT d.id, d.title, d.created_at, substr(d.body, 1, 150),
(SELECT count(*) FROM logs t WHERE json_extract(t.meta, '$.depends_on') LIKE '%' || d.id || '%') as dependents
FROM logs d
WHERE d.type = 'decision' AND d.status = 'active'
AND d.created_at > '<last_audit_date>'
ORDER BY d.created_at DESC;Flag decisions with no downstream tasks or dependents.
Step 6 — Brain health
-- Entry counts by type and status
SELECT type, status, count(*) FROM logs GROUP BY type, status ORDER BY type, status;
-- Tier distribution
SELECT tier, count(*) FROM logs WHERE status = 'active' GROUP BY tier;
-- Tag frequency (top 15)
SELECT tags, count(*) FROM logs WHERE tags IS NOT NULL AND tags != '' GROUP BY tags ORDER BY count(*) DESC LIMIT 15;
-- Pillar distribution of active tasks
SELECT pillar, count(*) FROM logs WHERE type = 'task' AND status = 'active' GROUP BY pillar;Note anything out of balance: too many hot items, pillars with no active tasks, tag sprawl.
Step 7 — Docs staleness
Check if documents in cowork/ reference superseded or dropped decisions:
grep -oP '#\d+' cowork/platform/*.md cowork/notes/*.md 2>/dev/null | grep -oP '\d+' | sort -uSELECT id, title, status, superseded_by FROM logs
WHERE id IN (<extracted_ids>) AND status IN ('superseded', 'dropped');If staleness is found, list affected docs and propose updates.
Step 8 — Set focus
Run the Focus procedure (see below).
Step 9 — Log the audit
INSERT INTO logs (type, title, body, tags, importance)
VALUES ('milestone',
'Audit — <date>',
'<summary: what shipped, what was dropped/deferred, new focus items, brain health notes>',
'audit',
7);Step 10 — Update mantra
The mantra is Claude's self-authored context — what matters that CLAUDE.md doesn't say. Not a changelog or status summary. Think: what would a fresh Claude session need to know that isn't in CLAUDE.md? Patterns, non-obvious knowledge, tricky areas, current momentum, working assumptions.
- Read the current mantra (the block between the mantra marker lines in CLAUDE.md, already in your context) and recent high-signal entries:
SELECT id, type, title, substr(body, 1, 300), created_at FROM logs WHERE created_at > '<last_audit_date>' AND type IN ('decision', 'milestone', 'insight') AND importance >= 5 ORDER BY created_at DESC; - Rewrite the mantra. Ask: what did I learn this period that a fresh session would benefit from? What's non-obvious about where the project is right now? What keeps tripping me up or coming up repeatedly? What assumptions am I working under?
- Write it via the Mantra subcommand procedure.
Step 11 — Recalculate tiers
Run Recalculate tiers.
Focus subcommand
Set 2-3 focus items. These appear at the top of every session start.
Usage: focus
Procedure
- Show current focus items and their status.
- Clear existing focus:
UPDATE logs SET focus = 0 WHERE focus = 1; - Propose 2-3 focus items based on:
- What has momentum and should be finished?
- What's been stuck and needs dedicated attention?
- What's most important strategically right now?
- Present the proposed focus set and wait for user approval.
- On approval:
UPDATE logs SET focus = 1 WHERE id IN (<id1>, <id2>, <id3>); - Run Recalculate tiers.
Add subcommand
Create a new entry. Usage: add <type> where type is one of: note, decision, question, insight, task, milestone.
Procedure
- Parse the type from the argument. If missing or invalid, ask the user.
- Ask the user for:
- Title (required) — concise summary
- Body (optional) — detail, rationale, context
- Tags (optional) — comma-separated, reuse existing tags shown above
- Importance (optional) — 0-10, defaults to 5
- For task type, also ask:
- Pillar (required) — check existing pillars and suggest best fit
- Priority (optional) — integer, lower = higher priority
- Normalize tags: split by comma, trim, lowercase, sort alphabetically, deduplicate, rejoin.
- Insert:
-- For non-task types: INSERT INTO logs (type, title, body, tags, importance) VALUES ('<type>', '<title>', '<body>', '<normalized_tags>', <importance>); -- For tasks: INSERT INTO logs (type, title, body, tags, pillar, priority, importance) VALUES ('task', '<title>', '<body>', '<normalized_tags>', '<pillar>', <priority>, <importance>); - Confirm the entry was created (show id and created_at).
- Run Recalculate tiers.
Done subcommand
Close the session: make the brain match what happened, then consider the mantra and a lesson. Usage: done
Procedure
- Run the Update procedure (tasks done, decisions logged, plan progress, stale state).
- Mantra check. Did this session surface anything a fresh session would need that CLAUDE.md doesn't say — a new pattern, a non-obvious gotcha, a shifted assumption, a tricky area? If yes, rewrite the mantra via the Mantra subcommand procedure. If the work was routine, skip.
- Compound lesson. If a reusable lesson emerged, write it as an insight tagged
lesson: one sentence stating the rule, then Why and How to apply. - Tell the user in two or three lines what changed in the brain and the mantra.
Search subcommand
Full-text search across the brain using FTS5. Usage: search <query>
Procedure
- Search using FTS5 (ranked by relevance via BM25):
FTS5 query syntax:SELECT e.id, e.created_at, e.type, e.title, substr(e.body, 1, 200), e.tags, e.tier, rank FROM logs_fts f JOIN logs e ON e.id = f.rowid WHERE logs_fts MATCH '<query>' ORDER BY rank;word1 word2(implicit AND),word1 OR word2,"exact phrase",prefix*,NOT word. - If FTS5 returns no results, fall back to LIKE:
SELECT id, created_at, type, title, substr(body, 1, 200), tags, tier FROM logs WHERE title LIKE '%<query>%' OR body LIKE '%<query>%' OR tags LIKE '%<query>%' ORDER BY created_at DESC; - Present results grouped by type with enough context to be useful.
- If no results from either method, suggest related queries based on existing tags.
Resolve subcommand
Answer an open question by creating a linked decision. Usage: resolve <question_id>
Procedure
- Read the question:
If not a question, error.SELECT id, title, body, tags FROM logs WHERE id = <question_id> AND type = 'question'; - Ask the user: "What's the answer/decision?" (or infer from conversation context).
- Create the decision with
parent_idlinking back to the question:INSERT INTO logs (type, title, body, tags, parent_id) VALUES ('decision', '<decision_title>', '<rationale>', '<tags>', <question_id>); - Mark the question as resolved:
UPDATE logs SET status = 'done', body = body || char(10) || '--- Resolved by decision #' || <new_decision_id> WHERE id = <question_id>; - Confirm both entries. Run Recalculate tiers.
Depends subcommand
Mark that an entry depends on a decision. Usage: depends <id> <depends_on_id>
Procedure
- Verify both entries exist. The dependency target should be a decision.
- Update the dependent entry's meta:
IfUPDATE logs SET meta = json_set(COALESCE(meta, '{}'), '$.depends_on', json_array(<depends_on_id>)) WHERE id = <id>;depends_onalready exists in meta, append to the array rather than replacing. - Confirm. Show: "Entry #X now depends on decision #Y: <decision_title>"
Tag subcommand
Update tags on an entry. Usage: tag <id> <tags>
Procedure
- Read the current entry:
SELECT id, title, tags FROM logs WHERE id = <id>; - Normalize tags: split by comma, trim, lowercase, sort alphabetically, deduplicate, rejoin.
- Update:
UPDATE logs SET tags = '<normalized_tags>' WHERE id = <id>; - Confirm the change.
Mantra subcommand
Reflect on recent work and consider updating the mantra. The mantra is Claude's self-authored context — what matters that the rest of CLAUDE.md doesn't say: patterns, non-obvious knowledge, tricky areas, current momentum, working assumptions. It is not a changelog or a status report.
It lives in one place: CLAUDE.md, between the line that is exactly <!-- BEGIN:mantra --> and the line that is exactly <!-- END:mantra -->. It is already in your context. There is no copy in the DB or anywhere else.
Procedure
- Review conversation context and recent work. Ask: did this session surface anything a fresh session would need that isn't already written down?
- If nothing meaningful, say so and skip. Don't update for routine work.
- Rewrite the block with the Edit tool. Match the WHOLE marker lines — never the first place the marker text appears, since prose elsewhere may quote it. If the block doesn't exist, add a
## Mantrasection at the end of CLAUDE.md holding both marker lines. - Stay within about 4,000 characters. Rewrite rather than append: merge, cut what is stale, cut what CLAUDE.md or the code now says. The session-start hook flags a mantra over budget.
- Show the user the lines that changed. No confirmation needed — git history is the mantra's history, and the user can revert.
Recalculate tiers
Tiers are computed, never set by hand. Run the full two-phase recalculation from USAGE.md: the SQL phase (archived, cold, warm, focus-hot), then the plan-momentum shell phase. The session-start hook runs the same thing on every start.
Shared conventions
- The DB is the only copy. There is no markdown export. Query the DB;
/brainwith no argument is the readable view. - Recalculate tiers at the end of any subcommand that changes status, focus or importance.
- Normalize tags on every write. Split by comma, trim, lowercase, sort alphabetically, deduplicate, rejoin. Check existing tags (shown in dynamic context above) before inventing new ones.
- Set completed_at when marking tasks done. Always set
completed_at = datetime('now', 'localtime')— this drives plan momentum detection. - Decisions are permanent. Don't update a decision — create a new one that supersedes it (
supersedescolumn) and mark the old onesuperseded(superseded_bycolumn). - Questions resolve into decisions. Use
resolve <id>to create the linked decision. - Decision dependencies. Use
dependsto track what builds on what. - Sessions are auto-logged. The hooks record each session's start and end by Claude Code's session id. Nothing else is stored per session.
- Pillar consistency. Check existing pillars before creating new ones. Pillars are broad areas, not fine-grained categories.
- Priority is relative per pillar. Priority 1 in one pillar has no relation to priority 1 in another.
- Meta is structured. Use
json_set/json_extract. Common keys:plan_id,from_plan,blocked_by,depends_on. plan_idis a zero-padded string. Always'003', never bare3.
Global rules
- No permission needed — Execute immediately without asking.
- Brainstorm before writing — For Add, present what you'll insert and wait for confirmation.
- Keep it conversational — Review, Audit, and Search results should be narrated, not raw SQL output.
- Opinionated but collaborative — During Audit, propose what to drop, defer, and focus on. Hold it loosely — the user makes the final call.
- Don't auto-drop — Propose changes. Wait for confirmation before executing status/tier/focus updates.
Project overrides
If .claude/kit.json has a rules."brain" entry, read it and apply it as an additional
instruction for this skill. Absent file or key means no overrides — that is the normal case.
jq -r '.rules."brain" // empty' .claude/kit.json 2>/dev/nullDoes it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

