Environment Variables -- memQL

Audience: engineers running memQL locally or operating it in lab/prod. Last updated: 2026-04-25 (post env-var refactor; Phase 8 complete) Companion doc: copresent/docs/public/operate/env-vars.md covers the frontend side.

#TL;DR

memQL splits configuration into two tiers:

1. Bootstrap envelope -- a small set of OS environment variables the process must see before it can read anything else. Things like "where is Postgres", "what node am I", "what's the master encryption key". These are set in docker-compose.full.yml / docker-compose.cluster.yml (dev) or in the Cloud Run service manifest (prod). There is no encrypted-at-rest path for these -- they live in plain env.
2. Concept storage -- everything else. API keys, OAuth client secrets, model defaults, feature flags, mail-sender addresses, and any tunable a tenant might want to override. These live in four memQL concepts and are seeded via the make secrets-* / make variable-* workflow rather than env files.

The bootstrap envelope is intentionally tiny so that rotating an API key, changing a default model, or adding a new tenant's BYOK credential never requires a redeploy -- only a make variable-set or a re-seed of the operator's local yaml.

#Naming convention

Every env var name should answer "what subsystem owns this?" at a glance. The standard shape is:

<COMPONENT>_<VENDOR_OR_DETAIL>_<FIELD>

Where COMPONENT is the subsystem that consumes the value:

Frontend (VITE_* prefix is added by Vite to mark "safe to ship to the browser"):

#Anti-patterns to avoid

• Vendor-only names without a component prefix. AZURE_TENANT_ID is opaque -- Azure could mean storage, identity, OpenAI-on-Azure, or anything else. Always pair the vendor with the subsystem (EMAIL_AZURE_TENANT_ID).
• Two prefixes for the same thing. We had MAIL_* and AZURE_* for the same (email) integration; merging onto EMAIL_* with the vendor as the second segment removes that ambiguity.
• The MEMQL_ prefix where it's redundant. Inside the memQL repo, every var is "memQL's" -- prefixing every one of them with MEMQL_ is noise. Reserve MEMQL_ for things that are about memQL itself (master key, node identity, engine tuning), not for things memQL happens to call (OPENAI_API_KEY reads cleaner than MEMQL_OPENAI_API_KEY).

#Migration window

When a name changes (like AZURE_* -> EMAIL_AZURE_* in 2026-04), the consumer accepts both forms during a transition window so existing installs don't break. The pattern is:

1. Update the manifest + .env.local + docs to the new name.
2. Add a fallback in the consumer (Go integration / DSL provider) that tries the legacy name if the new one is empty.
3. Remove the legacy fallback in a follow-up commit once everyone has re-seeded.

Search for Legacy*EnvKeys / "legacy fallback" in the Go code to find the active migration shims.

#Future renames (deferred)

These would tighten the naming scheme but the change radius is too wide to justify in the same commit as the doc:

• MEMQL_SI_*_API_KEY -> SI_*_API_KEY. The MEMQL_ prefix is redundant inside the memQL repo and the dev manifest already seeds the bare form. Touches 6 provider .memql files plus Go bridge-agent and STT bootstrap; coordinate with manifest + user-yaml renames.

• VITE_BYPASS_AUTH -> VITE_AUTH_BYPASS, VITE_ENABLE_ADMIN -> VITE_FEATURES_ADMIN_ENABLED for stricter prefix consistency on the frontend.

If you're touching these areas anyway, fold the rename in. Don't do them as drive-by churn.

#The four concepts

Source files:

• concepts/v1/platform/secret/concept.memql
• concepts/v1/platform/variable/concept.memql
• concepts/v1/memql/secret/concept.memql
• concepts/v1/memql/variable/concept.memql

The _system partition is reserved for global concepts -- platform secrets and variables live there regardless of which partition the caller is in.

#Encryption

