brief

Usage

Database Location

Default path:

~/.brief/brief.db

Environment override:

export BRIEF_DB=/path/to/brief.db

Flag override:

brief --db /path/to/brief.db find --recent

Precedence is --db > BRIEF_DB > ~/.brief/brief.db.

The database and missing parent directory are created automatically on first use.

Basic Flow

Save an entry:

brief save --title "First note" --category note --tag brief "brief is working on this machine"
saved: [1] First note

Find it:

brief find "brief is working"

Fetch by ID:

brief find --id 1

Commands

find

brief find "hooks in VS Code"

save

brief save --title "Copilot hooks note" --tag hooks --tag vscode "UserPromptSubmit runs before the agent responds."
saved: [<id>] Copilot hooks note

edit

brief edit 12 --title "Copilot hooks overview" --add-tag automation

Flags: --title, --category, --language, --tag (replace all), --add-tag, --remove-tag, --unarchive, --stdin.

archive

brief archive 12

remove

brief remove 12 --force

recall

brief recall

Launches the interactive TUI browser. Requires an interactive terminal.

tag

brief tag list
brief tag rename <old> <new>
brief tag delete <tag>

category

brief category list

config

brief config set default_limit 20

Query Modes

brief find supports exactly one of these modes:

brief find "<query>"
brief find --id=<id>
brief find --recent
brief find --recent-updates

Filter flags such as --category, --tag, and --language are valid with <query>, --recent, and --recent-updates.

Additional flags valid with <query>, --recent, and --recent-updates:

They are not valid with --id.

Content Input

save accepts either positional content or --stdin:

printf 'stdin content\n' | brief save --title "stdin example" --stdin
saved: [1] stdin example

edit also accepts either positional content or --stdin:

printf 'updated content\n' | brief edit 12 --stdin

In both cases, positional content and --stdin are mutually exclusive.

Sources

brief sources indexes local directories and repos into a searchable corpus.

# Add a directory
brief sources add ~/projects/myrepo

# Search indexed content
brief sources find "how does the database get opened"

# Scope search to a specific source
brief sources find "http handler" --source ~/projects/myrepo

# List all indexed sources
brief sources list

Embeddings & Hybrid Search

brief supports optional vector embeddings via Ollama. When a model is configured, brief find runs hybrid search (cosine similarity + FTS5 BM25 boost) and brief save stores a vector alongside the entry. Without a model, brief find, brief save, and brief sources work in FTS5-only mode.

Prerequisites

  1. Install Ollama: https://ollama.com/download
  2. Pull a model:
ollama pull nomic-embed-text
  1. Confirm Ollama is running:
ollama ps

Environment variables

Variable Purpose Default
BRIEF_EMBED_MODEL Embedding model name (none — embedding disabled)
BRIEF_EMBED_URL Ollama base URL Auto-detect common local endpoints

The hidden flags --embed-model and --embed-url take precedence over environment variables on commands that support them.

If BRIEF_EMBED_URL is unset, brief probes common local Ollama endpoints, including WSL2 gateway routing when applicable, and uses the first reachable endpoint. If none respond, it falls back to http://localhost:11434, and embedding may still degrade to FTS5-only.

Save an entry with an embedding

export BRIEF_EMBED_MODEL=nomic-embed-text
brief save --title "My note" --category note "Content here"
saved: [1] My note

When a stored embedding model is detected, brief find automatically runs hybrid search — no flag required:

brief find "query about my topic"

Back-fill embeddings for existing entries

brief embed is a hidden command retained for backfill operations:

# Back-fill all entries that don't yet have a vector
brief embed --all --embed-model nomic-embed-text

# Back-fill a single entry
brief embed --id 42 --embed-model nomic-embed-text

Degradation behaviour