Libraries¶

A library is Melanite's unit of data. A single <name>.melanite folder contains everything: the database, the actual files, and the thumbnails.

Library operations¶

Task	How
Create	"Create New Library…" on the welcome screen → choose location and name
Open an existing library	"Open Library…" on the welcome screen → select a `.melanite` folder
Open a recent library	Click the row under "Recent Libraries" on the welcome screen
Remove from the list	The × at the right end of that row
Close	The × next to the library name at the top of the Sidebar

Only one library can be open at a time. To switch, close the current one and open another.

Removing from the recents list doesn't delete anything

The × at the end of a row clears only the entry in that list. The .melanite folder and its contents are untouched — reopen it any time with "Open Library…".

Use it to tidy up entries for libraries on external drives, or ones you've since deleted.

Should you split libraries?

One big library is usually fine (the design targets 100,000 items). Split only when you have a clear reason, such as fully separating work and personal data. Search and links do not cross library boundaries.

If you split them the wrong way, items can be moved across with their tags, links and memos → Move to another library

Inside the folder¶

MyLibrary.melanite/
├── melanite.json      # Library marker: format version and creation date
├── melanite.db        # SQLite: metadata + full-text search index
├── files/
│   └── <ULID>/<original file name>    # The actual files
├── thumbs/
│   └── <ULID>.webp                    # Thumbnail cache
├── trash/
│   └── <ULID>/…                       # Files moved to the Trash
├── backups/
│   └── melanite-<timestamp>-<kind>.db # Metadata backups (see below)
└── .lock              # Info about the running process (exists only while the app runs; see below)

This is the heart of Melanite's design.

Files are stored in their original format at files/<ULID>/<file name>. No proprietary formats, no re-encoding
So even without Melanite, you can retrieve files with Finder / File Explorer
A folder containing melanite.json is a library. Without it, Melanite won't open the folder
thumbs/ is a disposable cache (it can be regenerated by the integrity check)

Can't find .lock?

.lock is normally invisible for two reasons. This is not a problem.

It exists only while the app is running. It is deleted when you close the library
It is a hidden dotfile. Press Cmd+Shift+. in macOS Finder, or enable "Hidden items" in Windows File Explorer to see it

Backup¶

Copy the whole folder (the surest way)¶

Just copy the folder. That is a complete backup.

Moving to a new machine works the same way: copy the .melanite folder over and open it.

Close the app before copying

If you copy while Melanite has the library open, you may capture the database mid-write. Close the app first.

Metadata backups (taken automatically)¶

Melanite keeps snapshots of melanite.db in backups/ inside the library. You can review and change this under Settings → Backup.

melanite.db holds your tags, links, memos, locations, favorites and dates. Your files stay in files/ in their original format, so the database is the only part that cannot be recreated. That is why backups cover melanite.db only — files/ is not included, which keeps them from multiplying your disk usage.

Snapshots are taken at three moments:

Kind	When	Notes
Automatic	When you open the library	Only if the configured number of days (1 by default) has passed. Not on every open
Before update	Just before an app update changes the database format	Always taken; the most recent one is kept regardless of the generation count
Manual	When you press "Back up now"

Setting	Default	Meaning
Generations to keep	5	Oldest generations are removed first
Automatic interval (days)	1	Set to 0 to turn automatic backups off

This does not replace a whole-folder backup

backups/ lives inside the library folder. If you lose the disk, you lose it too. To protect your files as well, keep a copy of the whole folder somewhere else.

Cloud sync is not a backup

Dropbox and friends will happily sync a damaged database too. It does not do the job of a versioned backup.

Want to look inside?

A backup is a copy of the database, so reading it takes a tool that speaks SQLite. To get your tags, links, memos and locations out in a form you can read outside the app, use Metadata export on the same tab (it writes a single JSON file; it cannot be read back in).

Recovering from a damaged database¶

If Melanite finds the database damaged while opening a library, it shows a recovery dialog. Pick the point you want to go back to, and Melanite replaces the database with that generation and reopens the library.

The database being replaced is kept in the library as melanite.db.replaced-<timestamp> (the 3 most recent ones). Nothing is thrown away immediately, so you can try a different generation.

Restoring loses changes made after that backup was taken. Your files remain in files/ either way, so what you lose is the tags, links and memos added in between. Running the integrity check afterwards lists files imported after the backup as "on disk but not in the database", so you can import them again.