Secrets are sealed with NaCl secretbox (XSalsa20-Poly1305) under MEMQL_MASTER_KEY (32-byte hex). The cleartext is never stored; only base64(nonce || ciphertext) plus a 4-character fingerprint for UI display. See component/secret/encryption.go.

#Resolution chain (provider auth)

When a .memql provider file references a placeholder like env("MEMQL_SI_OPENAI_API_KEY"), the resolver in component/memql/si_providers.go (resolveAuthPlaceholders) walks:

1. v1:platform:globalSecret -- systemSecretResolver
2. v1:platform:globalVariable -- systemVariableResolver
3. OS env -- bootstrap-window fallback. See the note on bootstrap order below.

#Prefix elision

Provider .memql files historically reference MEMQL_SI_<VENDOR>_API_KEY while the dev manifest seeds the bare form (OPENAI_API_KEY, ANTHROPIC_API_KEY, ...). To bridge that gap without renaming either side, every layer of the chain tries both names in priority order:

authConceptLookupNames("MEMQL_SI_OPENAI_API_KEY")
  -> ["MEMQL_SI_OPENAI_API_KEY", "OPENAI_API_KEY"]

So a provider asking for MEMQL_SI_OPENAI_API_KEY will pick up a value seeded as OPENAI_API_KEY automatically. The same elision applies to the OS env fallback.

#Why OS env stays around

Providers are loaded eagerly during engine initialization. On a fresh make dev-refresh, the database wipe runs before the seed, so when providers first try to resolve their auth keys the concept storage is empty. The OS env fallback (populated from .env.local in dev or from the deploy manifest in prod) keeps providers alive through that bootstrap window until the seed completes.

Future work to retire the OS env fallback cleanly: either lazy per-request provider auth resolution, or a post-seed engine reload hook so providers retry concept storage once seeding finishes.

#Failure mode

A miss at every layer produces:

auth "apiKey" references MEMQL_SI_OPENAI_API_KEY but no value is in
concept storage or OS env. Tried name(s) MEMQL_SI_OPENAI_API_KEY,
OPENAI_API_KEY under v1:platform:globalSecret, v1:platform:globalVariable, and
the process env. Seed it with `make secret-set NAME=OPENAI_API_KEY
VALUE=... SCOPE=global` (or `variable-set` for non-sensitive values)

For partition-scoped resolvers (DSL resolveSecret(...) / resolveVariable(...)) the chain is:

1. v1:platform:partitionSecret -- partition row
2. v1:platform:globalSecret -- global row
3. (no env fallback for this path)

#Bootstrap envelope (set in env, not in concepts)

These are read at process startup. Putting any of them in a concept would be circular -- the process can't reach the concept without them.

#Required to start

#Required when the matching feature is enabled

#Optional with sensible defaults

#Node identity

#Transport

#Logging

#Database tuning

All optional. Defaults baked into component/database/database.go:

#Auth (Identity service + per-node verifier)

For the identity binary (-tags identity):

For every other binary (bff/voice/cognition/agent/planner):

See docs/public/operate/auth/identity-service.md for the full operator narrative (anti-abuse knobs, key rotation, email delivery).

#Feature toggles & engine tuning

#STT / voice (only if Polyphon or streaming STT is enabled)

#Infra metadata

#WebSocket tuning (rarely overridden)

All in component/server/memqlws/env.go:

#Concept-stored config

This is the table to look at when you ask "where do I put a new API key" or "where do I change the default model".

The authoritative manifest is scripts/secrets/manifest.yaml. Every entry in the manifest is what make secrets-init will prompt for and what make secrets-seed will push into the running memQL.

#Default global secrets (manifest)

Stored in v1:platform:globalSecret, sealed under MEMQL_MASTER_KEY.

#Default global variables (manifest)

Stored in v1:platform:globalVariable.

#Variables consumed by the CoPresent frontend

These aren't in the manifest yet -- operators add them via make variable-set -- but they're documented here because they live in v1:platform:globalVariable and are read by the CoPresent runtime config layer (src/lib/publicConfig.tsx):

