Core Concepts

How Strayfiles Works

Strayfiles is built on a simple philosophy:

“Keep your notes exactly where they are. We’ll adapt to your system.”

Two Types of Notes

Strayfiles handles notes in two ways:

1. Created Notes (File-First)

Notes you create within Strayfiles via “Add Note”:

• Stored as real .md files on disk
• You choose where the file lives when creating
• Content saved directly to file (no local database)
• UUID in frontmatter enables cross-device sync
• Strayfiles owns the file — deleting the note deletes the file

Create Note → Choose path → File created with UUID → Metadata indexed

2. Discovered Files (Filesystem-Backed)

Your existing Markdown files that Strayfiles indexes:

• Files stay exactly where they are
• No copying into a vault or database
• You manage sync (Git, iCloud, Dropbox, etc.)
• Strayfiles just indexes and organizes

Configure roots → Strayfiles scans → Files indexed → Virtual organization

UUID-Based Tracking

Every tracked note has a stable UUID identifier:

---
strayfiles:
  enabled: true
  id: "550e8400-e29b-41d4-a716-446655440000"
---

This UUID enables:

• Rename-safe tracking - Rename the file, keep the history
• Move-safe tracking - Move to a different folder, stay synced
• Cross-device sync - Same note, different paths on each device
• Version history - History follows the note, not the file path

Device Mapping

The same note can live at different paths on different devices:

Device	Note UUID	Local Path
MacBook	abc-123	~/notes/project.md
iMac	abc-123	~/Documents/project.md
Linux	abc-123	/home/user/notes/project.md

Strayfiles syncs the content while respecting each device’s filesystem.

Four Tracking Methods

When you discover a file, you choose how to track it:

1. Frontmatter Injection (Recommended)

• Adds UUID directly to the file
• Survives file renames and moves
• Best for files you control

2. HTML Comment

• UUID in invisible HTML comment
• Renders cleanly on GitHub/GitLab
• Best for README files

3. User TOML

• Adds path to ~/.strayfiles/strayfiles.toml
• No file modification
• Tracking lost if file moves

4. Project TOML

• Adds path to project’s strayfiles.toml
• Auto-detected via project markers (.git, package.json, etc.)
• Good for project-specific notes

What Happens When You Delete a Note

Deletion behavior depends on how the note was added:

Note Type	On Delete	File Result
Created (via “Add Note”)	File deleted	Gone from disk
Discovered (frontmatter)	Metadata removed	File kept, frontmatter cleaned
TOML-tracked	Reference removed	File unchanged

This design ensures Strayfiles never destroys files it didn’t create. Version history is also deleted — use Git or your backup solution for recovery.

See File Deletion Behavior for full details.

Virtual Workspaces

Organize notes without changing the filesystem:

[workspaces.work]
include = ["projects/**"]
exclude = ["**/archive/**"]

[workspaces.claude-code]
include = ["**/CLAUDE.md", "**/claude/**"]

A single note can belong to multiple workspaces. Assignments come from:

• Config patterns - Auto-assigned via glob matches
• Frontmatter - Explicit workspaces: ["work", "personal"]
• Manual - Drag and drop in the UI

Sync Philosophy

Free Tier:

• Local-first, no cloud dependency
• Sync via Git, iCloud, Dropbox, or Syncthing
• You control where files go

Pro Tier:

• Stray Cloud with end-to-end encryption
• Real-time updates across devices
• Files still stored locally as real .md files

Either way, your notes remain plain Markdown files that any editor can open.

What Strayfiles Doesn’t Do

• No proprietary format - Just Markdown with optional frontmatter
• No forced structure - Your folders, your organization
• No cloud lock-in - Switch providers anytime
• No code execution - Markdown is never executed, ever
• No symlink following - Direct symlinks are blocked for security (files within symlinked directories are allowed)

See Security & File Handling for details on file safety policies