Note Mapping

How Notes Map to Files

Strayfiles uses UUID-based note IDs that enable the same note to exist at different file paths on different devices.

The Mapping System

Each device maintains its own mapping of note IDs to local file paths:

Device A (MacBook):
  note-uuid-123 → ~/notes/work/project.md
  note-uuid-456 → ~/Documents/ideas.md

Device B (iMac):
  note-uuid-123 → ~/Documents/project.md
  note-uuid-456 → ~/notes/ideas.md

Device C (Linux):
  note-uuid-123 → /home/user/notes/project.md
  (note-uuid-456 doesn't exist on this device)

Key Behaviors

Notes can exist on some devices only: This is completely valid. A note doesn’t need to exist on every device. Device C above simply doesn’t have note-uuid-456 - no error, no problem.

Different paths are fine: The same note (note-uuid-123) lives at different paths on each device. Strayfiles syncs the content while respecting each device’s filesystem organization.

UUID is the source of truth: The UUID in frontmatter (or database) identifies the note, not the file path.

How Mappings Are Created

When you create a note:

1. You choose the file path
2. Strayfiles generates a UUID
3. UUID stored in frontmatter and database
4. Mapping created: device_id → note_id → local_path

When you sync:

1. New note arrives from another device
2. You choose where to save it locally (or use default)
3. Mapping created for your device

When you discover a file:

1. Frontmatter injection adds UUID to file
2. Mapping created for this device
3. Other devices can map the same UUID to their paths

Viewing Mappings

In Settings > Devices, you can see:

• Which notes exist on each device
• The local path for each note
• Last sync time per mapping

Moving Files

When you move a file on disk:

With frontmatter UUID:

• Strayfiles detects the move via file watching
• Mapping updated automatically
• No sync issues

Without frontmatter UUID:

• Old path becomes “missing”
• File at new path treated as new
• May cause duplicates

This is why frontmatter injection is recommended.

Syncing New Notes

When a new note arrives from sync:

1. Note content synced to database
2. If sync: false, note is skipped
3. You’re prompted for local save location
4. Or: auto-save to default notes directory
5. Mapping created for your device

Missing Notes

If a synced note doesn’t exist locally:

• Note appears in your list (from database)
• Marked as “not downloaded” or “cloud only”
• Click to download and choose save location

Deleting Notes

When you delete a note:

• Local delete: Removes file and mapping for this device
• Sync delete: Removes from all devices (with confirmation)
• Mappings cascade: Deleting note removes all device mappings

Renaming and Moving

Action	Effect
Rename file	Mapping updated, sync continues
Move file	Mapping updated, sync continues
Change UUID	Creates new note (don’t do this)

Troubleshooting

“Note not found on this device”:

• Note exists in cloud but no local file
• Download to create local copy

“Duplicate notes”:

• Same content, different UUIDs
• Usually from importing without frontmatter
• Merge manually, delete duplicate

“Mapping out of sync”:

• File moved outside Strayfiles
• Re-scan folder or manually update path