Environment Variables

The Graphnosis sidecar (graphnosis-sidecar) reads its configuration from environment variables.

In normal use you do not set any of these. The Graphnosis desktop app sets them automatically each time it spawns the sidecar for the active cortex. They are documented here for headless / standalone runs and for debugging.

cortex & unlock

Variable	Required	Default	Description
`GRAPHNOSIS_CORTEX`	Yes	—	Absolute path to the cortex folder. The sidecar will not start without it.
`GRAPHNOSIS_PASSPHRASE`	No	—	Unlocks the cortex non-interactively. Use only in trusted environments — see the security note below. If unset, the app’s unlock prompt is used.
`GRAPHNOSIS_RECOVERY_PHRASE`	No	—	The 24-word recovery phrase, as an alternative to `GRAPHNOSIS_PASSPHRASE` for unlocking.
`GRAPHNOSIS_DEVICE_ID`	No	`<hostname>-<pid>`	Identifier recorded in the op-log for changes made from this device.
`GRAPHNOSIS_DEFAULT_GRAPH`	No	`personal`	The engram an ambient `remember` writes to when no target engram is given.
`GRAPHNOSIS_POLICY`	No	—	Path to a JSON file defining per-engram sensitivity tiers. Without it, all engrams use default policy.

Local LLM

Variable	Required	Default	Description
`GRAPHNOSIS_LLM`	No	—	The local LLM model id the sidecar should load (e.g. `llama-3.2-3b`). The optional Local LLM powers `develop` / `predict` / `insights` and the LLM-assisted `edit` path. When unset, no model id is pre-selected.

Embedding

Variable	Required	Default	Description
`GRAPHNOSIS_EMBED_WORKERS`	No	`2`	Number of parallel embedding worker processes. Raise it on machines with more cores to speed up ingest.
`GRAPHNOSIS_EMBED_CACHE`	No	platform cache dir	Directory for the embedding cache.
`GRAPHNOSIS_EMBED_CACHE_DIR`	No	`$HOME`	Directory an embedding worker process uses for its model / tokenizer cache.
`GRAPHNOSIS_EMBED_DISABLE`	No	—	Set to `1` to disable on-device embeddings entirely. Debugging only — recall quality degrades sharply without embeddings.

Sockets

The sidecar communicates over Unix domain sockets. The app assigns these paths; override them only for unusual multi-instance setups.

Variable	Required	Default	Description
`GRAPHNOSIS_MCP_SOCKET`	No	`~/.graphnosis/mcp.sock`	Unix socket the MCP server listens on. The app sets this to a fixed per-user path so an MCP client configured once keeps working across cortex switches. Falls back to `<cortex>/mcp.sock` when unset.
`GRAPHNOSIS_IPC_SOCKET`	No	`<cortex>/sidecar.sock`	Unix socket for desktop-app ↔ sidecar IPC.
`GRAPHNOSIS_EVENTS_SOCKET`	No	`<cortex>/events.sock`	Unix socket the sidecar emits live events on.

MCP relay

Variable	Required	Default	Description
`GRAPHNOSIS_RELAY_WAIT_MS`	No	built-in	Initial wait, in milliseconds, before the MCP relay first connects.
`GRAPHNOSIS_RELAY_RECONNECT_MS`	No	built-in	Interval, in milliseconds, between MCP relay reconnection attempts.

Admin policy (enterprise)

Centrally disable specific connectors (incoming data) and AI clients (outgoing memory access). The effective policy is the union of these variables and a policy.json placed in the cortex folder. When the policy is marked managed, a local user can’t override it from the Settings UI.

Variable	Required	Default	Description
`GRAPHNOSIS_DISABLED_CONNECTORS`	No	—	Comma-separated connector kinds that must not mount (e.g. `slack,github`). A disabled connector is skipped on startup and won’t start even if configured.
`GRAPHNOSIS_DISABLED_CLIENTS`	No	—	Comma-separated AI client names whose MCP tool calls are rejected. Matching is case-insensitive.
`GRAPHNOSIS_DISABLED_PROVIDERS`	No	—	Comma-separated model provider ids blocked from Ghampus routing (e.g. `anthropic,openai`). Blocked providers show a lock badge in Settings → Models and cannot be enabled locally when policy is managed.
`GRAPHNOSIS_MANAGED_POLICY`	No	—	Set to `1` to mark the policy as centrally managed — `policy.set` from the app is rejected, so a local user can’t loosen an IT-pushed policy.

For per-cortex configuration, place a policy.json in the cortex folder with disabledConnectors, disabledClients, disabledProviders, pinnedRates, and managed fields; it merges with the variables above.

Recall latency benchmark

Used by the smoke-test regression guard and the pre-release manual benchmark script. See Performance and recall latency.

Variable	Required	Default	Description
`GRAPHNOSIS_SKIP_RECALL_LATENCY`	No	—	Set to `1` to skip the `recall-latency-regression` phase in `smoketest`.
`GRAPHNOSIS_RECALL_LATENCY_P50_MS`	No	`200`	Fail when warm recall P50 exceeds this many milliseconds.
`GRAPHNOSIS_RECALL_LATENCY_RUNS`	No	`5` (smoke) / `10` (manual script)	Timed recall iterations after warm-up.
`GRAPHNOSIS_RECALL_LATENCY_QUERY`	No	connect-AI-client query	Query string used for timed recalls.
`GRAPHNOSIS_RECALL_BENCH_GRAPH`	No	`personal`	Engram id for `scripts/recall-benchmark-manual.mjs` only.

Internal

GRAPHNOSIS_WORKER_ROLE is set by the sidecar on itself when it forks an embedding worker process. Do not set it manually.

Example: running the sidecar standalone

GRAPHNOSIS_CORTEX="/Users/you/Documents/MyCortex" \
GRAPHNOSIS_PASSPHRASE="your-passphrase" \
graphnosis-sidecar

Security note on `GRAPHNOSIS_PASSPHRASE`

Passing your passphrase as an environment variable means it may be visible in process listings (ps aux) and in any config file that holds it on disk. Only use it on a machine you control, with software you trust. For interactive use, leave it unset and unlock through the app’s prompt instead.

Boot & Engram Loading — how these variables shape startup.

Performance and recall latency — smoke-test P50 guard and manual benchmark script.

Graphs & Sensitivity Tiers — what GRAPHNOSIS_GRAPHS actually scopes.

What Leaves Your Device — relevant when you enable the HTTP MCP bridge.

File Formats — the files these paths point at.