second_brain v1.0.0

name: "second_brain" description: "Build and maintain a personal knowledge base (second brain) an agent can actually use: fast capture, a folder schema (PARA or Johnny Decimal), atomic linked notes, multi-tool retrieval patterns, and a vault linter that finds broken links, orphans, and staleness. Triggers when an agent needs to keep durable knowledge across sessions, wants a better way to organize notes than random files, or needs to query a Markdown vault reliably."

Second Brain

Purpose

A second brain is an external, trusted system for the things worth keeping: ideas, decisions, procedures, references. Humans forget; agents lose context between runs. The vault (plain Markdown files on disk), not the model, is the source of truth. This skill gives an agent the full loop: capture -> organize -> query -> lint, in any tool, with no vendor lock-in.

Workflow

1. Capture

Fast capture beats perfect capture. Every capture goes to 00 Inbox/ with minimal friction:

• One note per idea. If you caught two ideas, write two notes.
• Use assets/note-template.md: title, tags, a 2-sentence core claim, why it matters, source.
• Capture first, file later. Filing during capture is how captures get skipped.

Triggers that should produce a capture: a hard-won debugging insight, a decision with reasons, a preference or constraint learned mid-task, a summary at session end.

2. Organize

Pick ONE schema and stick with it. Both are in references/schemas.md.

• PARA (default): 00 Inbox, 10 Projects, 20 Areas, 30 Resources, 40 Archive. File by actionability: where will this note be useful the soonest? Projects are active goals with deadlines; Areas are ongoing responsibilities; Resources are reference; Archive holds retired items.
• Johnny Decimal: numeric areas (10-19, 20-29, ...), at most 10 areas and 10 categories each, every note carries a stable ID (31.01-some-note.md). Pick this when you want navigable, machine-sortable addresses.

Scaffold a new vault with the init CLI:

bash
python3 bin/second-brain-init.py ~/brain --schema para   # or --schema jd

Filing rule (Forte's, paraphrased): there is no perfect place for a note, so place it where it is actionable and move on. Weekly: empty the inbox, one note at a time.

3. Query

Retrieval is a pipeline, not one tool. Cheap exact search first, semantic search for the rest. See references/retrieval-patterns.md for the full pattern catalog:

1. Exact text: rg -l -i "phrase" ~/brain (ripgrep is instant and exact).
2. Tag/frontmatter search: grep tags: lines or rg "tags:.*project".
3. Wikilink traversal: from a hit note, follow [[links]] one hop for connected context.
4. Semantic search: embed the vault once, search by meaning when the wording is unknown. Any embedding store works; the pattern is index-once, query-many.

Always cite which note an answer came from ([[note title]] or path). If nothing in the vault answers it, say so plainly. Do not invent knowledge the vault does not have.

4. Lint

Run the linter on a schedule or after bulk writes:

bash
python3 bin/second-brain-lint.py ~/brain          # human summary, exit 1 on issues
python3 bin/second-brain-lint.py ~/brain --json   # machine-readable report

It checks for: broken [[wikilinks]] and markdown links, orphaned notes with no inbound links, missing frontmatter, oversized notes that should be split (atomic = one idea), stale notes untouched for 180 days (tune with --stale-days), and duplicate note names/titles. Full check list and fix guidance: references/lint.md.

Output Contract

• A vault layout on disk (Markdown only), created or repaired.
• Notes that are atomic (one idea), titled, tagged, and linked to at least one hub note.
• Query answers that cite their source note.
• A lint report with a count per check; the vault is "clean" when the linter exits 0.

Operating Rules

1. The vault is plain Markdown. No proprietary format, no cloud dependency. Any agent or tool must be able to read and write it.
2. One idea per note. A note longer than ~500 lines gets split; a note with no links gets linked or deleted.
3. Capture is cheap, filing is weekly. Never let the perfect folder structure block a capture.
4. Queries never hallucinate from the vault. "Not in the vault" is a valid, honest answer.
5. Lint before bulk imports. Ten broken links imported today are a hundred next month.
6. Never commit a skill, credential, or secret into the vault. Knowledge goes in; secrets stay in their stores.