Brain Dump Assistant

Brain Dump Assistant

A CLI for externalizing your working memory - capture ideas, projects, features, todos, and questions without the overhead of complex tools.

Why?

Your brain is for having ideas, not holding them. But sticky notes get lost, notepads pile up unread, and tools like Asana are overkill for personal capture.

brain-dump solves this by providing:

• Zero-friction capture - dump thoughts in seconds
• Structured retrieval - find anything with search and filters
• AI-assisted triage - agents help you organize, prioritize, and act

Agent Mindset

When assisting users with their brain dump:

1. Capture first, organize later - Never block on classification during fast capture. Get the thought out, refine later.

2. Proactive triage - Regularly surface raw entries needing processing. Don't let the inbox grow stale.

3. Connect the dots - Link related entries, identify patterns, consolidate ideas into projects.

4. Reduce cognitive load - Present summaries and prioritized lists, not exhaustive dumps.

5. Preserve context - Include enough detail for future recall. A cryptic note is useless later.

6. Respect simplicity - Simple thoughts don't need tags, priorities, and parents. Don't over-engineer.

Operating Modes

Detect user intent and respond appropriately:

Quick Start

Pre-flight Check

Before operations, verify the tool is ready:

brain --version   # Verify installed
brain stats       # Quick health check

If brain: command not found, the user needs to install: npm install -g brain-dump

Command Reference

Capture Commands

brain add <content>

Quick capture of a thought.

brain add "What if we used a graph database?"
brain add "Need to review the API design" --type todo --priority 1
brain add "Meeting notes from standup" --type note --tags "meetings,weekly"
brain add --type project --title "Website Redesign" "Complete overhaul of the marketing site..."

Options:

• --type <type>: idea, project, feature, todo, question, reference, note (default: idea)
• --title <title>: Short title (auto-extracted from first line if not provided)
• --priority <1|2|3>: 1=high, 2=medium, 3=low
• --tags <tags>: Comma-separated tags
• --parent <id>: Parent entry ID
• --json: JSON output

brain todo <content>

Shorthand for adding a todo.

brain todo "Review PR #42"
# Equivalent to: brain add "Review PR #42" --type todo

brain question <content>

Shorthand for adding a question.

brain question "Should we migrate to TypeScript?"
# Equivalent to: brain add "..." --type question

Query Commands

brain list

List entries with filtering.

brain list                              # Active + raw (default)
brain list --all                        # All except archived
brain list --type todo                  # Only todos
brain list --status raw                 # Needs triage
brain list --priority 1                 # High priority only
brain list --tags work,urgent           # Has ALL specified tags
brain list --since 7d                   # Created in last 7 days
brain list --json                       # JSON output for parsing

Options:

• --type <type>: Filter by entry type
• --status <status>: raw, active, someday, done, archived (default: raw,active)
• --tags <tags>: Comma-separated, AND logic
• --priority <1|2|3>: Filter by priority
• --parent <id>: Children of specific entry
• --orphans: Only entries without parent
• --since <duration>: e.g., 7d, 24h, 2w
• --all: All statuses except archived
• --done: Include done entries
• --archived: Show only archived
• --limit <n>: Max entries (default: 50)
• --sort <field>: created, updated, priority
• --reverse: Reverse sort order
• --json: JSON output

brain show <id>

Show full entry details.

brain show a1b2c3d4
brain show a1b2c3d4 --with-children
brain show a1b2c3d4 --with-related
brain show a1b2c3d4 --json

brain search <query>

Full-text search across content and titles.

brain search "database"
brain search "meeting" --type note --since 30d
brain search "API" --json

Modify Commands

brain edit <id>

Edit entry content.

brain edit a1b2c3d4                          # Opens $EDITOR
brain edit a1b2c3d4 --content "New text"     # Non-interactive
brain edit a1b2c3d4 --append "Follow-up"     # Add to existing
brain edit a1b2c3d4 --title "New title"

brain set <id>

Update entry metadata.

brain set a1b2c3d4 --type project
brain set a1b2c3d4 --status active
brain set a1b2c3d4 --priority 1
brain set a1b2c3d4 --tags "work,Q1"
brain set a1b2c3d4 --add-tags "important"
brain set a1b2c3d4 --remove-tags "draft"
brain set a1b2c3d4 --clear-priority
brain set a1b2c3d4 --parent b2c3d4e5

brain link <id1> <id2>

Create relationships between entries.

brain link a1b2c3d4 b2c3d4e5                # Add to related
brain link a1b2c3d4 b2c3d4e5 --as-parent    # Set hierarchy
brain link a1b2c3d4 b2c3d4e5 --unlink       # Remove relationship

