smolbren search — BM25 full-text search over your vault

The search command runs BM25 full-text search over the titles and bodies of all indexed notes and returns a ranked list of results. BM25 scoring accounts for term frequency, inverse document frequency, and document length, so results are ordered by relevance rather than recency or alphabetical position.

Synopsis

smolbren search <query> [--type <type>] [--path <prefix>] [--limit <n>] [--hybrid]

Arguments and flags

string

required

The search query. Multi-word queries should be quoted in your shell. Terms are matched against note titles and body text.

string

Restrict results to vault-relative paths beginning with this prefix. Use --path Notes/ to search curated notes without mixing in Journal/, Inbox/, or other source material. The same filter applies to both sides of hybrid search.

string

Restrict results to notes whose frontmatter type field exactly matches this value. For example, --type blog returns only notes with type: blog in their frontmatter. Case-sensitive. Use smolbren types to discover what type values exist in your vault.

integer

default:"10"

Maximum number of results to return, ordered by descending BM25 score. Must be a positive integer. Increasing this value does not affect search quality, only how many results are returned.

boolean

Fuse BM25 with vector similarity search using Reciprocal Rank Fusion. Requires embeddings — run smolbren embed first (exit code 6 otherwise). See Hybrid search below.

Output

Returns a JSON array of result objects, sorted by descending score. An empty array is returned when no notes match.

Field	Type	Description
`id`	string	Vault-relative note ID (path without `.md` extension), e.g. `blogs/context-engineering`
`path`	string	Vault-relative file path including the `.md` extension, e.g. `blogs/context-engineering.md`
`type`	string \| null	The note’s frontmatter `type` value, or `null` if the note has no type
`title`	string	The note’s title, derived from the first `# Heading` or the filename
`score`	number	BM25 relevance score. Higher is more relevant. Scores are not normalised to a fixed range and are only meaningful relative to other results in the same query
`snippet`	string	A UTF-8-safe body excerpt around a matching query term (about 280 bytes)

Examples

Basic search across all note types

smolbren search "context engineering"

[
  {
    "id": "blogs/context-engineering",
    "path": "blogs/context-engineering.md",
    "type": "blog",
    "title": "Context engineering",
    "score": 12.487,
    "snippet": "# Context engineering\n\nDraft thesis: prompt engineering changes the instruction…"
  },
  {
    "id": "blogs/context-platform-engineering",
    "path": "blogs/context-platform-engineering.md",
    "type": "blog",
    "title": "Context platform engineering",
    "score": 9.031,
    "snippet": "# Context platform engineering\n\nThe platform layer agents talk to…"
  }
]

Filter by note type

smolbren search "context engineering" --type blog --limit 3

[
  {
    "id": "blogs/context-engineering",
    "path": "blogs/context-engineering.md",
    "type": "blog",
    "title": "Context engineering",
    "score": 12.487,
    "snippet": "# Context engineering\n\nDraft thesis: prompt engineering changes the instruction…"
  }
]

Restrict search to curated notes

smolbren search "context" --path Notes/

Hybrid search

search --hybrid runs the query through both backends — BM25 keyword matching and vector similarity over embedded chunks (see similar) — and fuses the two rankings with Reciprocal Rank Fusion (k=60): each note scores Σ 1/(60 + rank) across the lists it appears in, so notes ranked well by both backends rise to the top. This is the strongest default for agent retrieval: BM25 contributes keyword precision, embeddings contribute semantic recall. The output shape is a superset of plain search:

Extra field	Type	Description
`score`	number	The RRF fusion score (replaces the BM25 score in this mode)
`bm25_score`	number \| null	BM25 component, `null` when the note matched only by similarity
`similarity`	number \| null	Best-chunk cosine similarity, `null` when the note matched only by keywords
`snippet`	string \| null	Best-matching chunk text (~280 chars), when the vector side matched

smolbren search "retrieval quality" --hybrid --limit 3

[
  {
    "id": "Journal/2026, June 04",
    "path": "Journal/2026, June 04.md",
    "type": "journal",
    "title": "2026, June 04",
    "score": 0.0328,
    "bm25_score": 3.82,
    "similarity": 0.39,
    "snippet": "Long day. Notes on retrieval quality and why hybrid search beats either backend alone."
  },
  {
    "id": "blogs/context-engineering",
    "path": "blogs/context-engineering.md",
    "type": "blog",
    "title": "Context engineering",
    "score": 0.0161,
    "bm25_score": null,
    "similarity": 0.18,
    "snippet": "# Context engineering\n\nDraft thesis: prompt engineering changes the instruction…"
  }
]

The vault must be indexed before running search. If the index is missing, smolbren exits with code 5 and prints {"error":"index missing for vault '...' — run smolbren index first","code":"index_missing"} to stderr. Run smolbren index once after registering a vault, and again whenever your notes change. --hybrid additionally requires smolbren embed (exit code 6 when embeddings are missing).

Commands

Output & Errors

smolbren search — BM25 full-text search over your vault

Synopsis

Arguments and flags

Output

Examples

Hybrid search

​Synopsis

​Arguments and flags

​Output

​Examples

​Hybrid search

Synopsis

Arguments and flags

Output

Examples

Hybrid search