Migrate an Obsidian vault to OKF and keep using Obsidian

You can migrate an Obsidian vault to OKF without leaving Obsidian. An Obsidian vault is a folder of markdown files with YAML properties at the top. An OKF bundle is a folder of markdown files with YAML frontmatter at the top. The Open Knowledge Format, an open specification published by Google Cloud, adds a few fields that record what a document is, who wrote it, who checked it and when it goes stale. Those fields are what Knowtarium reads to show you who wrote every note and who checked it. So the migration is small:

One thing looks different in Obsidian afterwards. Its properties view doesn't support nested properties, and generated and verified are nested, so read those in source mode. The note itself opens as before.

Any migration that touches every file deserves an undo button. If your vault isn't in git yet, put it there and commit, so you can see exactly what changed and roll it back:

cd ~/vault
git init
git add -A && git commit -m "Vault before OKF migration"
 
# notes that use a name OKF reserves
find . \( -name index.md -o -name log.md \) -not -path "./.obsidian/*"

The last command matters. In OKF, index.md and log.md are reserved names at every level: index.md lists a folder's contents and log.md records changes. If you have notes with those names, rename them in Obsidian first. With "Automatically update internal links" turned on under Settings, Files and links, Obsidian updates the links to them for you.

If you sync your vault, let the sync finish before you start, and pause edits on other devices.

At launch, Knowtarium includes a free migration skill that does the conversion for you. Your agent, such as Claude Code, Codex or Cursor, runs it on your vault and leaves your writing untouched:

1. It adds the OKF fields to every document: a type, who wrote it, and when it goes stale.
2. It turns wikilinks into standard markdown links, so every tool can follow them.
3. It keeps your own properties exactly as they are, and writes an index of the bundle.
4. You open the folder in Knowtarium and review the result like any other change.

Because the vault is in git, you can also read the whole migration as one diff. git diff --stat should show changes in the frontmatter and the links, and nothing else. If a paragraph you wrote shows up as changed, look at it before you keep it.

You don't need any tool to do this. OKF is plain frontmatter, and a small vault takes an afternoon. Here's a note before and after:

---
tags: [pricing, sales]
aliases: [Plans]
owner: maya
---
 
Pro is €14 a month since September. See [[Annual plans]].

---
type: Note
tags: [pricing, sales]
aliases: [Plans]
owner: maya                                # your own keys stay
generated: { by: human:maya, at: 2026-03-02T10:00:00Z }
stale_after: 2027-03-01T00:00:00Z
---
 
Pro is €14 a month since September. See [Annual plans](Annual%20plans.md).

1. Add a type to every note

type is the only required field. OKF has no fixed list of types, so pick a few descriptive ones that match how you already think: Note, Meeting, Person, Decision, Reference. A note with only a type is already valid OKF.

2. Record who wrote it

Add generated with an actor and a time. For notes you wrote, use human: and your name. For notes an AI wrote, use the tool and its version, like claude-code/2.1. Times are ISO 8601 with a UTC offset, such as 2026-03-02T10:00:00Z. If you don't know the exact time, the file's date is a fair estimate.

For notes you wrote and still stand behind, add yourself to verified with the same time; that's what Knowtarium records when you edit a note yourself. Leave verified out of notes an AI wrote until you've reread them.

3. Say when it goes stale

Add stale_after to notes that expire: prices, plans, anything with "currently" in it. Evergreen notes can go without it.

4. Switch to markdown links

In Obsidian, open Settings, then Files and links, turn off "Use [[Wikilinks]]", and set "New link format" to "Relative path to file". New links are then standard markdown. Existing wikilinks need converting, by hand or by asking an agent. In markdown links, spaces in file names are written as %20.

5. Write an index

Add an index.md at the root, and in any folder where it helps. It has no frontmatter, just headings and a line per document with a short description:

# Pricing
 
* [Pricing](pricing.md) - current plans and prices
* [Annual plans](Annual%20plans.md) - why we moved to yearly billing
 
# Customers
 
* [Interviews](customers/interviews/) - one note per customer call

A log.md of changes, newest first under YYYY-MM-DD headings, is optional.

Whether the skill did the work or you did it by hand, the result is an OKF bundle, and Knowtarium opens it as one. If the skill did it, you review its result like any other change. From then on, this is what you see:

• A trust tier on every note. Worked out from generated and verified: notes you signed and vouched for show as human-reviewed, notes an AI wrote show as unverified until someone checks them, and notes past stale_after show as stale.
• A graph coloured by trust. Your links become a graph where every note takes its tier's colour, and links to notes nobody has written yet are dashed ghosts.
• A review queue. Agent changes waiting for you, your own edits waiting for an agent check, and notes past their date, in one list.
• Search and history. Full-text search across the vault, and every change kept as a diff, outside your notes.

When an agent changes a note, you see the diff and approve it. When you change one, you ask your agent to check it against everything connected, and any fixes it proposes wait for you. Knowtarium doesn't call an AI itself, and it keeps your custom properties, comments and formatting as they are.

Knowtarium runs on macOS, Windows and Linux. For a side-by-side of what each app is for, see Knowtarium vs Obsidian.

After the migration the folder is still a vault. Obsidian refreshes when other apps change files in it, so you can keep opening your notes there while your agents and Knowtarium work on the same files. A few habits keep the bundle clean:

• Start new notes in the format. If you create notes from a template, give it a type and a signature, with the values quoted, so Obsidian's properties panel doesn't overwrite the variables:

---
type: Note
generated: { by: "human:maya", at: "{{date:YYYY-MM-DDTHH:mm:ssZ}}" }
---

• Stick to markdown links. If you turn wikilinks back on, new links won't be readable by other tools. Obsidian-only syntax, such as embeds and callouts, may not show the same way elsewhere.
• Sync stays yours. Knowtarium has no sync of its own and no mobile app, so keep whatever already syncs the folder. The files are plain markdown, so git works alongside.

With provenance in place, the vault is ready for agents that write alongside you:

• Give them rules in an AGENTS.md or CLAUDE.md. Our template for a knowledge base matches the fields above.
• Require a source for every claim they write, with the citation rules for agents.
• Review their changes before they stick: how to review what agents change.