Bulk Commands

brain done <ids...>

Mark entries as done.

brain done a1b2c3d4
brain done a1b2c3d4 b2c3d4e5 c3d4e5f6       # Multiple
brain done --type todo --tags "sprint-1"     # By filter
brain done --dry-run --type todo             # Preview first

brain archive <ids...>

Archive entries (hides from default view).

brain archive a1b2c3d4
brain archive --status done --since 30d      # Old completed items
brain archive --dry-run --status done        # Preview

brain delete <ids...>

Delete entries (logged for undo).

brain delete a1b2c3d4
brain delete a1b2c3d4 b2c3d4e5 --confirm
brain delete --status archived --since 90d   # Permanent cleanup
brain delete --dry-run --type reference      # Preview

Safety:

• All deletions logged to enable restore

• 10 entries requires --confirm or --force

• Entries with children require --force

brain restore

Restore deleted entries.

brain restore --last 1                       # Most recent
brain restore --last 5                       # Last 5
brain restore --ids a1b2c3d4,b2c3d4e5        # Specific IDs
brain restore --list                         # Show deletion log

Maintenance Commands

brain stats

Overview statistics.

brain stats
brain stats --json

brain export

Export entries.

brain export                                 # All to stdout
brain export --file backup.json              # To file
brain export --type todo --status active     # Filtered

brain import <file>

Import entries.

brain import backup.json
brain import backup.json --dry-run
brain import backup.json --merge             # Update existing + add new
brain import backup.json --skip-existing     # Only add new

Workflow Patterns

Daily Review

Run this each morning to get oriented:

1. Health check: brain stats
2. Triage raw entries: brain list --status raw
3. Focus list: brain list --priority 1 --type todo
4. Help user decide what to work on first

Weekly Review

Run this weekly to maintain hygiene:

1. Celebrate: brain list --done --since 7d - show what was accomplished
2. Check stalled: brain list --status active --sort updated - find items not touched
3. Review projects: brain list --type project - are they progressing?
4. Clean up: brain archive --status done --since 7d - archive completed items

Triage Workflow

When user has many raw entries:

1. Fetch: brain list --status raw --json
2. For each entry, determine:
   • Type (idea, todo, project, question, reference, note)
   • Priority (1, 2, 3, or none)
   • Tags (infer from content)
   • Parent (if belongs to existing project/feature)
3. Update: brain set <id> --type todo --priority 1 --tags "work"
4. If entry is actually multiple items, split and re-capture
5. Mark refined: brain set <id> --status active

Capture Mode

When user is dumping thoughts rapidly:

1. Just capture with brain add "..." - don't interrupt for classification
2. Use default type (idea) and status (raw)
3. After the brain dump session, offer to triage

Classification Rules

Type Detection Heuristics

Priority Assignment

Safety Rules

Non-negotiable constraints:

1. Never auto-delete - Always show what will be deleted and confirm
2. Preserve context - Don't summarize away important details during capture
3. Log before delete - All deletions are recoverable via brain restore
4. Confirm bulk operations - Operations affecting >10 entries require confirmation
5. Don't over-organize - Simple thoughts don't need tags, priorities, and parents

Two-Step Pattern for Bulk Operations

Critical for preventing accidental mass changes:

1. Preview: brain delete --status archived --since 90d --dry-run
2. Confirm: Show user what will be affected, get explicit approval
3. Execute: brain delete --ids "<specific-ids>" --confirm

Principle: Filters are for DISCOVERY, IDs are for EXECUTION.

Common Request Patterns

Troubleshooting

Testing / Evaluation Scenarios

JSON Output Schemas

Entry Object

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": "The full text of the entry",
  "title": "Short title (optional)",
  "type": "idea|project|feature|todo|question|reference|note",
  "status": "raw|active|someday|done|archived",
  "priority": 1|2|3|null,
  "tags": ["tag1", "tag2"],
  "parent": "parent-id|null",
  "related": ["id1", "id2"],
  "createdAt": "2026-01-05T08:30:00.000Z",
  "updatedAt": "2026-01-05T08:30:00.000Z",
  "source": "cli|agent|import"
}

List Response

{
  "success": true,
  "entries": [...],
  "total": 47,
  "returned": 12,
  "query": {
    "status": ["raw", "active"],
    "limit": 50
  }
}

Error Response

{
  "success": false,
  "error": "Entry not found: a1b2c3d4",
  "code": "ENTRY_NOT_FOUND"
}

Remember

• The goal is to externalize working memory, not build a perfect system
• Capture is king - never block a brain dump
• Structure serves retrieval, not organizational perfection
• The best system is one that gets used