Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pewdiepie-archdaemon/odysseus/llms.txt

Use this file to discover all available pages before exploring further.

All Odysseus user data lives in the data/ directory at the root of the project. This includes your chat history, uploaded files, memories, skills, settings, user accounts, and anything else that persists between restarts. The directory is gitignored by default, so it is never included in commits or forks. Keeping a regular backup of data/ is the only thing you need to do to protect your Odysseus data.

​
What Is in data/

PathContents
app.dbSQLite database — sessions, messages, documents, tasks, calendar events, email accounts
memory.jsonFlat memory store for persistent agent memories
memory_doc.mdLong-form memory document
uploads/Files uploaded through the chat or document interface
personal_docs/Personal documents and runbooks
chroma/ChromaDB vector store data (used for semantic memory search)
settings.jsonApp settings
auth.jsonUser accounts (credentials, roles, privileges)
sessions.jsonActive session tokens
presets.jsonSaved chat presets
data/ contains sensitive information: API keys, email credentials, user password hashes (bcrypt), active session tokens, and uploaded files. Keep this directory private. Never commit it to Git, include it in a public archive, or store it in an unencrypted location.

​
Built-In Backup (Export)

Odysseus includes a built-in export tool available at Settings → Backup (admin only). Clicking Export creates a downloadable JSON archive containing:
  • Memories
  • Skills
  • Presets
  • App settings
  • Feature flags
  • User preferences
This is a fast, in-app snapshot useful for migrating settings and personal data between instances or for sharing a configuration. The export is in JSON format and can be re-imported via Settings → Backup → Import.
The built-in export covers memories, skills, presets, settings, and preferences. It does not include the SQLite database (app.db), uploaded files, ChromaDB vector data, or auth/session files. For a complete backup, use the manual file-copy approach below.

​
Manual Full Backup

For a complete, consistent backup of everything in data/, stop the app before copying. Copying while the app is running risks a partial read of the SQLite database mid-write. 
# Stop the app first for a consistent backup
docker compose stop odysseus

# Copy the entire data/ directory with a datestamp
cp -r data/ data-backup-$(date +%Y%m%d)/

# Start the app again
docker compose start odysseus
For native installs, stop the uvicorn process, copy data/, then restart.
For Docker deployments, data/ is bind-mounted from the host into the container. This means it survives container recreation, image rebuilds, and docker compose down (without -v). Your data persists through routine updates automatically — you only need to manage backups of the host-side data/ directory.

​
Restoring from Backup

1

Stop the app

docker compose stop odysseus
2

Replace the data/ directory

# Move the current data/ out of the way
mv data/ data-pre-restore-$(date +%Y%m%d)/

# Put the backup in place
cp -r data-backup-20240101/ data/
3

Start the app

docker compose start odysseus

​
Moving data/ to a Different Location

Use the ODYSSEUS_DATA_DIR environment variable to move the entire data/ tree to a different path — useful for storing data on a NAS, external drive, or a separate volume. 
# .env
ODYSSEUS_DATA_DIR=/mnt/nas/odysseus-data
All paths that Odysseus writes under data/ — settings, auth, sessions, uploads, skills, memories — will use this root instead.

​
External SQLite Path

By default, the SQLite database lives at data/app.db. You can point it to a different file using the DATABASE_URL variable: 
# .env
DATABASE_URL=sqlite:////mnt/nas/odysseus-data/app.db
This is useful when you want the database on a separate volume from the rest of data/, or when you want an explicit path rather than the relative default.

​
External ChromaDB

If you run ChromaDB as a separate external server rather than using the embedded instance, the vector store data is managed independently of data/chroma/. Configure the external host and port in .env: 
# .env
CHROMADB_HOST=my-chromadb-server
CHROMADB_PORT=8000
In this configuration, backing up ChromaDB data is the responsibility of that external server’s own backup procedure. The data/chroma/ directory will be empty or unused.

​
Encryption of Stored Secrets

IMAP and SMTP credentials stored in app.db are encrypted at rest using a Fernet symmetric key stored at data/.app_key (mode 0o600 on POSIX). This protects against database file exfiltration — for example, a stolen backup or a leaked container layer — but does not protect against a full process compromise where an attacker can read the key file alongside the database.
If you share a data/ backup with another Odysseus instance, copy data/.app_key alongside it. Without the matching key, encrypted email credentials in app.db will fail to decrypt and those email accounts will appear unconfigured.

Build docs developers (and LLMs) love

Get started for freeTalk to us