The exact name on the memQL side has to match the entry in the publicConfig whitelist (src/lib/publicConfig.tsx) exactly. To add a new one: add it to the whitelist, then make variable-set NAME=... VALUE=... SCOPE=global.

#Per-tenant overrides

Anything in v1:platform:globalSecret / v1:platform:globalVariable can be overridden per-tenant by writing the same name into v1:platform:partitionSecret / v1:platform:partitionVariable with the tenant's partition stamped on the row.

The resolver always tries the partition-scoped row first and falls back to the global one. So a tenant with OPENAI_API_KEY in their partition's v1:platform:partitionSecret will use their own key; everyone else keeps using the platform default.

This is the BYOK ("bring your own key") path. The DSL surface is resolveSecret("OPENAI_API_KEY") and resolveVariable("..."); see component/memql/sense/builtins.go for the builtin docs.

#The yaml file (~/.memql/dev-secrets.yaml)

This is operator-local, gitignored, and dev-only. It is the plaintext stash of values that get encrypted-and-pushed to memQL on make secrets-seed.

Schema:

masterKey: <64-hex-character master key>     # 32 bytes hex-encoded
secrets:
  - name: OPENAI_API_KEY
    scope: global
    kind: vendor_api_key
    value: sk-proj-...
  - name: ANTHROPIC_API_KEY
    scope: global
    kind: vendor_api_key
    value: sk-ant-...
  ...
variables:
  - name: IDENTITY_BASE_URL
    scope: global
    value: https://auth.example.com
  - name: VITE_OPENAI_MODEL
    scope: global
    value: gpt-5
  ...

The yaml only matters for the dev-refresh workflow. In production:

• The MEMQL_MASTER_KEY env var is set explicitly on the deploy target.
• Secrets and variables are seeded once via Make targets pointing at the prod gRPC endpoint, after which they live in the database.

#Where the yaml lives in the bootstrap chain

1. make dev-refresh runs scripts/dev/refresh.sh.
2. require_master_key in scripts/dev/lib.sh calls go run ./scripts/secrets master-key, which reads ~/.memql/dev-secrets.yaml and prints the masterKey field.
3. The refresh script exports it as MEMQL_MASTER_KEY before docker compose up, so every container has the key in env.
4. After the stack is up, the same script runs go run ./scripts/secrets seed, which encrypts each yaml entry under the master key and upserts the row into the right concept over gRPC.

#Make targets

All driven by scripts/secrets/main.go:

dev-refresh does export -> wipe -> restart -> seed in one shot, so the yaml stays in sync as long as you go through that target.

#Master-key resolution order (in process)

component/secret/encryption.go reads MEMQL_MASTER_KEY from the OS env at first encrypt/decrypt call. There is no fallback. If absent when an encrypted secret is accessed, the process logs a fatal error. The yaml passthrough above is purely operator tooling -- it puts the key into the env before docker compose up. Inside the container, the value is just an env var.

For non-dev installs, set MEMQL_MASTER_KEY directly on the deploy target (Cloud Run env, Kubernetes secret, etc.). The yaml is never deployed.

#How the cluster wires (peer discovery)

In cluster mode (multiple node-typed binaries), each non-BFF node needs to know how to reach BFF, and BFF needs to know how to reach each worker:

• MEMQL_PARENT_ADDRESS -- set on every worker (cognition, agent, planner, voice). Tells the worker to dial BFF for outbound event forwarding.
• MEMQL_WORKER_PEERS -- set on BFF (and on cognition for its agent-only narrowing). Comma-separated type=address list. First- boot seed only; once peers register themselves into v1:cluster:node (a global concept), DB-based discovery takes over.

Both are bootstrap envelope vars -- they have to be in the env before the gRPC server starts.

