GROOM: Gated Refresh of Organizational Memory

An LLM agent is only as current as the text it reads. Production agents ground their answers in curated corpora: engineering wikis, runbooks, style guides, the documents behind retrieval-augmented generation^[1]. We version the model and update it on a schedule. The corpus sits still, and the world moves past it. GROOM keeps the corpus current by turning each consultation into the trigger to maintain it. Every edit it makes passes a checkpoint before it counts, so the maintenance runs on its own.

Knowledge rot

Start with a concrete failure. An agent reads your team’s wiki before it answers a question. Six weeks ago someone wrote that the staging database lives at db-staging-1. Last week the team moved staging to db-staging-3 and left the page alone. The agent reads the page and answers db-staging-1, with full confidence.

The model did nothing wrong. It read the source it was told to trust and reported what the source said. No exception fired. No log line turned red. The agent gave a confident wrong answer because the page behind it was old.

We call this knowledge rot: a corpus describes a world that has moved on, and the agents reading it inherit the error. A page written in March documents an API that shipped a breaking change in May. An agent reads it in June and repeats the mistake in whatever it builds. The failure stays invisible until something downstream breaks.

Context engineering^[2] manages the window, the tokens that reach the model at inference time. GROOM manages the source those tokens come from. Keep the source fresh and the agent stays right; let it rot and the agent inherits the error and states it with the same confidence.

Most of the tools we build for knowledge bases handle two jobs: writing pages and finding them. Authoring, search, embeddings, retrieval. Keeping pages current after they are written gets far less attention. GROOM is built for that third job.

Why the usual fixes miss

Three reflexive answers come up first. Each one fixes something real and leaves the rot in place.

Re-index it. Rebuild the embeddings, add a reranker, tune retrieval. This makes a stale fact easier to find. It does not make the fact true. A faster retriever surfaces the wrong page sooner. Retrieval freshness and content freshness are separate axes, and correctness lives on the second one.

Run a nightly job over everything. A cron that rechecks every page spends most of its budget on pages no agent reads, lags reality by up to a day, and asks a model to operate over the whole corpus in one unbounded pass. That pass is the unsupervised, hard-to-review operation you want to avoid. Grow the corpus and the cost grows with the shelf, not with what agents use.

Have a person review it. This is where most teams land, and it does not scale. It also inverts the priority: the pages that rot are the ones no one opens, which are the ones a review pass keeps skipping.

All three treat maintenance as a separate chore, scheduled and paid for on its own, cut off from the moments an agent uses the knowledge. GROOM joins the two.

The idea: reading the corpus maintains it

The pattern comes from web caching. HTTP has a directive called stale-while-revalidate^[3]. When a cached response is past its freshness window, the cache serves the stale copy at once and fetches a fresh one in the background, so the next request gets the update. The reader never waits. The cache stays useful because agents keep reading it.

GROOM applies that pattern to knowledge. A consultation is the trigger to check whether the page needs maintenance. The agent that reads it never waits: the check returns in tens of milliseconds, and any real work runs in a separate process the reader never sees. The corpus gets maintained as a side effect of being read.

This gives GROOM a property a nightly job cannot have: maintenance follows attention. A hot page the whole team relies on gets refreshed often; a cold page no agent opens can stay stale without costing anyone. A page carries a timestamp, and a refresh is due only once that stamp is older than the freshness window, 24 hours in our setup, so reading a hot page a hundred times in an hour still triggers at most one run.

That focus is the payoff. In simulation, against the skewed read patterns real corpora show, GROOM keeps the busiest pages far fresher than an equal-budget schedule that spreads its work evenly, and lets the pages no one reads drift.

An LLM maintaining a markdown knowledge base is not a new idea^[4]. What GROOM adds is the trigger that decides when to act and the gate that makes the acting safe. Figure 1 traces one consultation from the read to the journaled edit.

Walking the loop

Figure 1 is the whole system. Each step does something deliberate, so here it is in words.

1. An agent consults a page. It opens the wiki through a skill, the same way it reads any documentation. The step looks ordinary to the agent.

2. The skill fires a launcher. Opening the wiki also starts a small background process. The launch does not block, so the agent reads on without waiting.

3. The launcher checks three gates before it spends anything. Is maintenance enabled? Is a refresh due, or did one run recently? Is another refresh already running? The third check is an atomic lock: when eight reads arrive at once, one wins the claim and the other seven step aside. If any gate says no, the launcher exits in milliseconds and the agent reads the page as it stands. Most reads take this path.

4. When all three gates pass, the launcher spawns a detached worker and returns. By the time the worker starts, the consulting agent has moved on with the page it read. The reader and the maintainer never overlap.

