Ai on Prskavec.Net

A Knowledge Format Is Not a Knowledge Base

ladislav@prskavec.net (Prskavec.Net) — Thu, 16 Jul 2026 09:00:00 +0200

Google’s Open Knowledge Format sounded relevant to me immediately. OKF v0.1 is a directory of Markdown files with YAML frontmatter, stored in Git and readable by people and agents. That is close to how I already use Logseq, Codex, and Claude Code with my own knowledge base.

After reading the specification, I do not think I should adopt it. OKF could be an export format one day, but it leaves out too much of what makes a knowledge base useful.

First, a correction: OKF is not another markup language. It is a small profile on top of Markdown and YAML. The required surface is deliberately thin: every concept is a file, its path is its identity, and its frontmatter must contain a type. Titles, descriptions, tags, resources, timestamps, indexes, logs, and citations are optional or recommended.

That simplicity is attractive. It also standardizes the least difficult part of a knowledge system.

Backlinks are part of the data model

OKF defines a link from concept A to concept B as a directed, untyped edge. The meaning, such as “depends on”, “references”, or “joins with”, stays in the surrounding prose. A consumer may scan the bundle and compute the reverse edge, but the format does not require it.

This distinction matters. In Logseq, a backlink is not decoration in a graph view. When I open B, I can see every page that mentions B, including connections I did not remember to encode on B itself. The forward link records what the author of A knew. The backlink shows how the rest of the corpus has accumulated around B.

Adding an explicit link from B back to A is not the same thing. It duplicates the edge and may misstate the relationship: “A references B” does not imply “B references A”. It also creates a synchronization problem when pages move or relationships change.

An OKF consumer can reconstruct backlinks. Google’s reference visualizer does this and presents them as “Cited by”. But another consumer can ignore reverse links and still conform to the specification. Both tools support the same format while exposing materially different knowledge bases.

Conformance does not imply shared meaning

The rest of the interoperability contract is similarly thin. type is the only required field, but type names are not registered. Consumers must tolerate unknown values. Links are untyped. Citations are recommended rather than required. Broken links are explicitly permitted.

These are sensible choices for a forgiving file exchange format. They also mean that two conformant bundles can agree on syntax while disagreeing on nearly all of the semantics. One producer’s Playbook may not resemble another’s. A consumer can parse both files without knowing how to compare, validate, or use them.

That is portability of text. It is not yet portability of knowledge.

We already have document formats

If the problem is how to store rich, readable technical documents in plain text, we already have mature options. reStructuredText has field lists, citations, hyperlink targets, directives, and extensible interpreted-text roles. AsciiDoc has document attributes, document-to-document cross-references, and includes.

Neither format gives every tool Logseq-style backlinks automatically. That is the point: backlinks are a corpus-level index and navigation contract, not an inline-markup feature. Putting YAML in front of Markdown does not solve that layer either.

Markdown plus YAML is a reasonable transport choice with modest parsing requirements. But choosing a transport is different from defining a knowledge architecture. If a team prefers AsciiDoc or reStructuredText, it should not need to convert its source documents just to participate in a knowledge exchange. A useful standard could define concepts, identifiers, relationships, provenance, and lifecycle independently, then provide mappings for several text formats.

Markdown is the least interesting part of my knowledge base

My setup works because it is selective. Journals are a raw inbox. External sources are retained locally when needed. Durable pages are synthesized rather than copied. Claims carry source notes with searchable anchors. A curation log records what was promoted, skipped, or left for later. Every page edit is reviewed against its sources instead of trusted because the prose sounds coherent.

None of that follows from the file extension.

A directory can be perfectly conformant with OKF and still be a bad knowledge base: duplicated notes, stale claims, missing provenance, disconnected pages, and generated summaries nobody has checked. An agent can parse the corpus, but parsing is not the same as trusting or navigating it.

For me, a stronger interchange model would need at least:

stable concept identifiers that survive file moves
standardized backlink or reverse-edge behavior
relationship types that consumers can understand without reading prose
claim-level provenance, not only an optional citations section
a way to distinguish raw capture, durable synthesis, and deprecated material
mappings for existing systems and formats instead of one mandatory source syntax

This does not all need to live inside every document. A manifest or generated graph index may be better than duplicating metadata across files. The important part is that the behavior belongs to the contract, so each consumer does not invent it again.

Where OKF could still fit

OKF may become useful as a lowest-common-denominator export. If an agent or catalog I want to use accepts OKF, a Logseq plugin could map page properties to YAML, convert wiki links to Markdown links, and generate a backlink index. My knowledge base would remain the source of truth.

