A portable brain for all us mere mortals trying to create a second brain.
smolbren
turns a folder of markdown files — an Obsidian vault, a notes directory, anything with frontmatter — into a local, queryable knowledge graph with full-text search on top. It doesn't impose a schema; it discovers one from the frontmatter you already write, then lets you (or your agent) query it with Cypher and BM25.
Ontology-first. Tools likeqmd
approach vault search embeddings-first. smolbren instead starts from the structure your notes already encode: the frontmattertype
key becomes a node type, and every frontmatter key holding[[wikilinks]]
becomes a typed edge in a graph. Embeddings come on top —smolbren embed
runs a local model (EmbeddingGemma-300M via ONNX, nothing leaves your machine) for semanticsimilar
search and BM25+vectorsearch --hybrid
.Built for agents. Every command prints single-line JSON to stdout, errors are JSON on stderr with stable exit codes, and nothing is interactive. Humans pipe tojq
; agents parse directly — there's aready-made skilltoo.Fully local and fast. Storage isLanceon disk under~/.smolbren/
. Indexing is incremental (blake3 content hashes, mtime+size fast path) and parses files in parallel across all cores.
Everything starts from a note like this:
---
type: book
status: reading
started: 2026-06-01
author: "[[people/ursula-k-le-guin]]"
themes: ["[[topics/anarchism]]", "[[topics/utopia]]"]
related: ["[[books/the-left-hand-of-darkness]]"]
---
An ambiguous utopia: two worlds, one wall, and the physicist who tries to
unbuild it.
From each file, smolbren index
derives an id (the vault-relative path without
.md
— books/the-dispossessed
, the same shape wikilink targets use), a type
(book
, which becomes a Cypher node label alongside the catch-all Note
), a
title (the first # heading
), and edges — every frontmatter key whose values
contain wikilinks becomes a relationship type (here author
, themes
, and
related
), while scalar keys like status
stay on the note as plain frontmatter. The discovered types and edge types are the vault's ontology: a graph schema you never have to configure, queryable with Cypher and searchable with BM25.
From crates.io:
cargo install smolbren
cargo install
builds from source, so you need Rust (edition 2024) and protoc
on
PATH (brew install protobuf
) — Lance compiles protobuf definitions at build time.
smolbren vault add personal ~/notes # register a vault
smolbren index # incremental index (rerun any time)
smolbren types # the discovered ontology
smolbren search "ambiguous utopia" # BM25 full-text search
smolbren query "MATCH (b:book)-[:themes]->(t:Note) RETURN b.id, t.id"
smolbren embed # embed chunks with a local model (~300MB, one-time download)
smolbren similar "two worlds divided by ideology" # semantic similarity search
smolbren search "utopia" --hybrid # BM25 + vector, fused with RRF
Full documentation lives at ** smolbren.com**: the
quickstart, core concepts (vaults, ontology, indexing, search), guides for
querying the graph, and
scripting & agents, plus the complete
CLI referencewith every flag, output shape, and exit code.
This CLI is designed to be driven by agents, and skills/smolbren/SKILL.md is a ready-made
Agent Skillthat teaches an agent the output contract, the explore-the-ontology-first workflow, Cypher rules, and the common gotchas. Install it with the
skills CLI, which detects your coding agents (Claude Code, Cursor, …) and installs it into each:
npx skills add junaidrahim/smolbren
Or install manually by copying the file into your agent's skills directory — for
Claude Code, ~/.claude/skills/smolbren/SKILL.md
(personal) or
.claude/skills/smolbren/SKILL.md
(per-project).
- Cypher can filter/return only physical columns (
id
,path
,type
,title
) — arbitrary frontmatter scalars likestatus
are inget
'sfrontmatter
object but not Cypher-addressable yet. - Wikilink targets are resolved when the
sourcenote is indexed; deleting a target leaves staleresolved
flags on unchanged notes untilindex --full
. embed
is a separate step fromindex
— new or edited notes are invisible tosimilar
/search --hybrid
until you runsmolbren embed
again (it's incremental, so rerunning is cheap).
Requires Rust (edition 2024) and protoc
on PATH (brew install protobuf
).
cargo build
cargo test # includes an end-to-end CLI test over tests/fixture_vault
Version lock:lance-graph 0.5.4 pinslance ^1.0
/arrow 56.2
/datafusion 50.3
. Do not bumplance
past 1.x until lance-graph tracks a newer release. Verify withcargo tree -d
.
Releases are automated: every push to main
runs
release-plz, which computes the next semver from
Conventional Commits, updates the changelog,
publishes to crates.io, and tags a GitHub release. Use conventional commit messages
(feat:
, fix:
, …) so your change lands in the right version bump. Docs live in docs/ as a Mintlify site and deploy on push to
main
.