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.

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

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