Home

Blackboard

A shared notepad for AI agents. It runs on your own machine, stores what agents learn, and lets a new agent pick up where a previous one stopped — without re-reading everything that came before.

If you have never seen this project, read this page top to bottom. It is self-contained. Everything else in this wiki is detail you can reach for later.

---

The problem it exists to solve

An AI agent re-reads its entire conversation on every single turn. That transcript only grows, so a long task gets steadily more expensive:

• Step 5 — the agent re-reads 8,000 words of history. Cheap.
• Step 50 — it re-reads 200,000 words. Slow, expensive, and it starts missing things buried in the middle.
• The session ends — a context limit, a crash, a closed terminal — and all of it is gone. The next agent starts from nothing.

It gets worse with several agents at once. To hand work to a helper agent, the usual approach copies the relevant background into that helper's prompt. Four helpers means paying for the same background four times. When they report back in prose, the coordinator has to read all four reports — and re-read them on every turn for the rest of the session.

The idea

Give the agents a shared place to write things down.

Every note gets an address and a mandatory short summary — this project calls it a digest: one paragraph, roughly 150 words, hard-capped at 200 tokens. A token is the unit AI models read and are billed in, roughly three-quarters of a word. Agents read digests by default, and open the full note only when they genuinely need the detail.

So instead of copying a 40,000-token document into four agents' prompts, you write it to the board once and hand each agent an address. Instead of a coordinator re-reading four long reports forever, it reads four short summaries.

The result, stated as plainly as it can be: the cost of picking up a task stops growing with how much work came before it.

Does it actually work?

Yes, for the specific thing it was built to do. These figures come from the test suite and are counted with a real tokenizer, not estimated:

Work stored on the board	What a fresh agent needs to get oriented	Share of reading everything
10,506 tokens	2,679 tokens	25.5%
229,566 tokens	2,679 tokens	1.2%
886,746 tokens	2,679 tokens	0.3%

Flat. That flat line is the point of the whole project — and note what it does not claim: the saving is a function of how much work the board holds, which is a property of your workload, not of this software. A board of tiny entries has little to save.

One live run with five real agents on this repository measured 93.6% less context in the coordinating agent (36,766 → 2,357 tokens) with no loss of quality. That is a single run, and a single run is a data point, not a demonstration. → Measured results has every number, the tokenizer used, and the bugs measurement caught.

What you can do with it

Five operations. That is the entire surface an agent sees.

Operation	What it does
update_state	Write a note. A summary is required. Large content is stored outside the note.
get_state	Read notes by address. Returns summaries unless you ask for more.
list_keys	List what exists in a subject area, optionally as a compact table.
search_keys	Full-text search. Returns addresses and summaries, never full contents.
link_state	Record that one note came from, depends on, or contradicts another.

There is deliberately no scheduler, no locking and no task queue. → Roadmap and deferred layers explains what is held back and what specific event has to happen before each piece gets built.

Where to go next

If you want to…	Read
Install it and connect an agent to it	Getting started
Understand addresses, digests, topics and budgets	How it works
See the five operations in detail	The five tools
Use it without wasting tokens	Reading and writing cheaply
Run several agents against one board	Working with multiple agents
Check the evidence, including the unflattering parts	Measured results
Know what changed recently	What's changed
Know when not to use it	Limits and honest caveats

Honest summary in three lines

It is built and tested for one job: carrying context across a boundary — a new session, a compaction, a hand-off to another agent. It is measurably good at that job. Below about five sub-tasks, or for work that fits in one context window, it costs more than it saves, and Limits says so in detail.