The governing equation

One equation shapes every decision. Keep only this:

Four crates, cleanly layered

The engine owes nothing to the two adapters above it or the one model beside it. The AI-heavy crate sits behind the Embedder trait defined in b2-core, so the engine and its whole fast suite never import a tensor — and adding the desktop UI added one adapter, not new architecture.

One vault, traced end to end

Everything below follows this exact vault — the hand-authored golden fixture the tests run on. Two notes, engineered to exercise both edge kinds at once. Watch what each layer does to them.

---
b2id: 01JMEM0000000000000000000A
type: concept
title: "Human memory"
created: 2026-06-20
---
The brain encodes, stores, and retrieves information…

---
b2id: 01JSRS0000000000000000000B
type: concept
title: "Spaced repetition"
created: 2026-06-20
---
Spaced repetition exploits the [[concepts/memory|Human memory]]
retrieval curve.

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

The prose [[…]] is a bare, untyped references edge. The - elaborates [[…]] — … list item is a typed edge with an explanation. Both are human-authored (origin=inline) — B2 reads them, never writes them. One ingest yields a known-good graph the tests match whole.

FLOW ①  Ingest — vault becomes index

b2 reindex is the write path that realizes the governing equation. Its one subtlety: a note can link to one the walker hasn't reached yet, so link resolution must not depend on file order. Ingest runs in two phases.

• Phase 1 projects each note's frontmatter, chunks its body (a minimal paragraph splitter, one chunk per maximal run of non-blank lines), and embeds each chunk through the seam. This fills notes(b2id, path) — the path ⇄ b2id resolver — for the whole vault. Our two notes yield one chunk each; memory.md's chunk lands in chunks_vec ready to be found.
• Phase 2 derives edges by parsing each body + frontmatter relations: and resolving every [[path]] against the now-complete resolver. From spaced-repetition.md that's two directed edges to memory.md: a bare references and a typed elaborates. A typed line consumes its wikilink, so it isn't double-counted as a bare reference.
• If a note lacks a b2id, phase 1 stamps one — mint a ULID, write a single surgical line into the note's frontmatter. That's the whole record: the id travels in the file, so there is no separate log to keep. B2's one always-allowed write during ingest. (Both fixture notes are pre-stamped, so nothing is written here.)

Incremental by default, ≡ a full rebuild. A note whose body_hash is unchanged and whose chunks all still have vectors reuses them verbatim — only edited notes re-embed. Both paths replace rather than accumulate: re-projecting a note deletes its old chunks (FTS triggers fire, stale chunks_vec rows are cleared) and all its edges, then re-derives every edge from the current Markdown (body inline ∪ frontmatter). Because every edge is Markdown-derived, a one-note re-parse is exactly a one-note slice of a full rebuild — there is no log term to reconcile. b2 reindex --dry-run previews the same decision, writing nothing.

The schema — a derived projection

Every table is a projection of (Markdown); nothing here is a source of truth. The schema is derived from the data model — it must satisfy the model, never the reverse.

Two schema details do load-bearing work. There is no status column and no lifecycle — an edge exists iff it is written in the Markdown, so origin only records which home it came from (inline body link, or a frontmatter relations: entry). And chunks_vec is created outside the base migration because its FLOAT[N] dimension is a DDL literal pinned to meta.embed_dim: the vector space can only be shaped once the embedder's dim is known. (Removed 2026-07-04: the edge_provenance table, the status column, the origin='suggested' value, and the origin/status CHECK — all gone with the LLM relator.)

FLOW ②  Search — hybrid retrieval

BM25 keyword search and brute-force vector KNN run in parallel and fuse with Reciprocal Rank Fusion (Σ 1/(k + rank + 1), k=60). Results resolve up from chunks to notes.

# keyword + semantic + graph, one command
$ b2 search "how does forgetting affect recall"
notes/spaced-repetition.md  Spaced repetition
    …exploits the [[concepts/memory|Human memory]] retrieval curve.
concepts/memory.md       Human memory
    The brain encodes, stores, and retrieves information…

• The keyword half sanitizes raw natural language into a safe FTS5 expression — each alphanumeric term double-quoted so nothing is read as an operator, OR-joined for recall. (Punctuation is FTS5 syntax and would otherwise crash the parse — a real bug the eval surfaced.)
• A graph-filtered variant — "nearest chunks whose note is within k typed hops of note X" — is the chunks_vec ⨝ chunks ⨝ edges join. It searches within an already-related neighborhood (near ∩ connected). Discovery is its complement (near ∖ connected) — the two are opposites, and confusing them is the trap the engine turns on avoiding.
• The façade resolves hits to note level: pulls a wide chunk pool, dedups to the best chunk per note, attaches a one-line snippet.

FLOW ③  Similar — surface the connections you haven't made

b2 similar <note> surfaces the notes most semantically similar to an anchor that you haven't linked yet — instantly, locally, free: a vector KNN over the embeddings already in chunks_vec, with no model call and no network. The machine finds the candidates; you supply the judgment and the type (Flow ③ cont.). This is the reason B2 exists — and after the 2026-07-04 pivot it costs nothing per run.

FLOW ③ cont.  Link — commit a chosen connection

You saw a candidate worth connecting; now you commit it. There are exactly two ways a connection becomes real, both authored in Markdown — B2 never proposes an edge on its own, and there is no inert queue to accept from.

---
b2id: 01JSRS…B
type: concept
title: "Spaced repetition"
relations:
  - "elaborates [[concepts/memory|Human memory]]"  # ← appended
---

The write discipline — losslessness & surgical edits

The vault stays the human's. A parsed note keeps its raw text verbatim and records only the byte spans of the frontmatter block; serialization returns those raw bytes. So parse → serialize → parse is byte-identical — unknown keys, comments, odd whitespace, a missing final newline all survive. Against that backdrop, B2 makes only four narrow writes:

The one AI seam — a fake for CI, a real model for users

The one AI part left sits behind a swappable trait defined in b2-core. The engine is built and tested against a deterministic fake; a real model drops in through the identical seam with no schema or flow change. This is the "build for tomorrow's model" tenet made mechanical — and it is why the whole suite runs with no live model, no wall clock, and no random ids.

The command surface — a dumb adapter over one typed façade

Every engine module is called directly only by the integration tests. The Vault façade is the single typed entry point the CLI (and any future GUI) is the sole client of — it owns the connection, the injected embedder, and the id generator, and returns display-ready view structs (NeighborView, SearchResult, ExplainView, the discovery candidate view, …). The b2 binary parses args, picks the embedder, calls the façade, and prints — human, or --json for agents.

The invariants that hold it together

Almost every choice above serves one of these. Each is pinned by the suite.

Grounded in the tests

Nothing here is aspirational: the suite is the executable specification, integration-first, and every property above is asserted in it. Most tests share the golden vault, copied into a temp dir before every run so ingest never mutates the committed fixture, with two fixed b2ids so exact ids are assertable. Determinism is a hard requirement of the core — no wall clock, no randomness; timestamps and ids are passed in.

Not yet built

An honest architecture names its boundaries. Connection discovery is built — it is now b2 similar (surface) + b2 link (commit), local and free; the LLM relator was cut, not deferred. What remains is tuning, scale, and packaging — tracked in planning/tasks.md, not gaps that slipped through.