docker-compose.full.yml and docker-compose.cluster.yml have full worked examples. The full compose is the BFF + cognition + agent + planner shape; the cluster compose adds voice.

#Adding a new entry: decision tree

Is the value sensitive?
├── Yes → secret
│   ├── Tenant-overridable (BYOK)? → v1:platform:partitionSecret (default), with v1:platform:globalSecret as the global default
│   └── Instance-only?              → v1:platform:globalSecret only
└── No → variable
    ├── Tenant-overridable?          → v1:platform:partitionVariable (default), with v1:platform:globalVariable as the global default
    └── Instance-only?              → v1:platform:globalVariable only

If the value has to be available before memQL connects to its database (i.e. it controls how memQL connects), it's a bootstrap envelope var, not a concept entry. There's a strong bias against adding new entries to the bootstrap envelope -- it requires a deploy-config change every time it rotates.

#Adding a global secret

1. Append a row to scripts/secrets/manifest.yaml under secrets:.
2. make secrets-init (re-walks; only prompts for the new entry).
3. make secrets-seed.
4. Reference it from a provider/integration via env("YOUR_NAME") in .memql or os.Getenv("YOUR_NAME") in Go (the resolver chain works for both).

#Adding a global variable

1. Append a row to scripts/secrets/manifest.yaml under variables:, or set it ad-hoc with make variable-set NAME=YOUR_NAME VALUE=... SCOPE=global.
2. The DSL resolver returns it from resolveVariable("YOUR_NAME") or the same env() chain in provider auth.

#Adding a per-tenant (partition-scoped) entry

make secret-set NAME=... VALUE=... SCOPE=partition PARTITION=acme or the variable equivalent. The same resolver chain finds it automatically.

#Reference: file paths

#Operational notes

#Rotating a secret

# In the operator's local copy (dev):
make secret-set NAME=OPENAI_API_KEY VALUE='sk-proj-newvalue' SCOPE=global
 
# Or for prod, point the same target at the prod gRPC endpoint by
# setting MEMQL_GRPC_ENDPOINT in the calling shell.

The old row is soft-deleted (active=false); lastUsedAt / rotatedAt get stamped on the new row. The next decrypt picks the new value; nothing else has to restart.

#Backing up state before a wipe

make secrets-export

Pulls every active row from the running memQL, decrypts secrets locally with the master key, and merges the result into the yaml. Conflict resolution: memQL wins. Run this before any make dev-refresh that resets the database.

#"Why is my provider giving 'no value' errors?"

Check the resolver chain in order:

1. Is the row in v1:platform:globalSecret / v1:platform:globalVariable?

   shell⧉copy

   make secrets-list

   or in DSL: getQuery("queryConfigSecret", { name: "OPENAI_API_KEY" }).
2. Does the running memQL have MEMQL_MASTER_KEY set in env?
3. Is the master key the same one that encrypted the row? If you regenerated it, the existing rows are unreadable -- run make secrets-seed again to overwrite with the new key.

#Local override without polluting the yaml

make secret-set / make variable-set write directly to the running memQL without modifying the yaml. Useful for one-off experiments. Note that on the next dev-refresh the wipe-and-reseed will replace the value with whatever's in the yaml -- export first if you want to keep it.

#Migration history

The current shape is the result of an 8-phase env-var refactor completed 2026-04-25. Decision summary:

• Two concept trees (globalSecret / globalVariable and partitionSecret / partitionVariable) so per-tenant BYOK overrides fall back cleanly to the platform default.
• NaCl secretbox (XSalsa20-Poly1305) over AES-GCM for the encrypted half because it has a smaller surface, no nonce-reuse pitfalls when keys aren't rotated, and the Go stdlib has no native AES-GCM with built-in random nonces.
• OS-env fallback stays because providers initialize eagerly at engine boot, before the seed step has populated concept storage. The fallback keeps the BFF alive through that bootstrap window. A lazy per-request resolver or a post-seed engine-reload hook would let us retire it.