{"slug": "smolbren-local-search-for-your-markdown-vaults", "title": "Smolbren: Local search for your Markdown vaults", "summary": "Smolbren, a new CLI tool, turns Markdown vaults into local, queryable knowledge graphs with full-text search, using frontmatter to discover ontology and supporting Cypher queries and BM25 search. Designed for agents, it outputs JSON and runs fully locally with incremental indexing, offering a portable second brain for note-takers.", "body_md": "A portable brain for all us mere mortals trying to create a second brain.\n\n`smolbren`\n\nturns a folder of markdown files — an Obsidian vault, a notes directory,\nanything with frontmatter — into a local, queryable knowledge graph with full-text\nsearch on top. It doesn't impose a schema; it **discovers** one from the frontmatter\nyou already write, then lets you (or your agent) query it with Cypher and BM25.\n\n**Ontology-first.** Tools like`qmd`\n\napproach vault search embeddings-first. smolbren instead starts from the structure your notes already encode: the frontmatter`type`\n\nkey becomes a node type, and every frontmatter key holding`[[wikilinks]]`\n\nbecomes a typed edge in a graph. Embeddings come on top —`smolbren embed`\n\nruns a local model (EmbeddingGemma-300M via ONNX, nothing leaves your machine) for semantic`similar`\n\nsearch and BM25+vector`search --hybrid`\n\n.**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 to`jq`\n\n; agents parse directly — there's a[ready-made skill](#agent-skill)too.**Fully local and fast.** Storage is[Lance](https://lancedb.github.io/lance/)on disk under`~/.smolbren/`\n\n. Indexing is incremental (blake3 content hashes, mtime+size fast path) and parses files in parallel across all cores.\n\nEverything starts from a note like this:\n\n```\n---\ntype: book\nstatus: reading\nstarted: 2026-06-01\nauthor: \"[[people/ursula-k-le-guin]]\"\nthemes: [\"[[topics/anarchism]]\", \"[[topics/utopia]]\"]\nrelated: [\"[[books/the-left-hand-of-darkness]]\"]\n---\n\n# The Dispossessed\n\nAn ambiguous utopia: two worlds, one wall, and the physicist who tries to\nunbuild it.\n```\n\nFrom each file, `smolbren index`\n\nderives an **id** (the vault-relative path without\n`.md`\n\n— `books/the-dispossessed`\n\n, the same shape wikilink targets use), a **type**\n(`book`\n\n, which becomes a Cypher node label alongside the catch-all `Note`\n\n), a\n**title** (the first `# heading`\n\n), and **edges** — every frontmatter key whose values\ncontain wikilinks becomes a relationship type (here `author`\n\n, `themes`\n\n, and\n`related`\n\n), while scalar keys like `status`\n\nstay on the note as plain frontmatter.\nThe discovered types and edge types are the vault's **ontology**: a graph schema you\nnever have to configure, queryable with Cypher and searchable with BM25.\n\nFrom [crates.io](https://crates.io/crates/smolbren):\n\n```\ncargo install smolbren\n```\n\n`cargo install`\n\nbuilds from source, so you need Rust (edition 2024) and `protoc`\n\non\nPATH (`brew install protobuf`\n\n) — Lance compiles protobuf definitions at build time.\n\n```\nsmolbren vault add personal ~/notes    # register a vault\nsmolbren index                         # incremental index (rerun any time)\nsmolbren types                         # the discovered ontology\nsmolbren search \"ambiguous utopia\"     # BM25 full-text search\nsmolbren query \"MATCH (b:book)-[:themes]->(t:Note) RETURN b.id, t.id\"\n\nsmolbren embed                         # embed chunks with a local model (~300MB, one-time download)\nsmolbren similar \"two worlds divided by ideology\"   # semantic similarity search\nsmolbren search \"utopia\" --hybrid      # BM25 + vector, fused with RRF\n```\n\nFull documentation lives at ** smolbren.com**:\nthe\n\n[quickstart](https://smolbren.com/quickstart), core concepts (vaults, ontology, indexing, search), guides for\n\n[Obsidian setup](https://smolbren.com/guides/obsidian-setup),\n\n[querying the graph](https://smolbren.com/guides/querying-graph), and\n\n[scripting & agents](https://smolbren.com/guides/scripting-agents), plus the complete\n\n[CLI reference](https://smolbren.com/cli/overview)with every flag, output shape, and exit code.\n\nThis CLI is designed to be driven by agents, and [ skills/smolbren/SKILL.md](/junaidrahim/smolbren/blob/main/skills/smolbren/SKILL.md)\nis a ready-made\n\n[Agent Skill](https://agentskills.io)that teaches an agent the output contract, the explore-the-ontology-first workflow, Cypher rules, and the common gotchas. Install it with the\n\n[skills CLI](https://github.com/vercel-labs/skills), which detects your coding agents (Claude Code, Cursor, …) and installs it into each:\n\n```\nnpx skills add junaidrahim/smolbren\n```\n\nOr install manually by copying the file into your agent's skills directory — for\nClaude Code, `~/.claude/skills/smolbren/SKILL.md`\n\n(personal) or\n`.claude/skills/smolbren/SKILL.md`\n\n(per-project).\n\n- Cypher can filter/return only physical columns (\n`id`\n\n,`path`\n\n,`type`\n\n,`title`\n\n) — arbitrary frontmatter scalars like`status`\n\nare in`get`\n\n's`frontmatter`\n\nobject but not Cypher-addressable yet. - Wikilink targets are resolved when the\n*source*note is indexed; deleting a target leaves stale`resolved`\n\nflags on unchanged notes until`index --full`\n\n. `embed`\n\nis a separate step from`index`\n\n— new or edited notes are invisible to`similar`\n\n/`search --hybrid`\n\nuntil you run`smolbren embed`\n\nagain (it's incremental, so rerunning is cheap).\n\nRequires Rust (edition 2024) and `protoc`\n\non PATH (`brew install protobuf`\n\n).\n\n```\ncargo build\ncargo test            # includes an end-to-end CLI test over tests/fixture_vault\n```\n\nVersion lock:lance-graph 0.5.4 pins`lance ^1.0`\n\n/`arrow 56.2`\n\n/`datafusion 50.3`\n\n. Do not bump`lance`\n\npast 1.x until lance-graph tracks a newer release. Verify with`cargo tree -d`\n\n.\n\nReleases are automated: every push to `main`\n\nruns\n[release-plz](https://release-plz.dev/), which computes the next semver from\n[Conventional Commits](https://www.conventionalcommits.org/), updates the changelog,\npublishes to crates.io, and tags a GitHub release. Use conventional commit messages\n(`feat:`\n\n, `fix:`\n\n, …) so your change lands in the right version bump. Docs live in\n[ docs/](/junaidrahim/smolbren/blob/main/docs) as a Mintlify site and deploy on push to\n\n`main`\n\n.", "url": "https://wpnews.pro/news/smolbren-local-search-for-your-markdown-vaults", "canonical_source": "https://github.com/junaidrahim/smolbren", "published_at": "2026-07-08 02:53:46+00:00", "updated_at": "2026-07-08 03:30:13.184307+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "natural-language-processing"], "entities": ["Smolbren", "Obsidian", "Lance", "Cypher", "BM25", "EmbeddingGemma-300M", "ONNX", "Rust"], "alternates": {"html": "https://wpnews.pro/news/smolbren-local-search-for-your-markdown-vaults", "markdown": "https://wpnews.pro/news/smolbren-local-search-for-your-markdown-vaults.md", "text": "https://wpnews.pro/news/smolbren-local-search-for-your-markdown-vaults.txt", "jsonld": "https://wpnews.pro/news/smolbren-local-search-for-your-markdown-vaults.jsonld"}}