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:

• Scans all .md files

• Chunks content (by timestamp blocks or headers)

• Generates embeddings for new/changed chunks

• 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