When there are no backups

If you have a copy of the library folder, overwrite the damaged library's melanite.db with the one from that copy and open it again. (If melanite.db-wal or melanite.db-shm are present, delete them too.)

Using cloud storage¶

Keeping a library in Dropbox / iCloud Drive / OneDrive is not prevented by design, but use it with care.

Melanite assumes single-process access
Opening the same library from two machines at once can corrupt the database
The .lock file detects concurrent launches, but this is accident detection, not locking. Cloud sync takes seconds to propagate, so simultaneous opens within that window go undetected

To stay safe, make sure only one machine touches the library at a time, and always close the app before switching machines. Also wait until sync has finished on both machines before opening it on the next one — right after closing, the transfer may still be in flight and you could open a stale copy.

If you see "May be open on another machine"¶

This confirmation appears when a record of another machine opening the library (.lock) is still present. Melanite has no way to tell whether that machine still has it open or whether the record was simply left behind by a crash, so it asks instead of deciding for you.

If the other machine still has it open, choose "Cancel" and close it there first
If the other machine has already closed it, or the record was left by a crash, "Open anyway" will let you in

"Open anyway" opens without further prompts, so make sure the other machine really has it closed before choosing it. Opening on both at once can corrupt the database.

If you see "opened by another process"¶

Melanite is running twice on the same machine. Use the other window instead — there is no "open anyway" option here, because process liveness can be verified reliably. A .lock left behind by a crash is reclaimed automatically, so manual deletion is normally unnecessary.

Integrity check¶

You can verify that the database and the actual files are in sync.

Run it from "⚙ Settings…" at the bottom of the Sidebar → "Maintenance" tab.

It mainly checks for drift in two directions:

In the DB but the file is missing — e.g. someone deleted from files/ externally
File exists but not in the DB — e.g. someone put a file into files/ externally

Reading the report¶

You get "The library is healthy" when nothing is wrong, or "Some items need attention" when something is.

Repaired automatically (each reported as a count)

Item	What it does
Picking up external changes	If the underlying file was modified outside Melanite, its size and modified time are re-read
Name normalization	Fixes macOS-style decomposed characters (Japanese "が" stored as "か" plus a separate dakuten mark). Tag names are covered too, and tags that become identical after normalization are merged
Image dimensions	Fills in the width and height of images whose dimensions could not be read on import (HEIC and similar), by reading the file again
Search index rebuild	Rebuilds the full-text index
Thumbnail generation	Generates thumbnails that are missing, in the background (ones that failed before are not retried → Regenerating thumbnails)

Needs your decision (listed individually in the report)

Item	What to do
Entries whose files are missing	"Delete Entries…" removes the entry — its tags, memo, and links. This cannot be undone
Folders not registered in the database	Files still sitting inside the library. Re-import them by drag & drop if you want them back (Melanite never registers them on its own)
Identical items	See "Cleaning up identical items" below

Make sure the files are really gone before deleting entries

A file that is merely unavailable right now also counts as missing — for example when the library lives in cloud storage and the contents haven't been downloaded to this machine yet (iCloud Drive's "Optimize Storage" and similar → Using cloud storage).

"Delete Entries…" removes the item's folder along with the database row. If the file arrives later, it can't be brought back. When in doubt, wait for the sync to finish and run the check again.

Cleaning up identical items¶

The report also lists groups of items whose content is byte-for-byte identical (duplicates that slipped in when migrating from another library, restoring from the Trash, and so on).

Pressing “Move N items to the Trash” keeps the earliest import of each group and trashes the rest.

Tags on the trashed copies are carried over to the item that stays
This is not a permanent delete, so you can restore them from the Trash

Watch out for files created from a template but not yet edited

A file created from a template is byte-for-byte identical to that template until you edit it. Run this cleanup before changing and saving it and the template — imported earlier — is what stays, while the file you just created goes to the Trash, with its tags carried over to the template.

Restoring it from the Trash brings its tags back with it, but the tags copied onto the template stay there. The safe order is to open and save the new file first, then run the cleanup. Once saved its contents differ, so it no longer appears in the duplicate list.

Don't put files into files/ directly

Melanite writes in the order "file operation succeeds → then register in the DB". A file placed into files/ by hand is not in the database, so it won't appear in the list or in search. Always import through the app.