How do I install the Brain skill?

Run npx skillmds@latest add hjewkes/brain in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Brain safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Brain?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Brain free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

hjewkes (@hjewkes) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Brain by hjewkes — Agent Skill

Name: Brain
Author: hjewkes

Brain

Search and manage your second brain knowledge base. Use when the user asks about their notes, wants to find information, or needs to add/organize knowledge. Also use proactively before research, brainstorming, or planning tasks to pull relevant prior work, and after completing research or making decisions to deposit findings.

hjewkes bc3fc3c 4.0 KB Updated Sep 17, 2026

File contents

Brain — Knowledge Management

A CLI for managing a developer second brain with hybrid BM25 + vector search over markdown notes.

When to Use

User asks "what do I know about X" or "find my notes on Y"
User wants to save something to their knowledge base
Before starting work on a topic (context pull)
After completing research or making a decision (deposit)
User asks about stale or outdated notes

Commands

All commands are run via brain (ensure it's on PATH or use the full path to the CLI). Use --json flag on all commands when processing output programmatically.

Search

brain search "<query>" [options]
  --json                    JSON output
  --limit <n>               Max results (default 10)
  --min-score <score>       Minimum relevance 0-1 (use 0.4 for broad queries)
  --category <cat>          Filter by project category
  --tier <tier>             slow|fast
  --tags <tags>             Comma-separated tag filter
  --confidence <level>      high|medium|low|speculative
  --since <date>            Notes modified after YYYY-MM-DD
  --expand                  Include graph-connected notes

Add Notes

brain add <file> [options]
  --title <title>               Note title
  --type <type>                 note|decision|pattern|research|meeting|session-log|guide
  --tier <tier>                 slow|fast (default: slow)
  --tags <tags>                 Comma-separated tags
  --summary <text>              One-line summary for search excerpts
  --confidence <level>          high|medium|low|speculative
  --status <status>             current|outdated|deprecated|draft
  --category <cat>              Project category
  --related <ids>               Comma-separated related note IDs
  --review-interval <interval>  e.g. 30d, 60d, 90d, 180d
  --created <date>              YYYY-MM-DD (defaults to today)

Other

Command	Purpose
`brain status --json`	Database stats (note count, embeddings, types)
`brain stale --json`	Notes past their review interval
`brain graph <note-id> --json`	Show note's connections
`brain index`	Rebuild search index (slow — only when asked)
`brain template <type>`	Generate frontmatter template for a note type

Quality Rules

When adding notes:

ALWAYS include --category, --tags (2-3 minimum), and --summary
Include --related when the note references existing notes
Set --confidence to signal how proven the content is
Set --review-interval by type: decisions=180d, research=90d, patterns=60d, guides=90d

When searching:

Use --category to scope queries to the relevant project
Use --min-score 0.4 to filter noise on broad queries
Use --expand when you need the full context graph around a result

Workflow Patterns

Context pull — before planning or brainstorming:

brain search "topic" --category mobile --min-score 0.4 --expand --json

Research deposit — after completing research:

brain add research.md --title "Finding title" --type research \
  --category voltra-sdk --tags "ble,protocol" --confidence medium \
  --summary "One-line finding" --review-interval 90d

Decision record — after an architectural decision:

brain add decision.md --title "Use X over Y" --type decision \
  --category mobile --tags "architecture,state" --confidence high \
  --summary "Chose X because..." --review-interval 180d --related existing-note-id

Rules

Always use --json when you need to parse output
Search before claiming information isn't in the knowledge base
Do NOT run brain index unless the user explicitly asks — it processes all files and is slow
Present search results with score, file path, and excerpt

---name: braindescription: Search and manage your second brain knowledge base. Use when the user asks about their notes, wants to find information, or needs to add/organize knowledge. Also use proactively before research, brainstorming, or planning tasks to pull relevant prior work, and after completing research or making decisions to deposit findings.---# Brain — Knowledge ManagementA CLI for managing a developer second brain with hybrid BM25 + vector search over markdown notes.## When to Use- User asks "what do I know about X" or "find my notes on Y"- User wants to save something to their knowledge base- Before starting work on a topic (context pull)- After completing research or making a decision (deposit)- User asks about stale or outdated notes## CommandsAll commands are run via `brain` (ensure it's on PATH or use the full path to the CLI).Use `--json` flag on all commands when processing output programmatically.### Search```bashbrain search "<query>" [options] --json JSON output --limit <n> Max results (default 10) --min-score <score> Minimum relevance 0-1 (use 0.4 for broad queries) --category <cat> Filter by project category --tier <tier> slow|fast --tags <tags> Comma-separated tag filter --confidence <level> high|medium|low|speculative --since <date> Notes modified after YYYY-MM-DD --expand Include graph-connected notes```### Add Notes```bashbrain add <file> [options] --title <title> Note title --type <type> note|decision|pattern|research|meeting|session-log|guide --tier <tier> slow|fast (default: slow) --tags <tags> Comma-separated tags --summary <text> One-line summary for search excerpts --confidence <level> high|medium|low|speculative --status <status> current|outdated|deprecated|draft --category <cat> Project category --related <ids> Comma-separated related note IDs --review-interval <interval> e.g. 30d, 60d, 90d, 180d --created <date> YYYY-MM-DD (defaults to today)```### Other| Command | Purpose ||---------|---------|| `brain status --json` | Database stats (note count, embeddings, types) || `brain stale --json` | Notes past their review interval || `brain graph <note-id> --json` | Show note's connections || `brain index` | Rebuild search index (slow — only when asked) || `brain template <type>` | Generate frontmatter template for a note type |## Quality RulesWhen **adding** notes:- ALWAYS include `--category`, `--tags` (2-3 minimum), and `--summary`- Include `--related` when the note references existing notes- Set `--confidence` to signal how proven the content is- Set `--review-interval` by type: decisions=180d, research=90d, patterns=60d, guides=90dWhen **searching**:- Use `--category` to scope queries to the relevant project- Use `--min-score 0.4` to filter noise on broad queries- Use `--expand` when you need the full context graph around a result## Workflow Patterns**Context pull** — before planning or brainstorming:```bashbrain search "topic" --category mobile --min-score 0.4 --expand --json```**Research deposit** — after completing research:```bashbrain add research.md --title "Finding title" --type research \ --category voltra-sdk --tags "ble,protocol" --confidence medium \ --summary "One-line finding" --review-interval 90d```**Decision record** — after an architectural decision:```bashbrain add decision.md --title "Use X over Y" --type decision \ --category mobile --tags "architecture,state" --confidence high \ --summary "Chose X because..." --review-interval 180d --related existing-note-id```## Rules- Always use `--json` when you need to parse output- Search before claiming information isn't in the knowledge base- Do NOT run `brain index` unless the user explicitly asks — it processes all files and is slow- Present search results with score, file path, and excerpt

Frequently asked questions