Workspace & Files

Cairn stores all data in a single folder you choose. Understanding the layout helps you keep backups, sync across devices, and edit files outside the app.

How the workspace works

On first launch (or via Settings → Workspace → Change Folder), Cairn asks you to pick a root folder. Everything Cairn knows about your projects, notes, and tasks lives inside that folder and nowhere else.

Closing and reopening Cairn with the same folder restores your exact state. Pointing Cairn at a different folder instantly switches workspaces — you can maintain multiple independent workspaces.

File layout

my-workspace/
  cairn.db            ← SQLite database (projects, tasks, settings)
  notes/
    My Project/
      Design spec.md
      Meeting notes.md
    Another Project/
      Roadmap.md

• cairn.db — the canonical data store. Board state, task cards, settings, and note metadata all live here.
• notes/<Project>/<Title>.md — one file per note, organised into folders by project name. These are secondary representations that stay in sync with the database.

YAML frontmatter

Each .md file starts with a YAML frontmatter block that Cairn writes and reads:

---
title: Design spec
project: My Project
created: 2026-01-15T10:32:00Z
updated: 2026-04-10T14:05:22Z
pinned: false
tags: []
---

# Design spec

Your note content starts here...

The frontmatter is maintained automatically. You can read it with any tool that understands YAML frontmatter (Obsidian, VS Code extensions, Pandoc, etc.).

Editing files externally

Cairn watches the notes/ folder for changes. If you edit a .md file in another editor — VS Code, Obsidian, Neovim, anything — Cairn detects the change and syncs it back into the database within a second or two.

This means your notes are genuinely portable. You are never locked in to the Cairn editor.

Opening an existing Obsidian vault

Cairn recognises Obsidian vaults (folders containing a .obsidian directory) and Markdown folders. When you pick such a folder as a workspace — or copy one into an existing workspace — Cairn scans it without modifying anything and shows a preview of the projects and note counts it will adopt, with each top-level folder listed so you can untick the ones to leave out before any frontmatter is written.

• Auto-created projects — every top-level folder that contains notes becomes a project, and the .md files inside are imported recursively, preserving subfolder paths. Loose .md files in the vault root gather into a catch-all project named after the vault folder.
• Sensible defaults — dot-folders (.obsidian, .git, .trash), infra folders (assets, attachments), templates, and *.excalidraw.md files are skipped automatically. Re-scanning is idempotent.
• Filenames stay stable — Cairn keeps a note's on-disk filename unchanged on edits (Obsidian resolves [[wikilinks]] by filename, and vault notes often have a title differing from the filename). Only an explicit rename changes the filename, and that rewrites inbound wikilinks.
• Conflict-safe re-import — if a note is edited both in Cairn and in the vault since adoption, the vault file wins and Cairn's version is preserved as a conflict copy, surfaced in the same Conflict-resolution panel device sync uses — no silent data loss.
• Undo import — the "found these projects" summary has an Undo import action that removes the projects and notes Cairn created, strips Cairn's frontmatter from the vault files (leaving your own frontmatter and content untouched), and marks the folder as un-managed so it's never re-imported — without publishing deletions to synced devices.

Importing is a one-way, opt-in action: Cairn only writes once you confirm, and it's worth backing up (or committing) the vault first. Your exclusion choices persist for later startup scans and file watching.

Local Project Databases

Cairn allows you to store a project's data (notes, tasks, idea flows) directly alongside your source code using a local .cairn folder. This is incredibly powerful for keeping project management contextualized, portable, and accessible to MCP agents running within your codebase.

Initializing a Local Project

You can set up a local project database in two ways:

• Via the UI: Navigate to your Project Settings in Cairn and click "Mount Local Database". Select your repository folder, and Cairn will automatically initialize the required files.
• Via the CLI: Run cairn-mcp init inside your repository's root directory. Then, open Cairn, go to Project Settings, and link the local directory.

Moving and Migrating Projects

Local .cairn databases are completely portable. If you clone your repository on another machine or move the folder, simply link it to a project in your Cairn workspace.

When mounted, Cairn will automatically migrate the database schema if it was created on an older version of the app. It will also seamlessly adopt the existing notes and tasks into your current workspace context—meaning you never lose track of your Idea Flows or Kanban boards when migrating across machines.

Portability

iCloud Drive

Put your workspace folder inside ~/Library/Mobile Documents/com~apple~CloudDocs/ (or any subfolder within iCloud Drive) to sync across your Macs automatically. Cairn works normally with iCloud — the file watcher handles any on-demand downloads transparently.

Dropbox

Move your workspace folder into your Dropbox folder. Cairn and Dropbox sync the same files from different angles — Cairn writes, Dropbox syncs to cloud and other devices.

Git

Put your workspace folder in a git repository. The .md files version perfectly. Add cairn.db to .gitignore if you only want to version the markdown, or include it if you want full board state versioning (the database is binary, so diffs won't be human-readable).

Managing projects

Each project's ⋯ menu in the sidebar holds project lifecycle actions:

• Rename — renaming a project also moves its notes folder on disk (e.g. notes/Test Project/ → notes/Misc/), so your files stay consolidated under one folder.
• Merge into… — pick a destination project and everything in the current one — notes, task cards, board columns, and Idea Flow nodes — is moved into it, then the emptied project is removed. Cards land in the destination's matching column by type (Todo → Todo, Done → Done), and any custom columns are recreated so nothing is lost. The move is transactional and syncs to your other devices.
• Export as Markdown — export the whole project as a single document (metadata, board grouped by column, and all notes, folder-sorted).
• Code directory — the folder the coding agent reads and writes, set in Project Settings (also reachable from the gear in the Agent view). Type or paste a path, click Browse to pick a folder, or clear it entirely — no need to leave the coding workspace.

Merging is the clean way to consolidate duplicate or overlapping projects — for example, two projects that ended up with the same name.

Backup strategy

Because everything is files on disk, any file backup strategy works:

• Time Machine (macOS) backs up the workspace automatically
• Dropbox / iCloud provide continuous cloud backup
• A daily cp -r my-workspace my-workspace-backup is sufficient for simple use cases
• Git gives you a full history of note content