Data Storage

The thing most cloud-based writing tools never tell you, but which quietly shapes everything about the experience, is that your manuscript doesn’t actually belong to you while you’re using them. It belongs to their database, on their server, in their format, accessible only through their UI. If the company folds, your work is in a format you can’t read. If the API breaks, your editing session pauses until someone else fixes it. If you lose network, you lose access to your book. This is the SaaS default, and it’s normal enough that most authors accept it without thinking. Ishvana is built on the opposite bet — that a writing tool for long-term projects should keep the data on your machine, in formats you can open with other tools, under your complete control. This page is the specific explanation of how that works. Where files live, what formats they use, how to back them up, what happens if Ishvana stops running.

The data directory

Every Ishvana project stores its data in a data directory — a folder on your machine that contains everything the project cares about. By default it’s next to the Ishvana install, but you can point Ishvana at any directory you want through the ISHVANA_DATA_DIR environment variable.

The data directory’s structure looks like this:

data/
├── documents/          <- DOCX files (manuscript content)
├── books/              <- Per-book settings and metadata
├── attachments/        <- Images and other assets attached to lore
├── backups/            <- Automatic backup snapshots
├── cache/              <- Disk cache for expensive computations
├── chromadb/           <- Vector embeddings for semantic search
├── config/             <- Your settings and preferences
├── credentials/        <- Encrypted API keys for LLM providers
├── data_exports/       <- Exported data you generate
├── email/              <- Email account data and local mail cache
├── exports/            <- Document exports in various formats
├── ishvana.db          <- Main SQLite database (all structured data)
├── lore.db             <- Legendry database (lore entries and entities)
├── logs/               <- Error logs and crash dumps
├── ml/                 <- Machine learning model artifacts and cached results
├── research/           <- Research bookmarks and content
├── settings/           <- Detailed preference and configuration data
└── templates/          <- Document and project templates

Each subdirectory has a specific purpose. None of them are magic — they’re regular folders with regular files. You can browse them with your file manager, you can copy them, you can back them up, you can inspect them.

Structured data: SQLite

The bulk of Ishvana’s metadata lives in SQLite databases. SQLite is a file-based relational database — the whole database is one .db file that you can open with any SQLite tool if you want to inspect or export the data directly.

Ishvana uses several SQLite databases for different concerns:

• ishvana.db — The main application database. Contains user settings, session history, writing analytics, marketing assets, sales records, alert histories, and most project-level metadata.
• lore.db — The Legendry database. Contains lore entries, entity definitions, relationships, section content, voice profiles, and the entity graph. Separate from the main database because it’s accessed heavily during writing and keeping it in its own file makes it easier to back up or migrate.
• data/sql/ishvana.db — A subsidiary database for background services and queue state.
• data/worldknowledge/wikipedia.db — The local Wikipedia mirror used by the WorldKnowledge agent for fact-checking.
• data/import_export.db — Tracking for document import and export operations.

SQLite is chosen over alternatives (Postgres, MySQL, NoSQL databases) for one specific reason: it has no server. The database is a file. Backing up Ishvana is as simple as copying the data directory — no database dumps, no daemon, no network. When you close Ishvana, the database goes to rest. When you open it again, everything is exactly where you left it.

You can inspect the databases directly

SQLite is an open format. If you want to run a query directly against your Legendry or export the raw data, you can use any SQLite browser (DB Browser for SQLite is a good free option). The databases are not encrypted at rest by default — the assumption is that your filesystem is where encryption belongs, not the database file itself. If you need database-level encryption, that’s a configuration option worth raising.

Document content: DOCX files

Your actual manuscript text — the prose you write in the editor — does not live in SQLite. It lives as DOCX files on disk, one file per document. The files are in data/documents/ and named by the document’s UUID.

DOCX (Microsoft Word format) is chosen as the document format for three reasons:

1. It’s universally readable. Every modern word processor can open DOCX. If Ishvana stopped existing tomorrow, your manuscripts would still open in Word, LibreOffice, Google Docs, Pages, and every other major tool.
2. It preserves formatting. Unlike plain text or Markdown, DOCX stores styles, headings, emphasis, and structure. When Ishvana’s editor displays your chapter with proper paragraph breaks and inline formatting, that formatting survives in the DOCX file.
3. It’s stable. The DOCX format is a stable standard with decades of tooling around it. It’s not going to become unreadable in five years.

The SQLite database’s writing_documents table has a row for each document with metadata (title, UUID, word count, modification time, etc.) but the content column is deliberately left NULL — the content lives in the DOCX file, not in the database. This split means:

• Metadata operations are fast. Listing documents, filtering by status, sorting by date — all of these run on the SQLite metadata without touching the large DOCX files.
• Content operations are isolated. When you open a document to edit it, Ishvana reads the DOCX file. When you save, Ishvana writes the DOCX file. No database transactions are involved in the content itself.
• Backup is simple. To back up your manuscripts, you can copy the data/documents/ folder. To back up your whole project, you copy the whole data directory.

