Get started with B2

Clone the repo and build the release binary, then alias it so b2 is on your path for this shell:

$ git clone https://github.com/AlteredCraft/B2 && cd B2
$ cargo build --release -p b2-cli
$ alias b2=./target/release/b2
$ b2 --help
B2 — explore a Markdown vault's typed graph and search from the terminal

Semantic search and connection discovery run on a local embedding model — no account, no API key, no network at query time. b2 init downloads and verifies the model into a shared cache once — it is not re-downloaded per vault, and there is never a surprise download mid-command later.

$ b2 init
Installed 'bge-base-en-v1.5' (768 dims). Run `b2 reindex` to embed your vault.

Just write Markdown files. Here are two — a concept and a note that connects to it. The frontmatter is minimal; the body is plain prose:

# ~/vault/concepts/memory.md
---
type: concept
title: "Human memory"
created: 2026-07-03
---
The brain encodes, stores, and retrieves information.

# ~/vault/notes/spaced-repetition.md
---
type: note
title: "Spaced repetition"
created: 2026-07-03
---
Spaced repetition exploits the retrieval curve.

## Relations
- elaborates [[concepts/memory|Human memory]] — applies the forgetting curve

That last line is a typed connection: the verb elaborates, a wikilink [[concepts/memory|Human memory]] to the target, and a "why". A bare [[path|title]] anywhere in prose is an untyped references link. The verbs come from a small closed vocabulary — references, relates, elaborates, supports, refutes, contradicts, example-of, part-of, supersedes, derived-from — the same palette you'll pick from with b2 link.

Nothing is hidden — the files stay ordinary Markdown that work in Obsidian, or anything else, with no B2 running. After indexing (next step), that first note gains exactly one line B2 manages:

---
b2id: 01KWMCW242E0WSKVYDYNQBT7SN   # set by B2 on first index — a stable id, never changes
type: note
title: "Spaced repetition"
created: 2026-07-03
---
Spaced repetition exploits the retrieval curve.

## Relations
- elaborates [[concepts/memory|Human memory]] — applies the forgetting curve

b2 reindex reads every note, stamps any missing b2id, and builds the searchable index. It's how B2 catches up to files you've created or edited by hand:

$ cd ~/vault
$ b2 reindex .
Indexing /Users/you/vault
  embedding 2/2 · notes/spaced-repetition.md (2 chunks)
Indexed 2 notes (2 embedded, 2 stamped)

Run it again after editing notes — it's incremental: unchanged notes keep their vectors, so only what actually changed is re-embedded. Two flags help:

• b2 reindex --dry-run — preview what would happen (writes nothing, not even a b2id).
• b2 reindex --force — re-embed everything from scratch.

One command, hybrid ranking — it fuses keyword (BM25) and semantic (vector) matches, so you find notes by wording and by meaning:

$ b2 search "how does forgetting work"
0.0328  Spaced repetition (notes/spaced-repetition.md)
    Spaced repetition exploits the retrieval curve.
0.0161  Human memory (concepts/memory.md)
    The brain encodes, stores, and retrieves information.

Use --limit N to widen or narrow the result set.

Follow the connections around any note. neighbors is a quick list of what a note links to and from; explain adds each connection's why and its provenance:

$ b2 neighbors notes/spaced-repetition
→ elaborates  Human memory (concepts/memory.md) — applies the forgetting curve

$ b2 explain concepts/memory
Human memory (concepts/memory.md)  [b2id 01KWMCW242E0WSKVYDYNQBT7SN]
Connections:
  ← elaborated-by  Spaced repetition (notes/spaced-repetition.md)  [inline]
      why: applies the forgetting curve

You can pass a note as either its vault-relative path or its b2id. When nothing points at a note, explain flags it as an orphan — surfaced for you to notice, never auto-changed.

This is the point of B2. b2 similar <note> surfaces the notes most semantically similar to a given one that you haven't linked yet — a pure, instant read over the vectors reindex already stored. No model call, no network, no cost: the ranking and the "∖ already-connected" exclusion happen locally over your whole vault.

$ b2 similar notes/spaced-repetition
0.71  Cramming works       (notes/cramming.md)
    Massed practice yields only short-term recall.
0.63  The forgetting curve  (concepts/forgetting-curve.md)
    Retention decays exponentially without review.

Each row is a similarity score, the note's title and path, and the passage that made it similar. The note itself and anything already linked to it never appear. It lists about ten by default; --limit N widens or narrows that.

Pick the connections worth keeping and commit them. Either write a [[link]] in your note's body yourself, or run b2 link:

$ b2 link notes/spaced-repetition notes/cramming --type contradicts --explanation "massed vs. spaced practice"
Linked spaced-repetition → cramming (contradicts). Wrote the typed relation into the source note's frontmatter.

b2 link <src> <dst> appends the typed relation to the source note's frontmatter relations: — Markdown-first, never the body. --type picks the verb from the closed vocabulary (defaults to references); --explanation records the "why". Re-run b2 similar afterward and a note you just linked drops off the list — it's connected now, so the exclusion filters it out.