Logseq 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.