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.

The form lists seven more keys: provider, providers, factBudget.maxEpisodes, factBudget.maxChars, redaction, excludedProjects and apiKey. They are saved in the table, but in version 0.1.10 I found no code that reads the saved value. The active values come from the environment variables above, and redaction always runs. A fresh hub shows placeholder values for them in the form (1, 100, false), which are not the active values.

$ 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.