The problem
Your agents are producing research you can't audit
An agent reads twenty pages, synthesises a conclusion, and writes it into a markdown file. Six weeks later the conclusion is load-bearing and you want to know: which of those twenty pages actually supported it? Were any of them the same wire story republished four times? Did anyone read the primary, or did the model summarise a summary? Half the URLs now 404.
The LLM-wiki pattern gets you a knowledge base an agent can read. What it deliberately leaves open is lineage — and lineage is the part you need precisely when the stakes have risen enough that you're asking.
flip is the layer that closes it. It is not a retrieval system, a vector store, or an agent framework; it sits underneath those and holds what they produced, in files that outlive all of them.
What is actually enforced
Four rules, and a CLI that will not let you skip them
Every fragment below is real output, generated by running the CLI when this page was built.
At rest
It's a directory. That's the whole trick.
A flip notebook is an
Open
Knowledge Format v0.1 knowledge bundle at rest — not an export target [C3].
Markdown pages with YAML frontmatter, an index.md root, a generated
log.md. Any OKF consumer can browse one. Any markdown editor can
edit one. Open it in Obsidian and the frontmatter is the properties panel — a
human re-grading a source from that panel is a legitimate flip operation, not a
corruption to be repaired.
What flip adds on top is an extension profile for lineage: the custody rules, the grading vocabulary, the corroboration bar, and the session log. Sources are one page each. Claims are one page each. Events are append-only JSONL. Nothing is deleted to keep context small — the hot view is computed.
Choosing a substrate
What you're actually choosing between
These differ in kind, not in quality. None of them is trying to be the others, and there is no score to add up.
| Dimension | flip notebook | Plain markdown in a repo | PKM vault (Obsidian, Zotero) | RAG / vector store |
|---|---|---|---|---|
| Canonical at rest | Markdown pages + append-only JSONL | Markdown files | Markdown files, plus an app database | Embeddings in an index |
| What it enforces | Custody before citation; grading as a separate act; a corroboration bar on verified |
Nothing — convention only | Schema and citation style; not evidence standards | Nothing about provenance; retrieval relevance only |
| Downstream verifiability | Local bytes + sha256 at capture; the reasoning chain is in the bundle | Whatever the author wrote down | Reference metadata; usually not the bytes | Chunks, typically without the original custody trail |
| Required services | None. Two libraries; no network or LLM calls in the core | None | The application | An index, and usually an embedding provider |
| If the tool is abandoned | Still a valid OKF bundle and a readable directory | Still files | Files survive; the app's derived layer does not | The index is the artifact; it goes with the tool |
flip's own non-goals rule out replacing judgment with a composite trust score. It would be poor form to publish one here.
Before you adopt it
The honest case against
The strongest objection is that this is ceremony. Metadata discipline that raises the cost of every capture without changing what the agent concludes — and worse, grades assigned carelessly by the same model that wrote the claim, which would make the whole apparatus decorative.
That objection lands, and the honest answer is structural rather than
promotional. Grading is a separate recorded act by a named actor. Ungraded
sources count toward nothing at all. flip doctor makes the gap
between "captured" and "judged" visible instead of letting it hide. That is a
design which surfaces carelessness. It is not a claim to prevent it, and
you should not adopt flip expecting it to.
No adoption evidence
There are no users to count, no case studies, no testimonials. The test count below measures test functions in the repository — it says the implementation is exercised, not that the format works in the field.
No effectiveness measurement
Nothing here shows that notebook-backed agents produce better research than agents without notebooks. That reuse gets materially cheaper is the project's bet, recorded as an unconfirmed claim [C5] rather than quietly asserted.
The OKF profile is a draft, submitted nowhere
flip's provenance vocabulary is proposed as an OKF extension profile in the repository. It has not been submitted to, reviewed by, or endorsed by OKF or its maintainers. Whether it should be is an open question in the spec, and an open question in this site's own notebook — a live flip notebook you can browse: every claim this page makes traces to a graded source there, including a superseded claim kept on the record when OKF moved from v0.1 to v0.2. For a notebook built the way flip is actually used — an agent doing directed research in conversation, with the human never touching the CLI — see flip-examples: real NJ enrollment data, hashed captures, and claims verified by recomputation.
The spec is draft v0.11
Not 1.0 and not frozen. flip migrate exists because the format has
moved before and may move again. Notebooks migrate in place.
Where this stands
Coordinates
This site's own lineage
The claims on this page, and what backs them
Generated from this site's flip notebook by
flip export json at build time. One claim is unconfirmed and one
needs a second source; both are shown as they are.