Aletheia configuration reference: environment variables, settings and data directory

Aletheia (aletheia-mem) is configured in two ways: environment variables read at start-up, and a small set of runtime settings stored in the hub database. This page lists both, and the files that appear in the data directory.

Defaults come from src/config.mjs and src/hub/settings.mjs. Command output on this page was produced on 2026-10-29 by version 0.1.10 in a temporary home and data directory. A command shown without output was not run.

Set an environment variable

Set a variable in the shell that starts the command, or in the service unit that starts the server. A hook command runs with the environment of the host that starts it. If you use a custom ALETHEIA_DATA_DIR, set it in the host's environment too, or hooks write to the default directory.

$ ALETHEIA_DATA_DIR=/srv/aletheia ALETHEIA_PORT=37800 aletheia-server

Server and network

Paths and files

Capture and privacy

Redaction has no switch. See Privacy and redaction.

Extraction and model providers

With no provider, Aletheia extracts facts with a rule-based extractor and makes no model call. See Model providers.

Optional embeddings

Semantic search needs the optional package @huggingface/transformers. The first use downloads the model (about 35 MB per the source comment) into <HOME>/.aletheia/models. That cache is not under ALETHEIA_DATA_DIR.

• ALETHEIA_TRANSFORMERS_FROM: a folder whose node_modules holds the package.
• ALETHEIA_EMBED_MODEL: only changes the model name shown by aletheia doctor and /healthz. The embedder in the code reads no variable and uses Xenova/bge-small-en-v1.5.

Sync passphrases and test variables

• ALETHEIA_SYNC_PASSPHRASE: the passphrase for the aletheia sync encryption commands. --passphrase overrides it.
• ALETHEIA_SYNC_OLD_PASSPHRASE, ALETHEIA_SYNC_NEW_PASSPHRASE: used by aletheia sync change-passphrase.
• ALETHEIA_FAKE_RESPONSE, ALETHEIA_FAKE_FILE, ALETHEIA_FAKE_DELAY_MS: feed the fake provider that the tests use.
• WORK_STATE_TEAM_MODE (1) and ALETHEIA_BUG_COMPAT (1): legacy switches on the claude-mem source reader.

Runtime settings

Runtime settings live in the settings table of hub.db, under the key ui.settings.<name>, as JSON. They survive a restart. There is no command-line command for them. Change them in the dashboard under Connections, then Settings, or with PUT /api/hub/settings. A value outside its range is refused with a 400 and a message.

These three are the only runtime settings. Version 0.1.10 also showed provider, providers, factBudget.maxEpisodes, factBudget.maxChars, redaction, excludedProjects and apiKey in the form, but no code read them, so they were removed. The provider, its chain and key, the fact budgets and the excluded projects are environment variables (see above), and redaction always runs. A value saved under one of the removed keys stays in the table and does nothing.

$ curl -s -X PUT http://127.0.0.1:37790/api/hub/settings -H "Content-Type: application/json" \
    -d '{"facts.minConfidence":0.6,"context.facts":"on","rules.reviewDays":30}'
{"settings":[...],"saved":["facts.minConfidence","context.facts","rules.reviewDays"]}
$ curl -s -i -X PUT ... -d '{"facts.minConfidence":2,"context.facts":"maybe"}'
HTTP/1.1 400 Bad Request
{"error":"facts.minConfidence must be a number between 0.3 and 0.9 context.facts must be one of auto, on, off"}

Both calls ran against a temporary server on another port. The rows were stored as ui.settings.context.facts = "on", ui.settings.facts.minConfidence = 0.6 and ui.settings.rules.reviewDays = 30.

The data directory

Aletheia keeps the data directory at mode 0700 and its databases at 0600, and repairs looser modes with a one-line message on stderr. aletheia doctor reports them. This is what a data directory held after running save, install claude-code --write, a hook that could not reach the store, alerts add, sync pair, sync status, team create, watch --once, service install --write and erase --apply:

alerts.db              spool
alerts.db-shm          sync-client.db
alerts.db-wal          sync-client.db-shm
aletheia.bundle.mjs    sync-client.db-wal
erasure-exports        sync.db
erasure-receipts       sync.db-shm
erasure.key            sync.db-wal
hub.db                 sync.db.aletheia-bak-2026-10-29T19-49-58-125Z
hub.db-shm             team.db
hub.db-wal             team.db-shm
install-manifest.json  team.db-wal
service-manifest.json  watcher.db

• hub.db holds memories, facts, rules, the extraction queue and the settings table. -wal and -shm are SQLite's write-ahead files.
• spool/hook-spool.jsonl holds redacted hook items the store could not take. The next hook drains it. See Hooks reference.
• install-manifest.json and aletheia.bundle.mjs come from aletheia install --write: the files written per tool, and the single-file runner a hook loads.
• sync.db appeared with a one-time copy sync.db.aletheia-bak-<time>. sync-client.db is this device's replica.
• erasure.key, erasure-receipts/ and erasure-exports/ appear after aletheia erase --apply.
• Starting aletheia-server adds overlay.db and work-view-reviews.db.

See Operations for backup and growth, and Data model for the tables.

Next steps

• CLI reference - the commands that read these paths and settings.
• Hooks reference - how the spool and the excluded-project list work.
• Model providers - choose and test a provider.
• Run as a service - set these variables in a service unit.