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, in folders with review on, 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. The migration skill writes a converted copy and never changes the vault, but if you migrate by hand you edit the files themselves. 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. The migration skill renames notes with those names to index-note.md and log-note.md and updates the links to them. If you migrate by hand, rename them in Obsidian first: with "Automatically update internal links" turned on under Settings, Files and links, Obsidian updates the links for you.

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

Knowtarium includes a free migration skill that does the conversion for you. It's free for everyone and needs no account. Your agent, such as Claude Code, Codex or Cursor, runs it with the free knowtarium command line tool, which reads your vault and writes the converted copy to a new folder. The vault itself is never changed, and your writing is left untouched:

1. It adds the OKF fields each note lacks: a type, a title, a description (the note's first paragraph) and who wrote it (you, at the time of the migration). It leaves stale_after unset, so nothing is flagged stale on day one; you add expiry dates to the notes where they matter.
2. It turns wikilinks and embeds into standard markdown links, so every tool can follow them. Attachments stay where they are.
3. It keeps your own properties exactly as they are, and writes an index.md in every folder. If your vault already has notes called index.md or log.md, it renames them to index-note.md and log-note.md and updates the links.
4. You import the copy into a Knowtarium workspace, as a folder or a zip. (The import also converts an Obsidian vault the same way on its own, if you'd rather skip the skill.)

Because the copy sits next to the original, you can read the whole migration as one diff. git diff --no-index --stat with the two folders should show changes in the frontmatter and the links, the new index.md files, a root log.md, the conversion report (.knowtarium/conversion-report.md) and any notes renamed to index-note.md or log-note.md, 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. 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.

In Knowtarium

A link to a note that doesn't exist isn't an error in OKF. Knowtarium draws it as a ghost in the graph, so a link that broke during conversion is easy to spot.

(opens full size in a new tab) (opens full size in a new tab)

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 imports it as one into a workspace, from a folder or a zip. A report comes first, with the storage it needs; then every note is encrypted on your device and uploaded, so we can't read any of it (the agents you connect see what they read).

(opens full size in a new tab) (opens full size in a new tab)

From then on, this is what you see:

• Who wrote every note, read from generated. In folders with review on, verified also shows who checked it: human-reviewed, or unverified until someone checks it. Notes past stale_after are listed on the Stale and expiring page.
• A graph of your links. It shows what's gone stale, and with review on, it can colour notes by trust tier. Links to notes nobody has written yet are ghosts.
• Every change signed and undoable. An agent's change is saved at once, signed with its own key, marked on the note and one Undo away. Turn on review for a folder, and agents' changes there wait for your approval instead.
• Search and history. Full-text search across the workspace, run in your browser, and every version kept with the signed change that made it, for as long as you choose.

Your agents connect with npx knowtarium connect and work on the notes over MCP. In folders with review on, when you change a note you can ask your agent to check it against everything connected. Knowtarium doesn't call an AI itself, it keeps your custom properties, comments and formatting as they are, and you can export a workspace or a folder as plain markdown whenever you like.

Knowtarium is an end-to-end encrypted web app. For a side-by-side of what each app is for, see Knowtarium vs Obsidian.

After the migration the new folder is still a vault: the skill copies your Obsidian settings next to the bundle, so Obsidian opens it the same way, and you can keep using Obsidian there. If you also import it into Knowtarium, the workspace holds its own encrypted copy, and the two don't sync with each other: decide where you edit, and export from Knowtarium as plain markdown when you want the files back. 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 keeps a workspace in step across your browsers, not with the folder on disk, and there's no phone app yet. Keep whatever already syncs the vault 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.