5. The worker runs one bounded operation. It runs one budgeted job rather than a sweep of the whole wiki: fix the formatting on a page, cut a redundancy, fill a gap, or ingest a source. The worker scores the candidate page on the axes the operations target, form, redundancy, and coverage, and applies the single operation that page most needs, the same selection iterate performs. We list the operations in their own section below.

6. Whatever the worker changes passes a gate before it counts. The gate is the core of GROOM, so it gets the next section.

7. GROOM journals the run. Each accepted change appends a line to a human-readable changelog: the page, the operation, the diff. When you wonder why a page reads the way it does, the journal is the record.

The consulting agent never blocks, never sees an error when maintenance fails, and never pays the maintenance latency. A separate process carries that cost, later. Reading triggers the work; the work happens elsewhere.

What a maintenance run does

A maintenance run does one bounded operation. There are four, plus one that finds and lifts the weakest page.

lint fixes form: heading structure, missing frontmatter fields, broken internal links. It is the cheapest, safest operation, and it runs most often.

prune cuts redundancy. When two pages have drifted into saying the same thing, prune consolidates them, so an agent has one place to trust instead of three that might disagree.

expand fills a gap from the open web. When a page flags something it does not yet cover, expand does bounded research and writes the missing piece in the page’s own voice.

research ingests a specific source, an arXiv paper for instance, and attaches a citation, so every claim it adds traces back to where it came from.

iterate finds the weakest page. It scores every page on the axes the operations target, form, redundancy, and coverage, picks the lowest, and applies the one operation that page most needs, so the corpus’s floor keeps rising.

The shared constraint is small, gated, reversible steps. GROOM never rewrites the whole wiki at once. It makes one bounded change, proves it safe, keeps it or discards it, and records what it did.

The checkpoint gate

Letting a model rewrite a live knowledge base sounds risky, and it is. A model can hallucinate a detail, drop a load-bearing sentence while tidying, or rewrite something that was already correct. GROOM handles this by trusting none of the edit. It treats every maintenance run as a transaction that has to earn its commit.

The mechanism is git. Git already records a known-good state and snaps back to it, so GROOM uses it as a transaction log.

Checkpoint. Before the operation runs, GROOM commits the clean corpus. A labeled known-good state now exists to fall back to.

Run, scoped. A path fence confines the operation to the corpus directory, so it cannot touch anything else on disk, and a fixed budget caps its turns and edits. A misbehaving operation hits a wall instead of running away.

Gate. When the operation finishes, GROOM checks four things, and all four have to hold before it keeps a single byte:

The operation reported terminal success, rather than erroring out or exhausting its budget.
The corpus still passes the deterministic validator: valid structure, required frontmatter, no broken internal links, no orphaned pages.
The canaries still hold. A canary pins one load-bearing fact, a promise that a given page still contains a given string. We author a canary when a fact is known to matter (the staging host db-staging-3 is one), and the validator re-checks every canary after each run. Canaries catch an edit that drops a fact while passing every structural check.
The postcondition holds. Each operation declares a checkable predicate over the diff, and GROOM confirms the change matches what the operation promised. A formatting pass asserts that the prose is byte-identical once formatting is normalized away. A gap-fill asserts the flagged region grew. A consolidation asserts the page count did not drop.

Commit or revert. If the four checks pass, GROOM commits and journals the diff. If one fails, it runs git reset --hard to the checkpoint, and the working tree returns to the known-good state in about thirteen milliseconds.

The asymmetry is the design. A good edit costs one commit. A bad edit costs nothing, because it never lands. GROOM’s default is to change nothing, and it leaves that default only when every check agrees.

We tested the gate instead of trusting it. We built an adversarial fault matrix of nine ways a run can go wrong, from a link-breaking deletion to the subtle case of removing one load-bearing fact in a way that passes every structural check. The gate rejected all nine and restored the corpus each time, while a maintainer that commits without checking corrupted the corpus in every one.

The runtime and the format

Everything so far concerns when GROOM acts and how it keeps the acting safe. None of it concerns what a page looks like on disk. That separation is where Google’s Open Knowledge Format fits.

Two ideas are easy to blur. A format is how knowledge is written down: the shape of a page, the metadata it carries, how pages link to each other. A runtime is the machinery that decides when to act and keeps the acting safe: the trigger, the gates, the checkpoint, the journal.

GROOM is a runtime. It shipped with its own plain format, markdown plus a little YAML frontmatter: a title, a summary, some tags, an updated date, a confidence level. The runtime does not read the frontmatter to do its job. The loop, the gate, and the journal read and write files, and the shape of the metadata belongs to whoever defines the format.