Vector embeddings: ChromaDB

For semantic search — finding things by meaning rather than by keyword match — Ishvana uses ChromaDB, an open-source vector database. Vector embeddings from your manuscript, your Legendry, your research bookmarks, and various other content live in data/chromadb/ as a specialized file format.

ChromaDB isn’t general-purpose storage. It’s specifically designed for vector similarity search. When Ishvana wants to find “lore entries semantically similar to this paragraph,” it converts the paragraph to a vector embedding and asks ChromaDB for the nearest neighbors in vector space. ChromaDB returns the matches ranked by similarity, and Ishvana then looks up the corresponding entries in SQLite.

The vector embeddings are computed by a local embedding model — they don’t require sending your text to a cloud API. This matters because:

• Privacy. Your manuscript and lore never leave your machine, even for search operations.
• Cost. Embedding is free once you’ve computed it. Cloud embeddings are cheap but not free, and a large project has a lot of embeddings.
• Speed. Local embeddings run in milliseconds for a short query. The alternative (round-tripping to a cloud API) adds hundreds of milliseconds to every search.

There’s more detail on how semantic search actually works on the Semantic Search page.

Configuration and credentials

Your settings and preferences live in data/config/ and data/settings/ as JSON and YAML files. Things like your theme choice, your editor width, your model provider settings, your skills configuration.

API keys and other credentials live in data/credentials/, and they’re encrypted at rest using a machine-specific Fernet key. The encryption prevents a casual disk inspection from revealing your OpenRouter API key or your Anthropic key — the credentials file isn’t readable without Ishvana’s decryption.

Note that the encryption is machine-specific. If you copy the credentials folder to a different machine, the credentials won’t decrypt there. You’d have to re-enter them. This is a tradeoff — more portable credentials (e.g., a password-protected keystore) would be portable but less secure; machine-specific encryption is less portable but doesn’t require you to type a password every time you start Ishvana.

Backups

Ishvana creates automatic backup snapshots in data/backups/. The snapshots contain compressed copies of the main databases (ishvana.db, lore.db) plus any files that have changed recently. The backup schedule is configurable in settings — hourly, daily, weekly, or off.

Automatic backups are a safety net, not a replacement for your own backup strategy. If your entire data directory gets corrupted — hard drive failure, accidental deletion, ransomware — the backups in data/backups/ are gone too because they’re in the same directory. For real resilience, you want the whole data directory copied to another location: another drive, another machine, or a cloud backup service like Backblaze or Dropbox.

Backblaze is a solid default for desktop apps

If you don’t already have a backup strategy for your writing, Backblaze offers unlimited personal backups for a flat fee. Set it up to include your Ishvana data directory and you’ll be covered for disk failures and ransomware. Ishvana doesn’t recommend any specific service — this is just general advice for desktop app users who don’t have a strategy yet.

What local-first actually gives you

Three concrete things:

Offline operation. You can use Ishvana without an internet connection. The editor, the Legendry, the outline, everything except the cloud-based features (Hawken generation if using a cloud provider, Lagan research, WorldKnowledge Wikipedia lookups for uncached articles) works offline. If you’re running Ollama locally, even the agents work offline.

Company failure resilience. If Ishvana the company stops existing tomorrow, your project keeps working. You still have the DOCX files (openable in any word processor). You still have the SQLite databases (openable in any SQLite tool). You still have the ChromaDB vectors (openable with ChromaDB’s open-source library). You can’t run the Ishvana UI without the app itself, but the data is yours in readable formats.

Your data stays yours. No third party can access your manuscript through Ishvana. No telemetry uploads your prose to a server. No automatic “we’ll use your data to train our models” clause. The data lives on your machine and it stays on your machine unless you deliberately send it somewhere (running a cloud LLM call, publishing to KDP, exporting to a cloud service).

What local-first doesn’t give you

Honest limitations:

• No multi-device sync. Ishvana is a single-machine app. If you want to work on the same project from two computers, you have to sync the data directory yourself (via Dropbox, Syncthing, a git repo, or another sync tool).
• No multi-user collaboration. Ishvana isn’t designed for two authors editing the same document simultaneously. It’s a single-author tool.
• No automatic cloud backup. Unlike SaaS tools, Ishvana doesn’t automatically push your work to a server. Backups are your responsibility.
• Disk space matters. All your data lives on your drive. A large project with a multi-book Legendry, detailed analytics, and a full research bookmark library might eventually grow to multiple gigabytes. The cost is disk, not cloud storage fees.

What’s next

Semantic Search How ChromaDB and vector embeddings power search across all your data.

Cache & Performance Why the app stays fast even on large projects.

Background Services Auto-save and other services that protect your data continuously.