-
Notifications
You must be signed in to change notification settings - Fork 0
Whats Changed
Goal of this page: what is new, in plain language, with why it was done and what it cost. Newest first.
This project is young — the first commit landed on 6 September 2026 — so this page is closer to a running log than a release history. There are no version numbers yet.
What changed. The read path always had five ways to ask for less. The write path had exactly one: hand-composed JSON, chosen on an argument about cost that nothing checked. It now has several shapes, each measured.
| New shape | Use it when | Saved |
|---|---|---|
columns + rows
|
you are writing a set of similar records | 28% on a 12-finding set |
append / append_path
|
you are adding one item to a running entry; the server does the read-modify-write, so the existing body never crosses the wire | 94% |
digest_from="field" |
the body already contains its own summary; the server lifts it | 17% |
digest alone |
the whole finding fits in a summary — a body is not required | 43% |
select / lines with source_path
|
you need one part of a file; the server slices it and the rest is never stored either | avoids storing what nobody wanted |
writes: [...] |
several related entries in one call | one round trip instead of several |
| — | the server no longer echoes your summary back in the result | 68% of the echo |
Four writes end to end: 2,435 → 1,010 tokens, 59% less. Details and the caveat about which bracket each ratio measures: Measured results.
What it cost. The tool descriptions re-sent every turn grew from 395 to 469 tokens against a 600 budget. That is paid by every agent whether or not it uses a new shape. It sits in the cacheable prefix, so the real bill is smaller than the number looks — but it is standing, and only 131 tokens of headroom are left.
How to check it yourself. bench/write_shapes.py regenerates the table and
refuses to run unless the exact tokenizer is installed.
Running five real agents against the board found three things no test had:
- The example client configuration installed the package without the transport extra, so the server would not start.
- The server resolved an agent's access grant once at process start, which made revoking a token or letting it expire completely inert for a running server. Now re-checked.
- Cleaning up unreferenced files scoped its "still in use" set to one workspace, while files are shared across all of them — so it could delete a file another workspace still pointed at.
A follow-up fixed a related case: cleanup could delete files that older versions of an entry still referenced. Version history is meant to stay readable, so it now keeps them.
Three changes, all in the same direction — a test that quietly passes is worse than no test.
- Any test that reports a token saving now fails loudly if the exact tokenizer is missing, instead of silently falling back to the estimator that was once 106% wrong.
- Optional extras no longer silently disable whole test files. Continuous integration now runs a configuration where everything is installed, so "120 passed" means 120 actually ran.
- The agent-facing instruction sheet and the human-facing practices page are checked against each other, and the build fails when they drift apart.
Test count: 84 → 120.
Five agents, five questions about this repository, identical prompts — the only difference being that one arm reported in prose and the other wrote to the board and replied in three lines. Parent context −93.6%, total agent spend −38.7%, no loss of quality, and one prediction falsified (the board arm was expected to cost more internally; it cost 39% less).
n=1. It is recorded because the planned four-arm benchmark had produced nothing and one honest data point beats an assumption. It is not the benchmark.
Writing an entry used to cost the author their summary twice: once composing it, once reading it echoed back in the result. The echo is gone. Small, constant, and paid on every write anyone ever makes.
A practices page ordered by how much each practice saves, with the measured figure attached to each: Reading and writing cheaply. It opens with the question to answer before any write — which context reads this instead of re-deriving it? — because a write with no answer to that is pure overhead.
A board that is merely reachable gets used badly, which costs more than not having one. So the setup path now installs the protocol alongside the server: three instruction sheets (the core protocol, fanning out to helper agents, parking and resuming a session), an adapter for Claude Code, and a verification step you are told not to skip. Two bugs in the setup instructions themselves were fixed the same day — a flag documented in the wrong position, and the wrong environment variable names.
The same day added the section that says plainly which parts of a fan-out the board cannot help with: a background command's log and a monitor notification, because output that has already reached an agent is already paid for.
Every Markdown file in the repository now exists to be understood on first read
by someone who arrived from a search result. No undefined abbreviation, no
filename as link text, lead with what a thing does rather than what it is made
of, and every number either measured-and-cited or labelled a target. The README
and the architecture document were rewritten to it; the design notes under
docs/ are being brought up to it as they are touched.
Layer 0 — the store — and Layer 1 — the protocol agents follow. Entries with mandatory summaries, addresses, versions, full-text search, storage of large files outside the database, topic-scoped access control, and token budgets on every read, over five tools. Layers 2 to 4 designed and deliberately not built.
The task queue, trust scoring and the multi-machine deployment remain unbuilt. Each waits on a specific observation rather than a date — Roadmap and deferred layers says which, and why building a guard before the failure it guards against is how projects like this stall at 80% complete.
Every number in this wiki is either measured and cited, or labelled a target — the same rule the repository's documentation standard applies to itself. Source, tests and design notes: TapanManu/blackboard.
Start here
Understanding it
Evidence
Direction