Skip to main content
smolbren is a single binary with no runtime dependencies beyond its own index files. Once it’s installed you register a vault, run one command to build the index, and immediately have BM25 full-text search and Cypher graph queries over your notes.
All smolbren output is single-line JSON written to stdout. Pipe to jq for human-readable formatting: smolbren search "rust async" | jq.
1

Install

smolbren is distributed as a Rust crate. You need the Rust toolchain (edition 2024, rustc 1.85+) and protoc on your PATH before running cargo install — see the Installation guide for full prerequisites.
cargo install smolbren
Confirm the binary is available:
smolbren --version
2

Register your vault

Tell smolbren where your Markdown files live by registering the directory as a named vault. The --default flag makes it the vault used by all subsequent commands. If this is the first vault you register it becomes the default automatically.
smolbren vault add personal ~/path/to/vault --default
You’ll get a JSON confirmation:
{"name":"personal","path":"/home/you/path/to/vault","default":true}
List all registered vaults at any time:
smolbren vault list
3

Build the index

Index your vault. The first run scans every .md file; subsequent runs are incremental — smolbren compares modification times, file sizes, and content hashes to skip unchanged files.
smolbren index
smolbren prints an IndexStats object when it finishes:
{"scanned":9,"unchanged":0,"added":9,"updated":0,"removed":0,"edges":15,"unresolved_edges":3,"duration_ms":42}
FieldDescription
scannedTotal .md files found in the vault
unchangedFiles skipped because mtime/size and content hash matched
addedNew notes inserted into the index
updatedExisting notes whose content changed
removedNotes deleted from disk and removed from the index
edgesTotal resolved edges in the graph after indexing
unresolved_edgesEdges whose wikilink target couldn’t be found
duration_msWall-clock time for the full index run
To rebuild the index from scratch (e.g. after bulk renames):
smolbren index --full
4

Search and query

Full-text search with BM25 — results are ranked by relevance score:
smolbren search "context engineering"

[{"id":"blogs/context-engineering","path":"blogs/context-engineering.md","type":"blog","title":"Context engineering","score":0.87}]
Narrow results to a specific note type with --type:
smolbren search "context engineering" --type blog --limit 5
Graph queries with Cypher — traverse typed relationships between notes:
smolbren query "MATCH (n:blog) RETURN n.title LIMIT 5"

{"columns":["n.title"],"rows":[{"n.title":"Context engineering"},{"n.title":"Context development lifecycle"},{"n.title":"Context platform engineering"}]}
Follow edges between node types:
smolbren query "MATCH (b:blog)-[:mentions]->(n:Note) RETURN b.id, n.id"
Fetch outgoing and incoming links for a specific note:
smolbren links blogs/context-engineering --type mentions
smolbren backlinks projects/prism
Inspect the discovered ontology — all node types and edge types with counts:
smolbren types   # [{"type":"blog","count":3}, {"type":"project","count":2}, ...]
smolbren edges   # [{"edge_type":"mentions","count":6}, ...]

​
Next steps

Installation

Full prerequisites, protoc setup, and platform-specific install instructions.

CLI Reference

Every subcommand, flag, exit code, and JSON output shape documented in detail.