I would not build that adapter before there is a consumer worth using. OKF is still a v0.1 draft, and changing a working knowledge base to satisfy a thin interchange profile would add maintenance without improving the knowledge.

The problem is real: agents need portable context, and knowledge should not be locked inside one vendor’s catalog. But a collection of readable files is only the substrate. A great knowledge base also needs relationships, provenance, selection, and maintenance. Another file profile does not provide those by itself.

Sources

Google Cloud, Introducing the Open Knowledge Format (2026-06-12)
Open Knowledge Format v0.1 draft specification
Open Knowledge Format reference implementation and visualizer
Docutils, reStructuredText Markup Specification
Docutils, reStructuredText Interpreted Text Roles
Asciidoctor, Document Attributes
Asciidoctor, Document to Document Cross References
Asciidoctor, Includes

How I Use Logseq as a Personal Knowledge Base

ladislav@prskavec.net (Prskavec.Net) — Sat, 27 Jun 2026 09:00:00 +0200

This setup was inspired by Andrej Karpathy’s LLM Wiki, but my version is deliberately local and boring: Logseq journals as the inbox, source files as the archive, and compact pages as the durable layer.

Google is making a similar argument with Open Knowledge Format: Markdown plus YAML front matter as a shareable knowledge format. I think the format is the easy part. Markdown, reStructuredText, AsciiDoc, or any plain text format with metadata can work. For company-wide use, the harder part is the documentation pipeline: how you ingest sources from different places, keep them fresh, and assign curators, human or LLM, to maintain the useful layer.

My Logseq graph is not where every thought becomes permanent. It is where raw material waits until I decide whether it deserves a second life.

The split in this repository is blunt:

journals/ is the raw inbox.
sources/ is where bulky external material lives.
pages/ is the durable knowledge layer.
log.md is the audit trail of curation work.

Day to day, that is not formal. I capture links, screenshots, meeting fragments, commands, papers, talks, and half-formed notes into Logseq journals. Later, I run a curation pass and promote only the material I expect to search for again.

The flow

Journals are the inbox

Daily journals are intentionally messy. They contain:

links I may or may not read later
meeting scraps
debugging notes
command fragments
screenshots
TODOs
short observations
notes for work projects

I do not try to make journals beautiful. If I had to polish every note at capture time, I would capture less.

The rule is that journals are source material, not the knowledge base. Most journal bullets should never be promoted. TODO-only items, meeting logistics, unexplained fragments, and one-off status updates usually stay where they are.

What gets promoted is the material with reuse value:

architecture decisions
operational patterns
incident/debugging lessons
recurring themes
commands with explanation
glossary terms
papers, talks, docs, and articles worth finding again

External sources need a local copy

Some source material is too large, too valuable, or too likely to disappear behind a login wall. The graph has a sources/ directory for that.

For conference talks, I fetch subtitles with yt-dlp and store .vtt files under sources/transcripts/<conference>-<year>/. Each talk gets a small metadata file with the URL, title, speakers, runtime, transcript path, and the page that summarizes it.

The summary goes into pages/. The transcript stays in sources/ so future search can still find an exact phrase, command, or speaker quote that did not make the summary.

X.com needs a different path because direct fetching is unreliable from this workspace. Long posts and threads are exported locally as Markdown into sources/x-com-posts/. The stable join key is the numeric status ID. When a journal has an X link, I grep the exports for that ID and cite the local file.

Attachments such as screenshots, PDFs, CSVs, and images live in assets/, using Logseq’s normal local asset links.

The result is boring in a useful way: a broken website or login wall does not erase the source trail.

Pages are the knowledge layer

The durable pages are compact Markdown notes. They are not dumps from journals. They answer the questions I expect a future reader, including a future AI agent, to ask:

What is this?
Why does it matter?
How does it work?
What are the gotchas?
Where did this come from?

The common shape is:

## Summary
## Key Ideas
## Operational Notes
## Gotchas
## Links
## Source Notes

Not every page needs every heading. The format is only there to force the useful work: make the page searchable, connect it to related pages, and show where the material came from.

A recent addition to that shape is claim-level footnotes. ## Links is a fine roster of further reading, and ## Source Notes records which journal a page grew from, but neither tells a reader which specific source backs a specific sentence. When a page states a number, a benchmark result, or a direct attribution, I now tie it to its source with a footnote at the point of the claim, so the reader lands on the primary source instead of guessing which of ten links in the list is the right one. Logseq renders standard Markdown footnotes: [^1] next to the claim, and [^1]: Title, date, URL collected at the bottom of the page. The curate-journals skill treats this as a rule now: any paper, post, or video a page relies on has to be reachable from the page itself, because the journal it came from usually holds only a bare link.