In 2026 Google published the Open Knowledge Format^[5], a vendor-neutral way to write a knowledge base as a directory of markdown files with YAML frontmatter, so different tools can share one corpus instead of locking it inside a product. OKF is a format and stops there. Its specification lists serving, storage, and querying as explicit non-goals. It says how to write knowledge down, and says nothing about keeping it fresh or editing it safely.

Freshness and safe editing are exactly what GROOM does. So we taught GROOM to speak OKF. Point it at an OKF corpus and the same loop, gate, and journal maintain it, with no change to the runtime.

GROOM supplies the maintenance OKF leaves open. OKF supplies the portability GROOM’s own format lacked. The two compose.

Speaking OKF is close to a rename. You can trace it field by field below.

The mapping is mostly dull, which is the point. title and tags carry over unchanged. GROOM’s summary becomes OKF’s description. GROOM’s updated date becomes OKF’s ISO-8601 timestamp. GROOM’s confidence has no OKF field, so it travels as a namespaced extension key, which OKF requires consumers to preserve rather than discard. The page body and every field of real data survive byte for byte. The one thing the round trip adds is a type field OKF requires, which GROOM has no source for and synthesizes on export.

These are real corpora, not fixtures we built. We pointed GROOM’s validator at three OKF knowledge bases Google published, a Bitcoin reference, a Google Analytics reference, and a Stack Overflow export, with no per-corpus configuration. All three parsed with zero errors, and every round trip came back content lossless.

Support is opt-in, one line of config. A team already on OKF points GROOM at the corpus and gets self-maintaining knowledge with no migration. A team on the native format keeps everything it has and can export to OKF whenever it wants a corpus other tools can read.

What we measured

The claims above rest on measurements. Here are the four that matter most, each with its limit.

50 ms

warm median for the launcher’s gate check, so reads do not pay for maintenance

9 / 9

adversarial bad edits rejected by the gate; recovery near 13 ms over n = 450

0.52 → 0.78

lexical retriever recall@1 on a degraded corpus, after grooming

~half the age

mean page age for the hottest tenth, in simulation, vs an equal-budget round-robin schedule

Being triggered is cheap. The number is a warm median: the first check of a session pays a one-time spin-up, and the gate degrades to the corpus as it stands rather than blocking when it runs long. The reader is never on that path.

It is safe. The nine cases were chosen to be hard, from a link-breaking deletion to a single dropped fact that clears every structural check, and the revert is a git reset --hard to the checkpoint, which is why it is fast.

It targets the right pages. This is the payoff of attention-weighted maintenance, measured against an equal-budget round-robin that spends the same work spread evenly. We ran it on a simulated corpus of 500 pages with reads drawn from the power-law skew real corpora show, the top tenth of pages taking most of the traffic. We have not yet reproduced the gap on a live corpus.

It helps everything downstream. Fixing the content, not the index, lifts every retriever sitting on top of it. A lexical retriever’s recall@1 rose from 0.52 to 0.78 overall after grooming, and a neural one from 0.56 to 0.81, so the gain is not an artifact of one matching method. The size of the gain tracks how degraded the corpus was, which the figure below breaks down by domain.

We are clear about the limits. The timings come from one machine. Canaries certify the facts they pin, not the rest of a page. Ingestion through expand and research opens an injection surface that GROOM gates without closing. The strongest claim, a sustained end-to-end win in production, is the open problem. The technical paper carries the full evaluation of each.

Running GROOM

GROOM is open source, and the fastest way in is to install it as a Claude Code plugin. Add the marketplace, then install the plugin:

/plugin marketplace add beconfident-ai/groom
/plugin install groom@groom

After that, consulting the wiki starts the background refresh on its own, the way the loop above describes. You can also run an operation by hand:

npm run lint      # fix form, links, frontmatter
npm run prune     # consolidate redundancy
npm run expand    # fill a flagged gap from the web
npm run iterate   # improve the single weakest page

GROOM is not Claude-only. It ships rule files for other agents, so a Gemini, Cursor, Windsurf, Cline, or Copilot agent can drive the same pipeline. It also maintains an OKF corpus in place of GROOM’s native format, no migration needed.

Knowledge you keep

A knowledge base is not a document you finish writing. Someone, or something, has to keep it current, and that job does not end. We built GROOM on a bet: the cheapest time to do that work is the moment an agent reaches for the knowledge, because a consultation and a maintenance pass are the same event seen from two sides.

Reading is the trigger. The gate makes the writing safe. The journal keeps the record honest. Because the runtime never reads the frontmatter, the same machine maintains GROOM’s own corpus or an Open Knowledge Format one. Stale-while-revalidate, for the things your agents are supposed to know.

Want the rigorous version, with the full evaluation, the related work, and the limitations in detail? Read the GROOM paper →