Start here

Core ideas

Five words explain all of Stale: node, source, stale, taint and firewall. Learn these and every screen makes sense.

Nodes: four kinds of knowledge

Everything Stale remembers is a node, and every node has a kind.

from a source

Fact

Something someone said or wrote. “Support SLA is 4 hours.” Always tied to a source and the exact quote.

derived

Belief

A conclusion built from other nodes. “Premium customers get priority.” It depends on facts.

derived

Decision

A choice that rests on beliefs and facts. “We will staff the night shift.”

does something

Action

Something an agent or person intends to do. “Wire $48,000.” Actions are the only thing the firewall stops.

Nodes link with DEPENDS_ON edges. A decision depends on the beliefs it uses, and a belief depends on the facts behind it. That chain is the whole point.

Sources and trust

A source is where a fact came from: a Slack channel, an email thread, a repo, a page. Every source is either trusted or untrusted.

Your team, in your own channels, is trusted.
Guests, shared channels, bots, strangers on public repos and unknown email senders are untrusted by default.
You can quarantine or restore any source at any time, and everything downstream updates instantly.

What “stale” means

A node is stale when anything it depends on has changed. If a fact is replaced, Stale walks the DEPENDS_ON edges and marks everything above it, however deep.

A node’s status is valid, stale or superseded (replaced by a newer version, kept for history). Staleness is reachability, not a timer, so it only appears when something actually changed.

Taint: a stranger’s words can’t act

A node is tainted when any path of dependencies leads back to an untrusted source. Taint is computed live from the graph and never stored, so quarantining a source taints everything downstream immediately, and restoring it clears the taint.

The firewall

Every action goes through a check before it can run. An action is blocked if it is stale or tainted, and blocked actions cannot execute.

check_action returns allowed plus the exact path that caused a block.
A human can approve a blocked action. The approval is tied to the action’s ancestry at that moment, so if a new problem appears upstream later, the approval is withdrawn.
Agents cannot approve. There is no approve tool in MCP, on purpose.

Repair: fixing stale knowledge in order

repair_plan lists stale nodes in layers, root-first. Layer 0 must be rechecked first, because everything above it depends on it. resolve revalidates a node (optionally with corrected wording) and rebases it onto the newest version of its parents. It refuses while any parent is still stale.

The review queue

When Stale reads a message it decides: confirm (same as before), add, or supersede (contradicts something). Safe changes apply automatically when your workspace is set to autoApply: trusted. These wait for a human:

`untrusted-source`	The claim came from a stranger.
`low-confidence`	The extractor wasn’t sure what was said.
`possible-conflict`	It might contradict a fact, but isn’t clearly the same subject.
`policy`	The workspace is set to never auto-apply (`autoApply: never`).