Curated Knowledge for Humans and Agents

Substrate for Managing Shared Knowledge

Most knowledge and memory systems are concerned with storing information, and if you’re lucky, organizing it. Facts is concerned with deciding what information becomes knowledge, and when, and on whose authority. The CLI is a zero-config, fast, malleable substrate for managing trusted knowledge, and the basic unit is a proposition, a statement that can be evaluated as either true or false. Proposing one doesn’t make it a fact. It sits pending until an actor decides.

$ fact propose policy.md
$ fact pending

01a00-9ef94  pending, update pending  Policy v0  [accept or reject]

$ fact accept 01a00-9ef94

That small distinction is the whole system. A wiki can tell you somebody wrote this. A ledger can tell you somebody proposed this, these actors considered it, this revision was accepted, and this is the version currently treated as fact. What matters for humans matters more for agents, since an agent has no way to tell an opinion from a decision unless the record says which one it’s reading.

Version-Controlled Knowledge

Facts applies some of the useful properties of Git to knowledge. When someone learns that an accepted fact is incomplete, they revise it, and the old revision doesn’t disappear because somebody edited some text. fact show lists the accepted revision alongside its proposed replacement, and the replacement doesn’t become effective merely because it’s newer. It has to earn that status. fact history keeps the sequence intact: proposed, accepted, revised, commented, accepted, archived, restored. Knowledge changes over time, and the history explains how and why.

Information is Accumulated. Knowledge is Curated.

Consider a company wiki. Someone adds “Customers on the Enterprise plan receive 24-hour support” and it’s searchable immediately, which is useful if the statement is correct and expensive if the person misunderstood the policy. Import that same statement into a ledger and the system retains it without treating it as accepted knowledge. A reviewer looks into it and rejects it. The proposition stays in the history, it just never became a fact. “We considered this” isn’t the same thing as “We believe this is true,” and only one of the two should be feeding your agents.

Actor-agnostic Knowledge Management

Facts doesn’t care whether an actor is a human, an agent, a service, or an organization. fact as registers one with a public/private signing key pair and permissions to participate, so an agent can propose a runbook, a second agent can comment that it contradicts the one in production, a human can reject it, and any of them can invite specific reviewers to a specific proposition. The point isn’t human approval. It’s controlled knowledge formation. Humans can supervise agents, agents can supervise agents, and both can participate in the same decision.

Safer AI Agent Memory

The common agent memory loop looks roughly like this:

The danger is obvious once you draw it. An agent makes one bad inference, “Customer X never wants email notifications,” commits it to memory, and a future agent retrieves it as context. A mistake gets committed as truth, and if that memory is shared, that’s a catastrophic failure. Facts puts a decision boundary in the middle:

The agent stays free to learn, propose, and revise. What changes is that an agent querying accepted knowledge doesn’t see the inference until a human, another agent, or several participants have signed off on it. Consider this: put two agents on the same ledger and neither one can write to shared memory without the other reviewing it first. Every claim gets checked while the work is still in flight, which is what CI does for code, applied to knowledge.

Don’t Go Fishing

The prevailing enterprise AI architecture looks like this: Give the agent(s) access to repositories of context and wish it luck:

Every task starts with the same questions. Which document is current, which statement was superseded, was this proposal ever approved, and which of these three policies is authoritative. Raw information can stay where it is. Curated knowledge lives in the ledger, and tags narrow the search further.

$ fact find "production database access" --tag network --tag policy

019f91-a2f91  Production database access requires VPN
019fa8-3cfa8  Production credentials rotate every 30 days
019fa9-92fa9  Production writes require an approved change

Three accepted facts instead of four thousand search results, and if the agent needs supporting material it can go fishing afterward. Facts first, raw information second, instead of searching everything and hoping retrieval found the right answer.

Simple Primitives, Lot of Shapes

Propose, revise, comment, accept, reject, find, pull, push. Those primitives compose into personal memory, team decisions, engineering conclusions that would otherwise die in chat, runbooks written the day after an incident, curated requirements an implementation agent can query, and overnight agent findings a human triages in the morning. The same handful of commands also arranges into very different systems depending on how many ledgers you keep and who holds which permission.

Facts as a Substrate: Ten Topologies

Two of those are worth spelling out. Consensus records every position and lets policy decide whether the proposition becomes effective, which is a different thing from “Agent A wrote something to memory, therefore it is memory,” and you can deliberately mix models, agents, and tools so that their failure modes are less correlated. Escalation turns fact conflicts and fact pending into the human’s inbox, so people spend their attention on the contested cases instead of reviewing every memory update.

Hot-Swappable Memories

If Agent A owns its memory, retiring it next year is a migration project. If the organization owns the ledger, the replacement starts with the same accepted knowledge on its first day.

Models change, frameworks change, vendors change, and agents come and go. The ledger remains. Facts doesn’t try to predict the application, it provides the substrate, and underneath every one of these shapes is the same distinction. “Someone said it” is information. “We accepted it” is a fact.