8. PinSlip Data Storage

8. Data Storage

PinSlip's core principle: local first.
This chapter covers where your notes actually live, what format they're in, how to back them up, and how to migrate them.

8.1 Where the Vault Lives

Default Location

How to Change It

• Pick the location on first launch.

• Change it later under Settings → Storage Location → Change Location.

Switching locations will close all note windows, restart the service, and rebuild the index — a few seconds.

8.2 Directory Layout

<your chosen directory>/
├── notes/              # All notes (.md, may have subfolders)
├── inbox/              # Quick Capture notes (flat)
├── attachments/        # Image attachments (png/jpg/gif/webp)
├── .trash/             # Recycle bin
└── .pinslip/           # Runtime files
    ├── settings.json   # Settings file
    ├── pinslip.db      # Search index database
    ├── groups.json     # Note group registry
    ├── git-sync.json   # Git sync config (token lives here)
    ├── mcp.json        # MCP discovery file
    └── .gitignore      # Excludes git-sync.json and other sensitive files

What Each Directory Is For

8.3 File Format

Every note is a .md file, with YAML frontmatter + Markdown body:

---
tags: [work, ideas]
pin: true
color: yellow
collapsed: false
group: g-abc123
zoom: 1.0
created: 2026-07-30T14:00:00+08:00
updated: 2026-07-31T09:30:00+08:00
source: browser-extension
---

# Task List

- [ ] Write the daily report
- [ ] Reply to the client
- [ ] Organize this week's notes

Frontmatter Fields

File Naming

title-slug-created-date-yyyymmdd-id.md

• Example: my-idea-20260731-abcd1234.md

• slug strips illegal characters \/:*?"<>| and is truncated to 30 runes.

• When the title changes → the file is auto-renamed.

• Older <id>.md naming is still supported.

Title Derivation

When a note has no explicit title, PinSlip uses the first meaningful line of the body:

• Strips Markdown structural markers (# / - / > / - [ ])

• Strips inline wrappers (**bold** / __bold__ / ~~strike~~ / *italic* / _italic_ / `code`)

• Skips full-line links / full-line images

• Skips git conflict markers

• Truncates to 30 runes

The server and renderer use the same algorithm, so filenames stay consistent.

8.4 Image Paths

Images live in attachments/. Notes use relative paths:

![png](attachments/screenshot.png)

This is how a note in the notes/ root writes its image path.

Relative Paths in Nested Folders

When the note is in notes/work/project/, the path gains ../:

![png](../attachments/screenshot.png)

PinSlip maintains this ../ prefix for you:

• Move a note to a folder with a different depth → the server rewrites attachment paths automatically.

• That way images stay visible when you open the same directory in Obsidian / VS Code.

8.5 Backups

How to Back Up

Just copy the whole vault directory.

Your vault is just .md files plus a pile of images — no proprietary format dependency.

Backup Strategies

• Full backup: copy the whole vault to an external drive / cloud drive.

• Incremental backup: we recommend Git sync (see 06-Sync) — automatic version control.

• Manual backup: CopyOnSave / Time Machine / Windows File History.

Recommend Excluding .pinslip/ from Backups

• Contains tokens (git-sync.json)

• Contains process info (mcp.json)

• Contains the search index (pinslip.db, rebuilt automatically on launch)

• After excluding it, reinstalling will re-initialize cleanly (you won't lose any note content).

Always Back These Up

• notes/ (all notes + tags + colors + pin state)

• inbox/ (Quick Capture)

• attachments/ (images)

• groups.json (group ordering — optional; losing it just scrambles the order, notes are still recoverable from frontmatter)

8.6 Migration

Migrating to a New Computer

1. Install PinSlip on the new machine.

2. Copy the vault directory (excluding .pinslip/) to the new machine.

3. Launch PinSlip → pick the new location → wait for the index to rebuild.

4. If you use Git sync it's even simpler: fill in the same repo → PinSlip clones all your notes back automatically.

Migrating to a Different Folder

• Settings → Storage Location → Change Location.

• Once you pick the new directory, PinSlip closes all note windows, restarts the Go service, and rebuilds the index.

• The old vault is not deleted automatically (delete it manually if you want).

Migrating to Another Computer (via Git)

See 06-Sync → Multi-Device Sync.

8.7 Privacy

• All notes live only on your local disk.

• PinSlip never uploads note content.

• MCP service and Git sync are the only features that talk to the outside world once enabled.

• With all external features turned off, PinSlip is a fully offline local app.

8.8 Data Recovery

A Note You Accidentally Deleted

• For a regular note / group / folder → check .trash/.

• Can't find it → check your backups (Git sync history / backup copy).

A Broken Index

• Delete <vault>/.pinslip/pinslip.db.

• Restart PinSlip → it rebuilds the full index automatically (note content is unaffected).

A Whole Broken Vault

• Restore the whole vault from a backup.

• Or re-clone from the Git repo.