Notes written while you're in the middle of trying something out are good at recording results and reflections, but keeping the flow that led to those results as structure is surprisingly hard. The procedure that lived only in someone's head at the time, the implicit assumptions that didn't make it onto the page, the judgment calls that got summarized away in meeting decks — when you read the notes back years later, those rarely survive together.
I felt this myself. More than ten years after stepping away from active experimental work, I tried to recall the flow of one of those experiments. What I had left were fragmented notes and a few meeting decks. The results were there, but the flow that led to them had thinned out over time.
There is advice that says: write the procedure as a flow chart in your notebook. Even so, notes written in the moment tend to be results-centric, and keeping the flow recorded as structure on top of that takes more effort than expected. For reproducing or revisiting work later, having a setup that records the flow as structured data alongside the results would be valuable.
Japanese cooking has a saying about "sa-shi-su-se-so" — adding sugar, salt, vinegar, soy sauce, and miso in that order changes the taste. The same is true anywhere you're trying things — experiments, recipes, code, drafts. What you add when, in what order, how long you wait — those choices shape the outcome. The flow is making the result.
So I wanted a way to keep "what came from what, through what flow" — that causal data — as a structured record. There is also another reason: this kind of data feels especially interesting in an era when AI starts handling the data of trial-and-error work itself.
PROV-DM as the missing model
That is when I came across PROV-DM (Provenance Data Model), a W3C standard for describing what was made, from what, and how. It defines three primitives — Entity, Activity, Agent — and the relations between them.
Academic data systems use it. Personal notes apps don't, as far as I can tell. But the daily output of anyone trying things on the ground already fits this shape. A researcher writing "I heat-treated Sample A and got Sample B" and a baker writing "I added sugar before salt and the texture changed" both describe, in PROV-DM terms, "Entity B was generated by an Activity from Entity A." With this, I had a way to keep the flow of trial and error — the part that used to live only in my head — as structured data.
Another layer of provenance — same model for edit history
Looking deeper into PROV-DM, I realized the same data model also fits document edit history, not only content provenance. In fact, that may be closer to what PROV-DM was originally designed for.
So in Graphium, I track provenance in two layers:
- Layer 1: Content provenance — the experimental workflow (Sample A flowing into Sample B, and so on)
- Layer 2: Document edit provenance — who edited what, and when
Layer 2 maps the editor (human or AI) to prov:Agent, edit operations to prov:Activity, and document revisions to prov:Entity. The fact that both layers describe themselves in the same PROV-DM vocabulary felt like the right design choice to me.
Both layers gain weight in the AI era
I think both layers grow in value as AI becomes part of the picture.
Layer 1 keeps the procedure inside a note as causal structure. When inputs, steps, and outputs are connected as a causal flow within the same note, you — or an AI reading that note later — can trace the flow at a higher resolution. As AI starts handling this kind of trial-and-error data, structured procedures themselves gain value as material that can be analyzed or reused.
Layer 2 matters when AI-written and human-written content start mixing in the same notes. As AI writes parts, summarizes, or edits, being able to tell later "this was my own observation, this was added by AI" matters when you re-read your own work or share it with others. Just having "AI or not" recorded as Agent gives that distinction a place to live.
The same "what came from what" question applies far beyond lab work. Recipes, software change histories, medical records — the shape is the same. That's why the header image of this post is a bread-making note rather than a chemistry experiment.
Recording it without making the user edit a graph
Asking users to author a graph directly is a non-starter. So Graphium maps PROV-DM onto the grammar of the document itself: headings become Activities, and short inline highlights inside headings turn the named term ("NaCl", "80°C", "clear solution") into Entities.
The writing experience stays "type a heading, write a paragraph, occasionally highlight a word." The provenance graph is a computed view — never something you edit by hand.
Coexisting with knowledge links
Not every link should be causal. "This paper was interesting" or "this concept resembles that one" are non-directional. Forcing causality on them is unnatural.
So Graphium splits them. @ mentions default to knowledge links (no direction, cycles allowed). Relations between inline highlights inside heading scopes are provenance links (directed, acyclic). Same act of writing, two different graphs underneath.
