The Knowledge Flywheel: Beads + an LLM Wiki

A knowledge flywheel is a maintenance loop for work that agents would otherwise forget. In mine, Beads records decisions, dependencies, acceptance, and completion. An LLM wiki turns reviewed source material into linked Markdown pages that later sessions can read. The loop helps only when someone keeps both honest.

That is the whole mechanism. No escape velocity. No automatic learning. No claim that a larger folder makes a model smarter.

This is the knowledge layer I use around AgentOps. AgentOps runs a narrower delivery loop: one intent, one bounded build, one fresh verdict. The flywheel starts after that work produces something worth preserving.

The two ledgers

Beads and a wiki remember different things.

An issue tracker alone leaves knowledge scattered across closed work. A wiki alone can drift into a polished story with no connection to the work that tested it.

Together, they give every reusable claim a trail. The bead points to the change and its checks. The wiki page explains the lesson in a form another person or agent can use.

One real cycle

I learned this through a boring failure.

Two workers touched the same shared file. The work looked parallel on the issue graph, but the write path was not. The branches collided, the integration took longer than the original change, and I later caught myself planning the same mistake again.

The useful loop looks like this:

1. A bead names the work, the shared-file risk, and the acceptance check.
2. The implementation runs. Tests and a fresh review show what passed and what failed.
3. The bead keeps the result next to the original intent.
4. If the lesson generalizes, a wiki page records the planning rule and links back to the bead, commit, or other source.
5. The next related bead links that page before implementation starts.
6. If the rule proves wrong or stale, a new bead repairs the wiki.

The page does not appear because a transcript existed. Someone has to decide that the lesson is reusable, write it clearly, and keep the source attached.

What the LLM does

An LLM is useful for the bookkeeping that people skip. It can summarize source material, propose page boundaries, add links, find duplicate explanations, and flag stale references. It can also produce a confident synthesis that the sources do not support.

So the LLM drafts. The evidence decides.

I want every durable page to make four things easy to inspect:

• the claim;
• the source that supports it;
• the date or condition under which it was true;
• the work that should happen when it stops being true.

That last item matters. A wiki without a repair path becomes a museum. Beads provide the repair path.

What belongs in the wiki

Most sessions should not create a new page. The useful candidates repeat, constrain future work, or explain a decision that will otherwise be reopened.

Good candidates:

• a repository-specific failure pattern and the check that catches it;
• an architectural decision with the rejected alternatives;
• a deployment constraint that changes how work must be packaged;
• a procedure that another operator needs to run without its author present;
• a source synthesis that will be reused across several beads.

Bad candidates:

• a transcript dump;
• a one-off status update;
• an unverified hunch promoted because it sounds general;
• a duplicate page with fresher prose and no new evidence.

The wiki earns its keep by making the next decision cheaper to verify. Page count is not the score.

A minimum viable setup

You can run this without AgentOps or a special database.

work ledger
  beads              intent, dependencies, acceptance, evidence

knowledge base
  wiki/index.md       map of the maintained pages
  wiki/decisions/     choices and their reasons
  wiki/patterns/      repeatable rules with receipts
  wiki/sources/       notes tied to original material

Then keep one explicit handoff between them:

bead produces evidence
  → review decides what generalizes
  → wiki records the reusable part and cites the bead
  → later bead links the relevant page
  → failure opens repair work

Start with one page that prevents a mistake you have already repeated. Link it from the next bead that touches the same area. If it changes the decision, the loop did useful work. If nobody reads it, prune it or fix the retrieval path.

Where AgentOps fits

AgentOps is the operating loop around the work: Plan fixes the intent, Implement builds a bounded candidate, and a fresh Validate step judges the same acceptance and evidence. Beads are the preferred tracker, so the work begins from a durable source instead of chat scrollback.

The LLM wiki is an optional knowledge layer around that core. It must not decide whether the current change passed. A useful wiki page can inform a future plan; only the current acceptance and current evidence can validate current work.

That boundary keeps the story honest. The agent does not improve merely because it ran. The team gets a better chance of reusing a reviewed decision because the decision now has an address.

What I got wrong before

The first version of this essay described a Forge, Pool, Inject pipeline and treated the resulting corpus as a likely compounding advantage. The commands changed. The larger claim also failed its first honest test: the treatment did worse than a curated baseline.

I still believe the bookkeeping habit is useful. I no longer use that belief as evidence that the system learns, compounds, or forms a moat. Devlog #6 has the negative result.

The claim I will make today is smaller: Beads plus an LLM wiki creates a traceable path from work to reusable instructions. Whether that path improves outcomes is an eval question, page by page and task by task.

Related

• CDLC: where maintained context fits in the delivery lifecycle
• AgentOps: the operating loop and portable skills
• 12-Factor AgentOps: the broader delivery principles
• Devlog #6: the failed A/B that narrowed this claim