Logseq links are the connective tissue. A page about local models can point to [[Claude Code]], [[AI/Harness engineering]], or [[Observability/LLM observability]] without needing a separate taxonomy project. If a page name contains a slash, the file uses Logseq’s triple-lowbar encoding, so AI/Local models and RAG lives as pages/AI___Local models and RAG.md.

The curation pass

The curation workflow is deliberately mechanical:

The repo has a Claude skill for this: .claude/skills/curate-journals/SKILL.md. AGENTS.md says what the graph is and what good curation looks like; the skill turns that into the repeatable pass.

Find unprocessed journal changes from the last Curation hash: in log.md, plus any untracked journal files.
Read each journal in full and note the [[tag]] blocks.
Classify each bullet as durable, raw, or already promoted.
Map durable items to existing pages before creating new pages.
Investigate external links, transcripts, and local X.com exports.
Write synthesis into pages/, not a dump of journal bullets.
Cross-link related pages.
Append a new batch entry to log.md.
Update pages/contents.md if a new durable page was created.

The last step saves future work. log.md records which journals were processed, which pages changed, which external links were investigated, which videos or transcripts were fetched, what was skipped, and what backlog remains.

That makes curation resumable. A later pass can see why a link was ignored or whether a conference playlist was already fetched.

The git hash is the part that makes this work for real daily notes. A date scan only finds journal files newer than the last processed date. That misses the normal Logseq habit: I open an old day, add one new block, and save it. The curate-journals skill reads the previous Curation hash: and diffs journals/ against it, so a re-edited journals/2026_06_24.md shows up even if journals/2026_06_25.md was already processed.

The pass starts with roughly this:

git diff --name-only <stored-hash> HEAD -- journals/
git status --short journals/

The union is the work list: journal files changed since the last curation pass, plus new untracked journals. The curation log then records the next hash so the following pass has a new high-water mark.

The skill also keeps the pass conservative. It explicitly says to leave TODOs, meeting logistics, PR breadcrumbs, isolated IDs, and ungrounded fragments in the journal. That matters because the easiest way to ruin a personal knowledge base is to promote everything.

Agents make the graph more useful

This graph is written for humans, but I also expect coding agents to read it.

The repository has explicit instructions for Codex and Claude Code. They say, in effect: this is a private Logseq knowledge base, not an app repo; journals are the raw inbox; pages are the durable layer; do not copy raw fragments into pages; synthesize, cite sources, and keep sensitive details private.

For journal work, the agent loads curate-journals and follows the same checklist every time. That gives the agent a smaller job than “organize my notes”: find the new journal material, decide what has durable value, update the right page, and write down what happened.

That changes how I use AI tools. Instead of asking an agent to remember context from a chat, I ask it to inspect the repo:

search journals for a topic
find the existing page
read source notes
summarize a talk transcript
connect related pages
draft a post from the durable layer

The agent does not need everything pasted into the prompt. It can search the repository, read the source material, and leave behind better Markdown for the next run.

What I do not promote

The part that keeps the system usable is omission.

I do not move every note into pages/. Most raw material stays raw. That keeps the durable layer useful.

I leave behind:

tasks without reusable context
meeting logistics
temporary debugging noise
private operational details that do not need to be repeated
links that looked interesting but did not turn into a durable idea
source material that I cannot verify

The durable layer works because it is selective.

The result

I am not trying to build a perfect wiki. I want a working memory system with:

fast capture in journals
source retention for long-form material
compact durable pages
explicit source notes
a curation log
enough structure for Logseq, Codex, Claude Code, and future me to navigate it

The design choice is to treat personal knowledge as ingestion, not filing. Capture stays cheap because journals can stay messy. Curation happens later, when there is enough signal to write a page worth keeping.

That delay is the trick. It keeps the inbox easy and the knowledge layer clean enough to be useful months later.

Agent Harnesses: Why You Shouldn't Bet Your Company on Claude Code or Codex

ladislav@prskavec.net (Prskavec.Net) — Tue, 02 Jun 2026 09:00:00 +0100

In less than two years, coding agents went from novelty to daily driver. Claude Code and OpenAI Codex read your repo, run commands, edit files, and finish real work. I use them every day. You probably do too.

Using a tool is one thing. Standardizing your whole company on a single vendor’s closed agent is another. That decision is easy to make and very expensive to walk back, so it is worth thinking through before you make it.

What is an agent harness?

When people say “Claude Code” or “Codex,” they usually mean two things glued together:

