How It Works

How it works

Goal of this page: the six words you need, what an address means, and the four mechanisms that keep the board cheap. No prior knowledge assumed.

---

The vocabulary

Term	Meaning
Entry	One note on the board. Has an address, a version, a summary and contents.
Digest	The mandatory short summary carried by every entry, capped at 200 tokens. Agents read these first. This is the single most important rule in the system.
Workspace	One project or engagement. Its own database file.
Topic	A subject area inside a workspace, such as domain.automotive. Keeps unrelated work separated.
Token	The unit AI models read and are billed in — roughly three-quarters of a word.
Context window	Everything a model can see at once. The scarce resource this whole project exists to conserve.

Addresses

Every entry has one address, and it reads left to right from broadest to narrowest:

bb://myproject/domain.automotive/fact/brake-assembly
     └workspace┘ └───topic─────┘ └kind┘ └────name────┘

• workspace — which project this belongs to.
• topic — the subject area. Access control and every listing work on topics.
• kind — what sort of note it is: a fact, a decision, a task specification, a result, a run state.
• name — a stable, human-chosen identifier.

Addresses are the only thing agents pass around. Handing an address to a helper agent costs a few tokens; handing it the content costs whatever the content costs.

What is stored

A local SQLite database file per workspace, plus a directory of large files stored outside the database. Nothing listens on a network port in local mode — each agent session starts its own server process and talks to it over its standard input and output. The test suite asserts that the number of network connections in local mode is zero.

Every write creates a new version rather than overwriting. The history stays readable, so "what did this say before that agent changed it?" is answerable.

The four mechanisms that keep it cheap

1. Summaries first. Reads return digests by default. Reading 40 summaries costs roughly 4,000 tokens; reading the same 40 entries in full could cost 180,000.

2. Ask for only what you need. There are five ways to read an entry, and they form a ladder from cheapest to most expensive:

just the address  →  the summary  →  named fields  →  a compact table  →  the whole thing

Start at the left and move right only when you must. The compact table form is tab-separated rows with a single header line, which measures 44.6% cheaper than the same 30 records expressed as JSON objects.

3. The server enforces a budget. Every read carries a token budget. The server fills up to it, stops, and reports exactly what it left out and at which address. It is not possible for a read to quietly flood an agent's context window.

4. Big files never pass through an agent. Ask the server to ingest a file by its path and the server reads, stores and summarizes it itself; the agent receives an address and a summary. This is the difference between offloading content after you have already paid for it and never paying at all. Reading a 40,000-token file and then filing it away saves nothing.

Two safety properties worth knowing

Unrelated subjects cannot leak into each other. Each agent's access token lists the topics it may touch, and the server enforces that list. An agent working on cars cannot read a different topic — not because it was asked not to, but because the server refuses. Search results and listings are filtered by the same rule.

Notes are data, never instructions. Content written by other agents comes back wrapped in explicit markers:

<bb:body uri="bb://ws/topic/kind/id" producer="worker-3">
...content...
</bb:body>

Every role prompt states that text inside those markers must never be obeyed as a command, however it is phrased. Reuse is this system's entire value, which is also what makes it the path by which one poisoned note could reach everyone who reads it.

Concurrency without locks

Two agents can write the same address at the same time. There is no lock. Instead, a writer passes the version it last read, and the server accepts the write only if the entry is still at that version — otherwise it rejects the write and returns the current version, so the writer can re-read and merge. This is called compare-and-swap.

Measured: with eight agents writing the same address simultaneously, exactly one wins and the other seven get a rejection carrying the current version. With 30 concurrent writes, all 30 versions survive in the history. The convention that keeps this rare is simple: one writer per address.

What is built

The project is split into five layers, and only the first two are built.

Layer	Name	Covers	Status
0	Store	notes, addresses, versions, summaries, search, file storage, access control, budgets	Built
1	Protocol	the instructions agents follow: naming, when to read what, how to resume	Built
2	Coordination	a task queue: claiming work, timed ownership, waiting for updates	Deferred
3	Governance	scoring how trustworthy a note is, disputing bad notes, cleaning up	Deferred
4	Cloud	running it for a team: a shared database, object storage, authentication	Deferred

→ Roadmap and deferred layers explains what specific event has to happen before each deferred layer gets built, and why waiting is the point.