Knowledge as Code

AI did not create the knowledge management problem; it exposed how little of what we actually know was ever written down in a form that survives a tool change, a staff departure, or a single agent session.

The fix is not a better database. It is treating knowledge the way we already treat code: curated, versioned, linkable, and legible to humans and machines at the same time. I call that posture knowledge as code. Every document need not look like source code.

The durable unit of organizational memory behaves like a file in a repo: reviewable, diffable, and portable when the platform changes underneath you.

Four Jobs, One Method

For most of my career I kept four professional identities in separate drawers. Software developer. Content strategist. Writer-researcher. Genealogist and family-history archivist. Each drawer had its own tools, its own filing system, its own tacit rules about what counted as “done.”

Agentic tooling collapsed the drawers. The domains did not merge. The method did. I started advancing a corporate proof registry, a newsletter engine, a family archive, and a volunteer genealogy database with the same instinct: write it down in plain text, add enough structure for a machine to route it, and keep enough prose for a human to judge it. The domains stayed unlike. The contract did not.

That convergence arrived before I had vocabulary for it. I only noticed the pattern after the fourth system looked familiar.

The Same Shape in Four Unlike Places

In the newsletter content system, every essay carries an intent graph, an evidence packet, and passage modules: markdown files with frontmatter that tell an agent what the reader is trying to decide, which claims are evidenced, and which sections must survive extraction on their own. The prose is human. The scaffolding is machine-legible.

In the corporate proof-point registry, each claim lives in its own file: a proof point (CP) or capability statement (CS), each with its own identifier, SME review status, source tier, retirement notes when a proof point ages out. One entry, one file, one audit trail. When CP-007 retired, the retirement reason stayed in the record. That negative knowledge (what we no longer assert, and why) is as load-bearing as the claims still in circulation.

In the family-history archive, merge cautions and evidence tiers sit beside positive findings. A failed archive search gets logged. A tentative link carries its doubt on the surface, not buried in a footnote someone will never reopen.

At institutional scale, JRI-Poland’s NextGen consolidation faced the same structural problem from the opposite direction: more than two thousand spreadsheets, a “data carwash,” and the slow work of making scattered institutional memory legible enough to survive the next platform migration. The scale differs. The metabolism problem does not.

Four unlike domains. One recurring shape: curated text, versioned, linkable, with metadata that outlasts any single application.

Google’s Open Knowledge Format spec arrived late in my noticing, which is often how standards work. OKF describes vendor-neutral markdown plus frontmatter for knowledge interchange. I had been living a parallel version in four repos. The spec did not invent the idea for me. It named a pattern others were converging on independently, which is the strongest signal that a contract is real.

The Knowledge Stack

Once you see the convergence, you need a model that separates what gets confused in conversation. I call it The Knowledge Stack. Three layers, not three products.

• Substrate is the portable file: plain text plus metadata in a shape that survives export. This is the OKF-shaped layer. What lives here should still make sense if you change tools tomorrow.
• Semantics is domain meaning layered on the substrate: content pillars, proof-point IDs, evidence tiers, passage identifiers, merge cautions. This is what keeps an agent from treating your notes as undifferentiated prose.
• System is the workflow and governance that produce and consume the files: skills, MCP connectors, quality gates, SME review, the habits that turn a folder into an institution’s memory rather than a graveyard of drafts.

Most market talk collapses Substrate and System. People buy a platform and call it “knowledge management.” Or they write markdown and assume structure will emerge. The practical contribution is separating them. The file is not the whole answer. Neither is the agent. The contract is the stack.

Why Agents Need All Three Layers

The objections arrive in predictable order.

• “This is just docs-as-code.”
  • Docs-as-code gives you versioning. It does not give you semantics an agent can trust, or governance that tells you when a claim has expired. My proof registry files carry review status. My archive files carry evidence tiers. That metadata separates retrieval from hallucination with citations.
• “Frontmatter without discipline is metadata theater.”
  • Correct. Which is why System matters. SME review on corporate claims. Guardrails in the family archive that force negative results into the record. An intent graph that lists unsupported claims before prose gets written. Structure without discipline is performance. Structure with discipline is infrastructure.
• “Won’t the database or RAG handle this?”
  • A database row is excellent at storage. It is poor at human judgment on the way in and poor at portability on the way out. RAG without a curated substrate sends an agent shopping in a warehouse with no aisle labels. The agent needs bounded context drawn from files a human already agreed were worth keeping.

Production systems and builder tooling are converging on the same shape from different angles. I will unpack that journey in a later piece. For now the lesson is simpler: if your knowledge cannot survive a tool change as a file a human can read, it will not survive an agent session either.

Start With One File Worth Keeping

You do not need to rebuild everything. You need one file format your future self and your future agents can both trust, then one habit that keeps it honest.

Pick a domain where a wrong answer has cost you time: a client claim, a family link, a product assumption, a policy interpretation. Export or write one markdown file with frontmatter that states what the file is for, what confidence level applies, and what would falsify the claim. Link to sources. Log what you tried and rejected. If a proof point retires, say so in the file and keep the file.

That is the thin-export move. One durable unit. Versioned. Reviewable. Negative knowledge included.

In When the Work Learns to Look Like Data, I argued that dashboards teach organizations what to feed them. Knowledge as code asks the prior question: is the underlying knowledge written in a form durable enough to feed anything?

The institutions that metabolize change fastest are not the ones with the most data. They are the ones whose connective tissue is written in a form that survives the next departure, the next vendor swap, and the next model upgrade.

Knowledge as code is not a technology trend. It is the minimum viable contract for an organization that intends to remember what it learned.

This continues the thread from Designing for Absorption: the bottleneck was never capture alone, but whether what gets captured can be integrated, reviewed, and reused when the platform changes. Knowledge as code is what that integration looks like when agents join the workflow.

Forward this to: knowledge management leads and AI operators who are being asked to “turn on RAG” before anyone has decided which institutional memory is worth encoding, and to builders running personal and professional systems in parallel who keep rediscovering the same file shape in unrelated domains.

A Question for You: In the system you trust most today, what happens to the knowledge that turned out to be wrong? Is it still there, labeled, and readable? Or did it disappear when the project closed?

Madam I’m Adam