Data Management

Everything in QARK lives in a local SQLite database and a companion data directory on your machine. No cloud sync, no remote dependency.

Database and File Structure

QARK stores data in a .qark directory in your home folder:

Platform	Path
macOS	`~/.qark/`
Windows	`C:\Users\{username}\.qark\`
Linux	`~/.qark/`

The directory contains:

~/.qark/
├── qark.db                          SQLite database
├── attachments/                     conversation attachments
│   └── {conversation_id}/
├── documents/                       RAG source documents
│   └── {conversation_id}/
├── vectors/                         LanceDB vector stores
│   └── {conversation_id}/
├── generated_images/                image generation outputs
│   └── {conversation_id}/
├── generated_videos/                video generation outputs
│   └── {conversation_id}/
└── agent_tool_results/              sub-agent output files
    └── {conversation_id}/

The qark.db file contains conversations, messages, agents, flows, prompts, settings, provider configs, budgets, cost ledger, MCP server definitions, and document metadata. Binary files (images, videos, documents, vectors) are stored on the filesystem and referenced by the database.

Export Conversations

Export any conversation or group in 3 formats:

Format	Output	Use Case
Markdown	`.md` file	Version control, plain-text archives
HTML	`.html` file + `{name}_assets/`	Browser-viewable archive with formatting, interactive branch navigation
PDF	`.pdf` file + `{name}_assets/`	Formal documentation, offline sharing

The asset folder contains all images, videos, and attachments referenced in the conversation.

PDF export uses a locally detected Chromium-based browser (Chrome, Arc, Brave, Edge, Chromium) in headless mode. If no browser is found, PDF export is unavailable — Markdown and HTML still work.

Export scope:

Single conversation — from the conversation menu or command palette
Single message — right-click a message → Export
Group — right-click a group → Export Group (exports all conversations in the group)

HTML Branch Support

HTML exports preserve the full branch structure. When a conversation has branched messages (from regeneration or editing), the HTML output includes interactive sibling navigation — the same X/Y branch indicators you see in the app.

Export and Import Agents, Flows, Prompts

All three use JSON format and follow the same pattern:

Entity	Export	Import
Agents	Agent context menu → Export, or select multiple → Export Selected	Agents panel → Import
Flows	Flow context menu → Export, or Export Selected / Export All	Flow library → Import
Prompts	Prompt context menu → Export, or Export Selected / Export All	Prompt library → Import

What transfers: System prompts, tool configs, model assignments, input/output schemas, categories, tags, favorites, sort order.

What needs resolution: Agent references (@AgentName format) are resolved by name during import. If the target installation does not have an agent with that name, the reference is cleared. Provider-specific model IDs may need adjustment if the recipient uses different providers.

Duplicate detection: On import, items with matching title and content are skipped.

Archive vs. Trash

Action	What Happens	Recovery	Auto-Purge
Archive	Sets `is_archived` flag. Removed from sidebar, appears in Archive view.	Unarchive from Archive view	Never — archived items persist indefinitely
Trash	Sets `deleted_at` timestamp. Removed from sidebar, appears in Trash view. Active streams are cancelled.	Restore from Trash view	30 days — auto-purged on app startup

Archive is for conversations you are done with but may revisit. Trash is for items you intend to discard.

Auto-Purge

On every app launch, QARK automatically and permanently deletes conversations and groups that have been in trash for more than 30 days. This hard delete:

Removes database rows (messages cascade-delete with conversations)
Cleans up filesystem directories (attachments, documents, vectors, generated images/videos)
Cost ledger entries are preserved (the conversation_id is nullified but the cost record remains)

Empty Trash

To immediately purge all trashed items without waiting 30 days, use Empty Trash from the Trash view. This is irreversible.

Back Up Your Data

QARK has no built-in backup feature. Backup strategies:

System backup tools — Include ~/.qark/ in Time Machine (macOS), File History (Windows), or your backup tool of choice. This captures the database and all files.

Manual database copy — Close QARK, copy ~/.qark/qark.db to your backup location, restart. Copying while QARK is running risks capturing an incomplete write.

Entity-level export — Export agents, flows, and prompts as JSON files. Store these in Git alongside project code for version-controlled prompt engineering.

Orphan Cleanup

On startup, QARK checks for filesystem directories (attachments, documents, vectors, generated media) that reference conversations no longer in the database. These orphaned directories are cleaned up automatically, preventing disk space accumulation from deleted conversations.

The cleanup follows a strict order: database records are authoritative. If a directory exists on disk but has no matching conversation in the database, the directory is removed.

Reset Data

Three scoped reset options in Settings:

Option	Clears	Keeps
Clear Providers	All provider configurations and API keys	Conversations, agents, flows, prompts, settings
Clear Conversations	All conversations and their RAG indexes	Providers, agents, flows, prompts, settings
Reset Everything	All application data — returns QARK to first-launch state	Nothing

Each reset requires confirmation. Reset Everything is irreversible — back up your database first.