Data and encryption

Locate stored data, manage protection and plan backups or cleanup.

Mellow stores its local application data under ~/.mellow/. That includes conversation databases, memory, indexes, configuration, and supporting files. Model downloads and external working folders can have their own locations. A backup of one directory is therefore not automatically a complete backup of every file an agent used.

Choose a storage mode

The default database mode is plaintext SQLite. FileVault provides the Mac's full-disk encryption when enabled. Mellow also offers explicit database encryption through SQLCipher and encrypted attachment storage.

FileVault protection against offline disk access is different from protection while your account is unlocked. SQLCipher also does not make a running authorized process unable to read its data. Choose the mode for the threat you need to address rather than treating either option as universal protection.

Change the mode through Mellow

Open Data & Storage using management search or the advanced general settings. Review the detected state and FileVault status, then use the encryption control. Let conversion finish before quitting or copying the data directory.

Mellow opens existing files according to their actual format. A plaintext SQLite header is recognizable; an encrypted store needs its key. The selected mode determines how new files are created and how the conversion pass brings existing covered stores into the requested state.

Conversion uses a temporary target-format file and replacement rather than treating an in-place flag change as encryption. A partially converted collection can contain both formats until convergence finishes. The detected state is more informative than assuming every store matches the toggle instantly.

Data locations

The following paths are relative to ~/.mellow/ in the normal profile.

Configuration JSON and derived vector indexes are not all covered by database encryption. Credentials managed through Keychain are not ordinary files in this table. Copying the data root does not necessarily copy the keys needed to open encrypted stores or authenticate services.

Export before moving or resetting

Use Export plaintext backup to create a readable backup of the covered data and configuration. The export does not change the live storage mode. In encrypted mode it decrypts the exported copy, so protect the destination and any later copies.

Before moving Macs, also account for models, working folders, external documents, and any separately managed secrets. Test the recovery path with a disposable profile when feasible. Do not delete the original installation until the restored data is verified.

A recovery phrase for local identity is not automatically the recovery key for every storage mode. Keychain behavior also depends on app signing and the user's account. Avoid manually deleting Keychain entries to clear an unrelated error.

Recover a store that cannot open

Mellow surfaces failed stores in the storage diagnostics rather than silently discarding them. First record the specific store and error. A locked or inaccessible Keychain, missing encryption key, damaged file, and unwritable folder require different fixes.

Retry attempts to open the store again after the underlying issue is corrected. Reset moves an unreadable store into quarantine and creates an empty replacement. Reset restores an empty feature state; it does not recover the original contents. Preserve the quarantined file if later key recovery or repair is possible.

If you rotate the storage key, let Mellow perform the coordinated operation across covered stores. Replacing a key outside that workflow can make existing ciphertext unreadable.

Storage-key reference

Encrypted mode uses a 32-byte data-encryption key. The current Keychain service is com.latticeruntime.mellow.storage, with account data-encryption-key. This is diagnostic information, not an instruction to edit or delete the item manually. App signing and Keychain authorization affect whether a build can read it.

An optional master-derived storage key uses HKDF-SHA256 with the mellow-storage-v1 context and a saved salt. The salt sidecar alone cannot decrypt the data. Do not assume this optional mode is enabled simply because local identity recovery is configured.

The .storage-encryption.json marker records the desired mode and remains readable so startup can determine the storage policy without first opening an encrypted database. The actual file header still determines how an existing store is opened.

Attachments and file history

Large attachments can be stored separately from their database rows. Copying only the database can therefore leave missing images or documents. Back up the blobs alongside the conversation records.

File History records supported agent file changes so they can be reviewed or reverted. Retention can follow chat lifetime or a time window, and a size limit can remove older history. Once a snapshot is removed, the corresponding rollback may no longer be possible. File History is not a replacement for a full backup of a working folder.

Deleting a chat can also remove its history. Review retention before using chat deletion as an organizational shortcut when you still need a rollback record.

Maintenance and limits

Mellow performs periodic SQLite optimization, checkpointing, and space reclamation for registered stores. Large write-ahead-log files can reflect active or poorly closed transactions. Do not delete a -wal file while the application is using its database.

Plugin data may have its own lifecycle and maintenance behavior. Inspect the plugin's supported export path before removing it. A plugin that writes outside Mellow's managed stores is not automatically covered by the main export.

Unexpected size growth: compare models, attachments, file history, activity retention, and plugin data separately.

Missing attachments after restore: verify the blob directory was copied with the database.

Mixed encryption state: review conversion progress and individual failures before toggling repeatedly.

Database error after a new build: check signing and Keychain access before assuming corruption.

See Security for data boundaries and Memory for what is retained as agent context.