← Particulars

Comparison

Particulars and OKF

Google Cloud’s Open Knowledge Format (OKF) and particulars, the Dialectical Knowledge Format, solve neighbouring problems in a similar way. Where they differ is what happens when a belief changes — and that is also where they fit together.

Describes OKF v0.2 · last checked 2026-11-02

What both share

Both are open, vendor-neutral formats made of plain text files that live in git, are readable without special tooling, and are written by people and AI agents alike. Both record where knowledge came from and how far to trust it. If you value knowledge you can cat, diff, review in a pull request and carry between tools, either format gives you that.

Where they differ: how a belief changes

In March, Priya owns the billing service. In June, Ada takes over. Here is the same change in each format.

One change, two update models In OKF, the March concept file says Priya owns billing and carries a stale_after date. In June an agent rewrites the same file to say Ada owns billing and updates generated.at; a log.md line records the edit in prose, and the earlier version survives in git history. In particulars, the March claim stays as written; a June claim that Ada took over challenges it, and a synthesis reconciles the two, citing both claims, keeping the reasoning and declaring what remains open. OKF · a document, rewritten particulars · claims, reconciled ownership/billing.md “Priya owns billing.” stale_after: 2026-09-30… March rewritten in place ownership/billing.md “Ada owns billing.” generated.at: 2026-06-12… June · the same file log.md · Update: … earlier text: in git history current and correct — the why lives outside the knowledge “Priya owns billing.” claim · March · thesis challenged “Ada took over billing.” claim · June · antithesis reconciled “Ada owns billing since June 12.” cites both claims · keeps the reasoning unresolved: who covered the handover synthesis · CURRENT current and correct — the why is part of the knowledge
Both end up saying Ada. They differ in where the reason for the change lives.

OKF: freshness declared in advance, documents rewritten in place

An OKF concept is one markdown file. Its producer can set status (draft, stable or deprecated) and stale_after, an absolute instant after which the concept counts as stale. The spec expects agents to keep concepts current by rewriting them — it notes that “agents constantly rewrite these documents” — with generated.at marking the last meaningful change and an optional log.md recording edits in prose. That is simple, fast to read and easy to serve.

What the format does not have is a place for a disagreement. If two sources say different things, or the reasoning for a change matters later, that lives in commit messages and log prose rather than in the knowledge an agent reads. And stale_after is a prediction: a fact can go wrong before its date or stay right long after it.

Particulars: staleness detected by contradiction, reconciled with reasons

A particulars claim is never edited. When something contradicts it, the new claim is recorded next to it, and a synthesis reconciles the two: it cites both, carries the reasoning, and says what is still unresolved. The synthesis becomes the current belief, and can itself be challenged. A belief goes stale when evidence against it arrives, not when a date passes — and an agent reading it inherits the argument, not just the answer.

The cost is more structure: claims, syntheses and roles to learn, and a record that grows by appending, so you rely on tooling to show you the current state.

A date tells you when to doubt. A contradiction tells you what changed.

Provenance, compared fairly

Both formats take provenance seriously, at different grains.

OKF

A concept lists its sources, each with objective credibility signals (author, usage_count, last_modified). A sentence in the body can be attributed to a source with a footnote keyed to that source’s id. generated and verified record who wrote and who confirmed the concept, and consumers derive a trust tier from them: unverified, machine-confirmed or human-reviewed.

Particulars

The unit is a single claim, and it is immutable. Each records who asserted it, through which harness and model, from which document — with the supporting quote and a hash of what was read — and whether it was observed, inferred from other claims, or simply held as a position. A wrong claim is retracted with a reason, never rewritten.

The difference is not attribution versus none. It is the unit of change: a document that is rewritten, or a claim that is superseded.

Using them together

An OKF bundle makes a good source for particulars claims. Because a claim keeps a verbatim quote and a hash of what it read, it stays honest even when the document it cites is rewritten.

# claims/clm_….yaml — illustrative
subject: par_…               # the billing service
content: Ada owns the billing service.
evidential: observed
source:
  author: https://github.com/ada
  harness: claude
  document:
    ref: https://github.com/acme/knowledge/blob/4c1e…/ownership/billing.md
    hash: sha256:9f2b…    # the OKF concept as it was read
    quote: Ada owns billing.

Each format then supplies a signal the other lacks:

OKF tells particulars when to look

When the cited concept passes its stale_after, or moves to deprecated, the claims that cite it are due a re-check.

Particulars tells OKF what moved

Re-reading the concept compares the quote and the hash. The quote gone means the cited text changed; the quote present but the hash different means the text around it did. Either way the claim stays readable — drift is a prompt to re-read, not an error.

When the re-read turns up something new, it becomes a new claim, and the disagreement — if there is one — becomes a synthesis. The OKF bundle stays the readable current view; particulars keeps the account of how it got there.

What each one covers

OKF covers “the metadata, context, and curated insight that surrounds data and systems”. It deliberately fixes no taxonomy of concept types: a bundle can hold tables, datasets, metrics, attested computations — sanctioned ways to compute a number, with a check that it was computed that way — and procedures such as incident playbooks. Here OKF is broader than particulars.

Particulars is semantic memory with provenance: what is believed about things in the world, and why. It leaves procedural memory (how to do things) and episodic memory (a log of what happened) out of scope on purpose; an event can be the subject of claims, but a log of events is not the format’s job.

Neither standardises episodic memory: OKF’s log.md records edits to a bundle, not events in the world. If you need a runbook, OKF has room for it. If you need to know why the runbook’s owner changed and whether everyone agrees, that is a job for particulars.