Skip to content
KB-1 Docs

Import an Obsidian vault

KB-1 vaults are filesystem directories. The launch import path is intentionally plain: copy Markdown files and assets into a daemon-managed vault, preserve the KB-1 .kb1/ metadata directory, then verify the result through the daemon.

This is not an Obsidian plugin migration. KB-1 preserves your files, reads Markdown, shows assets that are present in the vault, and keeps its own daemon metadata under .kb1/.

What this imports

Section titled “What this imports”

Supported in the first import path:

  • Markdown files.
  • Images and attachments stored inside the Obsidian vault folder.
  • Folder structure.
  • YAML frontmatter as Markdown text.
  • Wikilinks as Markdown syntax the editor can decorate and resolve when the target exists in the imported tree.

Not imported as product settings:

  • Obsidian workspace state.
  • Obsidian plugin configuration.
  • Obsidian themes and snippets.
  • Files outside the vault folder.

Prerequisites

Section titled “Prerequisites”
  • A running local KB-1 daemon.
  • A backup of your Obsidian vault.
  • A quiet source vault: close Obsidian or stop editing while copying.
  • Enough disk space for a second copy of the vault.

The examples use rsync. On Windows, use WSL, Git Bash, or another copy tool that preserves nested directories.

Create the target KB-1 vault

Section titled “Create the target KB-1 vault”

Start the daemon first. If you have not done that yet, follow Run the local-only daemon.

In a second terminal, go to the same daemon checkout and set variables for the import. KB1_HOME and KB1_PORT must match the values used to start the daemon; the values below match the local-only quickstart.

Terminal window
cd /path/to/kb-1-daemon
export KB1_HOME="$PWD/.kb1-quickstart"
export KB1_PORT=7382
export VAULT_ID="obsidian-notes"
export OBSIDIAN_VAULT="$HOME/Documents/Obsidian/My Vault"

Create the KB-1 vault that will receive the import:

Terminal window
curl -X POST "http://127.0.0.1:$KB1_PORT/api/vaults" \
  -H 'content-type: application/json' \
  -d "{\"displayName\":\"Obsidian Notes\",\"slug\":\"$VAULT_ID\"}"

A successful response is 201:

{"ok":true,"vault":{"id":"obsidian-notes","displayName":"Obsidian Notes"}}

If the vault already exists, use a different VAULT_ID or import into the existing folder deliberately. New KB-1 vaults include starter notes; move or delete those starter files before copying if you want the imported tree to be exactly the Obsidian tree.

Copy the Obsidian files

Section titled “Copy the Obsidian files”

Flush live KB-1 sessions before copying:

Terminal window
curl -X POST "http://127.0.0.1:$KB1_PORT/api/vaults/$VAULT_ID/ops/flush"

Expected output:

{"ok":true,"flushed":0,"durableAsOf":"2026-06-26T21:57:52.352Z"}

Stop the daemon with Ctrl-C so it does not scan a half-copied tree.

Back up the fresh KB-1 target vault metadata before importing. Keep this backup outside KB1_HOME/vaults/; the daemon discovers each immediate directory under vaults/ as a vault on restart.

Terminal window
mkdir -p "$KB1_HOME/import-backups"
cp -a "$KB1_HOME/vaults/$VAULT_ID" \
  "$KB1_HOME/import-backups/$VAULT_ID.$(date +%Y%m%d%H%M%S)"

Refuse symlinks before copying. Symlinks can point outside the Obsidian vault folder, which would break the import boundary.

Terminal window
if find "$OBSIDIAN_VAULT" -type l -print -quit | grep -q .; then
  echo "Resolve or remove symlinks before importing:" >&2
  find "$OBSIDIAN_VAULT" -type l -print >&2
  exit 1
fi

Copy your Obsidian vault into the KB-1 vault directory while preserving KB-1’s .kb1/ metadata. Use -rtv, not archive mode, so symlinks are not preserved.

Terminal window
rsync -rtv \
  --exclude '.obsidian/' \
  --exclude '.git/' \
  --exclude '.trash/' \
  --exclude '.DS_Store' \
  --exclude '.kb1/' \
  "$OBSIDIAN_VAULT"/ \
  "$KB1_HOME/vaults/$VAULT_ID"/

Restart the daemon with the same KB1_HOME and port:

Terminal window
KB1_HOME="$KB1_HOME" KB1_PORT="$KB1_PORT" pnpm dev

Verify the import

Section titled “Verify the import”

In a second terminal:

Terminal window
curl "http://127.0.0.1:$KB1_PORT/api/vaults/$VAULT_ID/tree?depth=2"
curl "http://127.0.0.1:$KB1_PORT/api/vaults/$VAULT_ID/search?q=<unique-word-from-a-note>"

The tree response should be ok: true and should include imported folders or Markdown files. The search response should find a known word from one of your notes.

Open the imported vault in the local UI:

http://127.0.0.1:<KB1_PORT>/

Choose Obsidian Notes from the vault rail and open a note you recognize.

Done looks like

Section titled “Done looks like”
  • The KB-1 vault list includes the imported vault id.
  • The tree endpoint shows imported Markdown files.
  • Search finds text from imported notes.
  • Opening a note in the UI shows the expected Markdown.
  • Editing and saving a note updates the corresponding file under KB1_HOME/vaults/$VAULT_ID/.
  • The original Obsidian vault remains untouched.
Section titled “Troubleshooting links”