The model, the LLM that does the reasoning (Claude, GPT, and so on).
The harness, everything around the model: the tool-calling loop, file editing, command execution, context management, permissions, prompts, and the UI.

The harness is what turns a chat model into an agent. It decides which tools exist, how context is assembled, when to ask for permission, and how errors get recovered. The model is a commodity you rent by the token. The harness is where your actual workflow lives.

And the harness is the valuable part. The vendor owns it.

The case against vendor lock-in

1. You couple your workflow to someone else’s roadmap

Adopt Claude Code or Codex wholesale and your engineers’ muscle memory, your CI integrations, your custom commands, and your prompts all get shaped by that one harness. When the vendor changes pricing, drops a feature, throttles your usage, or pivots, you pay for it. You don’t control the roadmap and you can’t fork it.

2. The model is the easy part to swap, if the harness lets you

A new best model shows up every few months. The model that fits your codebase best in Q1 may be second-best by Q3. A good setup lets you switch when the price/performance curve moves. A closed vendor harness ties you to their model family, and that costs you the biggest lever you have: picking the best model for the task at the best price.

3. Data and compliance boundaries are not negotiable for many companies

Where does your code go? What gets logged, retained, and used for training? With a closed harness you take the vendor’s answers as given. For regulated industries, air-gapped environments, or anyone with serious IP concerns, that is not enough. An open harness lets you choose providers, route to self-hosted or enterprise endpoints, and keep an audit trail you actually own.

4. Lock-in is cheap to enter and expensive to leave

The start is great. Then you have hundreds of engineers with vendor-specific habits, internal tooling built against a proprietary CLI, and no abstraction layer. Migrating later means retraining people and rebuilding integrations. That switching cost is exactly what gives the vendor pricing power over you.

5. Your competitive edge should not be a SaaS subscription

If everyone in your industry runs the same off-the-shelf agent the same way, where is your advantage? The leverage is in how you wire agents into your codebase, your domain knowledge, your tests, and your review process. That belongs in something you control.

The alternative: own the harness, rent the model

This is not an argument against AI coding agents. It is an argument for putting the boundary in the right place. Here is the setup I recommend.

Own the harness with pi

pi is a minimal, extensible terminal coding harness. The idea is to adapt the tool to your workflow instead of the other way around, and you do that without forking the agent’s internals. You extend it with TypeScript extensions, skills, prompt templates, and themes, then package and share them across your team over npm or git.

That gives you what you want from a company harness:

Your custom tools, prompts, permissions, and skills become version-controlled artifacts in your repo, not settings trapped in a vendor’s cloud.
It runs in interactive, print/JSON, RPC, and SDK modes, so the same harness powers your engineers’ terminals and your CI pipelines and internal apps.
It ships with sensible defaults but stays small, so you add only the complexity you need.

You get the ergonomics of Claude Code or Codex, but the workflow logic is yours and travels with your codebase.

Rent the model through a gateway

Keep the model pluggable. The simplest path is OpenRouter, a model gateway that gives you access to basically every model worth using behind one interface. Swap Anthropic, OpenAI, Google, and open-weight models on price/performance without rewriting anything.

If your data or compliance requirements are stricter, and for many companies they are, go through a cloud provider gateway instead. Amazon Bedrock and Azure AI Foundry give you the same model menu inside your existing cloud account, with your org’s networking, IAM, logging, and data-residency guarantees already in place. For regulated or IP-sensitive work, that is often the right answer.

Either way, standardize on the OpenAI-compatible API shape as the lowest common denominator, so swapping providers is a config change and not a migration.

Measure and route

Once the model is a swappable component, you can benchmark cost and quality per task and route on purpose: a cheap fast model for boilerplate, a strong one for tricky refactors. With pi owning the loop and a gateway in front, that routing is yours to tune.

“But Claude Code / Codex is just better right now”

Maybe today. The gap between the leading harness and the open ones is closing fast, and the open ones are built out in the open. Optimizing for “best this quarter” while you lock yourself in for years is a bad trade, especially for something as foundational as how your company writes software.

Use the good tools. Just don’t let one of them become the thing you can’t leave.

Takeaways

The harness, not the model, is where your workflow lives, and closed vendors own it.
Treat the model as a swappable commodity. Lock-in takes that lever away.
Data, compliance, and cost control all get harder when the harness is a black box.
Use an extensible harness like pi and keep your prompts, tools, and skills version-controlled in your own repo.
Rent models through a gateway: OpenRouter for breadth, or Bedrock / Azure AI Foundry when compliance and data residency matter.

Adopt agents fast, but keep the boundary, the harness and the choice of model, in your own hands.