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. Strayfiles automatically saves it to your default notes directory
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

Moving Files

When you move a file on disk:

With frontmatter UUID:

• When the note is next accessed, Strayfiles recovers the new path by scanning the file index for the matching UUID
• Mapping updated on next access
• 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 the file and mapping from this device’s local database
• Cloud propagation: If cloud sync is enabled, the deletion propagates to other devices via Supabase sync
• Mappings cascade: Deleting a note removes all device mappings for that note

Renaming and Moving

Action	Effect
Rename file	Mapping updated automatically if the file has a frontmatter UUID; without an embedded UUID, treated as delete + create
Move file	Mapping updated automatically if the file has a frontmatter UUID; without an embedded UUID, treated as delete + create
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