brain-expert

name	brain-expert
description	Personal knowledge management expert for the brain CLI. Use when users want to capture notes, search their knowledge base, or manage their second brain.

Brain CLI Expert

You are an expert on the brain CLI - a personal knowledge management tool with hierarchical Markdown files, SQLite storage, and semantic search.

Quick Reference

Command	Description
brain init [path]	Initialize brain directory
brain add "text"	Add timestamped note to today's file
brain add -f file.md "text"	Add to specific file
brain add --ref /path "text"	Add note referencing external file
brain new "path/name"	Create new entry, opens in editor
brain list	Show recent entries
brain list --tree	Show directory structure
brain show <path>	Display entry content
brain edit <path>	Open entry in editor
brain delete <path>	Delete entry (file + database)
brain rm <path>	Alias for delete
brain sync	Sync files to database
brain sync --force	Re-embed everything
brain search "query"	Semantic search (default)
brain search --exact "term"	Full-text search (FTS5)
brain config show	Display configuration
brain todo add "text"	Create a new todo
brain todo list	List open todos
brain todo done <id>	Mark todo as complete
brain todo cancel <id>	Cancel a todo
brain todo edit <id>	Edit todo in editor
brain todo rm <id>	Delete todo permanently
brain cron install	Install auto-sync cron job
brain cron status	Check auto-sync status
brain cron remove	Remove auto-sync cron job

File Structure

Brain organizes files hierarchically:

~/Documents/brain/
├── 2026/
│   └── 01/
│       ├── 22.md          # Daily journal (timestamped entries)
│       └── 23.md
├── projects/
│   ├── acme.md            # Named entries (by topic)
│   └── startup-ideas.md
├── notes/
│   └── meeting-notes.md
└── .brain.db              # SQLite database (gitignored)

Entry Formats

Daily Files (YYYY/MM/DD.md)

Auto-created when using brain add:

[2026-01-23-143022]
First thought of the day

[2026-01-23-153045]
Another thought with more context

Named Files

Created with brain new:

# Project Title

Content organized however you like.
Can include todos: - [ ] Task here

Search

Semantic Search (default)

Uses OpenAI embeddings for meaning-based search:

brain search "database optimization strategies"

Returns results ranked by semantic similarity.

Full-Text Search (--exact)

Uses SQLite FTS5 for literal text matching:

brain search --exact "PostgreSQL"

Sync Required

Before searching, ensure database is synced:

brain sync

The sync process:

1. Scans all .md files
2. Chunks content (by timestamp blocks or headers)
3. Generates embeddings for new/changed chunks
4. Updates FTS5 index

Use brain sync --force to re-embed everything.

Configuration

Config stored at ~/.brain.json:

{
  "path": "/Users/taras/Documents/brain",
  "editor": "code",
  "embeddingModel": "text-embedding-3-small"
}

Manage with:

• brain config show - view config
• brain config set editor vim - update value

Common Workflows

Quick Capture

brain add "Idea: could use SQLite for local caching"

Reference External Code

brain add --ref ./src/api/auth.ts "Need to add rate limiting here"

Find Related Notes

brain search "authentication patterns"

Create Project Notes

brain new "projects/new-feature"
# Opens editor with # New Feature header

Delete Entries

brain delete 2026/01/22           # Delete with confirmation
brain rm notes/old-project        # Alias, same behavior
brain rm --force notes/temp       # Skip confirmation
brain rm --db-only notes/draft    # Keep file, remove from database

Todo Management

# Add todos with options
brain todo add "Review PR"
brain todo add -p myproject "Ship feature"
brain todo add -d tomorrow "Deploy to prod"
brain todo add -p work -d "next week" "Plan sprint"

# List and filter
brain todo list                    # Open todos
brain todo list --all              # Include done/cancelled
brain todo list -p myproject       # Filter by project

# Complete and manage
brain todo done 1 2 3              # Mark multiple as done
brain todo cancel 1                # Cancel a todo
brain todo edit 1                  # Edit in $EDITOR
brain todo rm 1                    # Delete permanently

Automatic Sync

# Set up background sync (runs every N minutes)
brain cron install                 # Default: 5 minutes
brain cron install --interval 15   # Custom interval

# Check and manage
brain cron status                  # "Active (every 5 minutes)"
brain cron remove                  # Stop auto-sync

Environment

• OPENAI_API_KEY: Required for semantic search embeddings
• EDITOR: Fallback if config.editor not set

Troubleshooting

Issue	Solution
Search returns nothing	Run brain sync first
Embedding errors	Check OPENAI_API_KEY is set
Command not found	Run bun link in brain directory
Wrong brain path	Check brain config show