Axiom StudioAXIOMSTUDIO
All docs

Configuration

Memora is configured from three layers — a TOML file, environment variables, and command-line flags — resolved in that order. This page lists every key each layer accepts, its type, and its default.

How Configuration Resolves

Later sources override earlier ones, so a flag beats an environment variable, which beats the file, which beats the built-in defaults.

built-in defaults → TOML file → environment variables → command-line flags

The file is found by taking the first path that exists from this list:

$MEMORA_CONFIG → --config → ~/.memora/config.toml → ./memora.toml → (defaults only)

Paths inside the file that begin with ~/ are expanded against the current user's home directory. When no file is found, the built-in defaults apply and nothing is reported as missing.

Two subcommands exist to inspect the result rather than infer it:

memora-core print-config     # render the resolved config, secrets replaced with ***
memora-core check-config     # validate it; prints "config ok" or exits 78

Both accept --config and both apply the environment layer, so they show what the server would see. check-config exits 78 on any validation error, which makes it usable as a deployment gate.

Server Keys

TOML table [server].

KeyTypeDefault
server.addrstring:7777
server.modestringsingle-tenant
server.api_keystring(empty)
server.api_key_filestring(empty)
server.allow_no_authboolfalse
server.mcp_enableboolfalse
server.ui_cookie_securestring(empty — always on a non-loopback addr, auto on loopback)

server.mode accepts single-tenant or multi-tenant; any other value fails validation. In single-tenant mode the workspace comes from the request path. In multi-tenant mode the X-Memora-Workspace header resolves it per request.

server.api_key and server.api_key_file are mutually exclusive, and setting both fails validation. The file form is the safer one for deployments that mount secrets, and Memora refuses to read a key file that is world-readable, reporting the offending mode — so the file must be 0600 or 0640.

server.mcp_enable mounts an MCP WebSocket endpoint at /mcp on the HTTP server, in addition to the stdio transport that memora-core mcp provides.

server.ui_cookie_secure sets whether the console's session cookie is marked Secure: always, never, or auto, which marks it Secure only when the request itself arrived over TLS. Behind a TLS-terminating reverse proxy or Ingress the server only ever sees plain HTTP, so auto would never mark it Secure there; that is why the default on a non-loopback address is always. A Secure cookie is named __Host-memora_session and the console also sends Strict-Transport-Security. If users reach the console over plain HTTP on a non-loopback address, browsers drop a Secure cookie and login loops back to the login page; set auto for that setup, and the server logs a warning the first time it happens.

allow_no_auth is an override, not a convenience. With no API key configured, the server starts on a loopback bind and refuses to start on any other address. Setting allow_no_auth suppresses that refusal, leaving the API unauthenticated on a reachable address. See Operations before using it.

TLS Keys

TOML table [server.tls].

KeyTypeDefault
server.tls.enabledboolfalse
server.tls.cert_filestring(empty)
server.tls.key_filestring(empty)
server.tls.auto_self_signedboolfalse

Enabling TLS requires either a cert_file and key_file pair or auto_self_signed; without one of those, validation fails. When the key file's permissions allow group or world access, the server logs a warning naming the path and mode but still starts.

TLS is file-only. There is no environment variable or serve flag for any of these keys.

Storage Keys

TOML table [storage]. Each seam takes a driver name and an optional DSN.

KeyTypeDefault
storage.data_dirstring./data
storage.metadata_driverstringsqlite
storage.metadata_dsnstring(empty — falls back to <data_dir>/memora.db)
storage.vector_driverstringsqlite-vec
storage.vector_dsnstring(empty — falls back to <data_dir>/memora.db)
storage.graph_driverstringsqlite_graph (set "none" to disable the graph)
storage.graph_dsnstring(empty — falls back to the metadata DSN)
storage.ledger_driverstringsqlite
storage.ledger_dsnstring(empty — falls back to <data_dir>/memora.db)
storage.content_driverstring(empty — content store disabled)
storage.content_dsnstring(empty — see below)

At the defaults, four of the five seams share one SQLite file at <data_dir>/memora.db and the content store is switched off entirely, which is what makes a fresh instance dependency-free.

sqlite_graph stores edges in the SQLite metadata database, so it requires metadata_driver = "sqlite"; check-config rejects any other combination. With a non-SQLite metadata store, set graph_driver = "none" (or MEMORA_GRAPH_DRIVER=none) to run without the context graph; an empty string also disables it, but cannot be set through the environment. With the graph disabled, graph operations report that the graph store is not configured.

The content store is the one seam that is off rather than defaulted. When content_driver is set and content_dsn is not, the DSN becomes the SQLite database for the sqlite driver and <data_dir>/content for any other driver. See Adapters for which drivers each seam accepts.

Embedding Keys

TOML table [embedding].

KeyTypeDefault
embedding.modelstringnoop:default
embedding.asyncboolfalse

The value is a prefix:model string where the prefix selects the provider. The default provider is a stub that returns meaningless vectors; set a real one before evaluating recall quality.

local:nomic-embed-text-v1.5 (a binary built with -tags local_embed, plus the libllama_go shared library) runs a GGUF model on the node. The model file nomic-embed-text-v1.5.Q8_0.gguf lives in $MEMORA_MODEL_DIR (default ~/.memora/models). If it is missing, it is downloaded from a fixed Hugging Face commit and kept only if its SHA-256 is 3e24342164b3d94991ba9692fdc0dd08e3fd7362e0aacc396a9a5c54a544c3b7. A file already in the directory is checked against the same hash on every start and refused if it differs, so an offline node can be given a copy that it will verify.

By default a write embeds its changed Cells before it returns, so an imprint responds with recall_ready: true. With embedding.async = true the write returns as soon as the Cells are stored and a background worker pool embeds them: imprint responds with recall_ready: false, and the Memory's recall_ready turns true once all of its Cells have vectors. Poll a lookup to see when it does. The re-embedded and skipped Cell counts in write responses and the ledger are the same in both modes. On shutdown the server finishes embedding the queued Cells before closing its stores.

Node Keys

TOML table [node]. These identify this node to federation peers and in search results.

KeyTypeDefault
node.idstring (UUIDv4)(minted on first start)
node.namestringthe hostname

When node.id is unset, the node mints a UUIDv4 the first time it starts and stores it in the metadata store. It keeps that ID across restarts, including in containers without a config file. memora-core node id prints it. Set node.id only to pin a specific ID.

federation.inbound_qps caps how many requests per second each peer may send to this node's peer routes. It defaults to 100. federation.peer_timeout_ms (default 5000) and federation.outbound_qps (default 50) are the defaults for each peer's timeout_ms and rate_limit_qps.

Federation peers are listed under [[federation.peers]]. Each peer needs node_id, which is the peer's own node ID (run memora-core node id on the peer), plus name and url. federation.federation_id is optional; if set, it is a UUIDv4 label for the cluster.

Peer Credentials

Each direction between two nodes has its own key. The routes a peer calls, POST /v1/federation/search and GET /v1/federation/memories/{memory_id}, take that peer's key instead of the server API key. All other routes, including the peer-management routes under /v1/federation/peers, keep the API key.

KeyTypeDefault
api_keystring(empty)
inbound_key_sha256string (64 hex characters)(empty)
client_cert_sha256string (64 hex characters)(empty)
revokedboolfalse
timeout_msintfederation.peer_timeout_ms
rate_limit_qpsfloatfederation.outbound_qps
inbound_qpsfloatfederation.inbound_qps
tls_certstring (path)(empty)
client_cert_file, client_key_filestring (path)(empty)
  • api_key is the key this node sends when it calls the peer. It goes in X-Memora-Federation-Auth: Bearer <key>, and the node sends its node ID in X-Memora-Local-Instance-ID.
  • inbound_key_sha256 is the SHA-256 of the key the peer sends when it calls this node. Only the hash is configured, so the key never sits in this node's config, logs or responses. The comparison runs in constant time. A peer without it cannot call this node, and the server logs a warning at startup.
  • client_cert_sha256, when set, also requires the peer to present a TLS client certificate with this SHA-256 fingerprint. It needs server.tls; the server refuses to start without it.
  • revoked = true keeps the peer listed but refuses its calls, and leaves it out of federated searches.
  • timeout_ms and rate_limit_qps bound this node's calls to the peer during a federated search. A search's own timeout_ms overrides timeout_ms.
  • inbound_qps caps the peer's calls to this node. Over it, the peer gets 429 with Retry-After.
  • tls_cert is the CA certificate used to verify the peer's server certificate on outbound calls.
  • client_cert_file and client_key_file are the TLS client certificate this node presents when it calls the peer. Set both or neither. They pair with the peer's client_cert_sha256 for this node. A file that cannot be loaded stops the server at startup.

Peer URL Policy

Every peer URL, from the config file or added at runtime, must pass this node's URL policy, which only the config file sets:

KeyTypeEffect
federation.insecure_peer_hostslist of hostsPeers at these hosts may use http://. Over http the peer key travels in cleartext, so any other http:// peer is refused. Loopback hosts (localhost, 127.0.0.1, ::1) need no entry. The node logs a warning for each such peer when it loads them.
federation.private_peer_hostslist of hosts or CIDRsPeers may reach non-public addresses (loopback, RFC 1918 and fc00::/7 private, link-local such as 169.254.169.254, CGNAT, unspecified, multicast and reserved ranges) only if listed. A host name or IP entry lets that URL host resolve to any address; a CIDR entry allows the addresses inside it. Everything else is refused.

The address check runs when a peer is added over the API or console, on the addresses its host resolves to, and again on every connection, so a name that later resolves to an internal address is still refused. Peer calls do not use HTTP_PROXY/HTTPS_PROXY. A URL with a user name or password is refused. A refused call shows up in failed_peers as peer_address_refused. If a stored peer no longer passes the policy (for example, after an entry is removed from a list), the node refuses to start and names the peer; change or delete it first.

[federation]
enabled = true
# Local demo on a private network: plain http between known hosts.
insecure_peer_hosts = ["memora-node2"]
private_peer_hosts = ["memora-node2", "10.20.0.0/16"]

Each peer also needs its own inbound_key_sha256; two peers with the same key are refused.

Calls to a peer never follow redirects. A peer that answers with a 3xx fails that call (error_code http_307 and so on), and nothing is sent to the Location it names, so the query and the peer key cannot be passed on to another host.

Peers listed in the config file seed the node's peer registry, which is stored in the metadata store. Each one is imported on the first start that sees it, and never again. After that, edit peers over /v1/federation/peers or in the console; changing a peer in the config file does not change the registered peer, and a removed peer is not re-imported.

The api_key of each peer is stored sealed (AES-256-GCM) with a node secret kept outside the database. The secret comes from MEMORA_FEDERATION_SECRET (32 bytes, base64), or from federation.secret_key_file, which defaults to <data_dir>/federation.key and is created with mode 0600 on first start. A key file readable by others is refused. Keep the secret with the node: without it the stored peer keys cannot be opened, and those peers are not searched until their api_key is set again.

memora-core node peer-key prints a new random key and its SHA-256. Put the key in the calling node's api_key for this peer, and the hash in this node's inbound_key_sha256 for the caller.

StatusError codeCause
401federation_unauthorizedUnknown node ID, missing or wrong key, or missing or wrong client certificate. These causes are not distinguished.
403federation_peer_revokedThe peer presented a valid key, but revoked is set.
404federation_disabledFederation is not enabled on this node.
409federation_loopThis node is already in the request's federation path.

Peer routes need peer credentials even when the server runs without an API key.

Telemetry Keys

TOML table [telemetry].

KeyTypeDefault
telemetry.log_levelstringinfo
telemetry.log_formatstringjson

log_level accepts debug, info, warn, or error. log_format accepts json or text. An empty value is treated as the default; any other value fails validation. Both are file-only.

Environment Variables

Each variable overrides its file counterpart when set and non-empty.

KeyTypeDefault
MEMORA_CONFIGstring(unset — see the search path above)
MEMORA_ADDRstring:7777
MEMORA_NODE_IDstring(minted on first start)
MEMORA_NODE_NAMEstringthe hostname
MEMORA_MODEstringsingle-tenant
MEMORA_API_KEYstring(empty)
MEMORA_DATA_DIRstring./data
MEMORA_METADATA_DRIVERstringsqlite
MEMORA_METADATA_DSNstring(empty)
MEMORA_VECTOR_DRIVERstringsqlite-vec
MEMORA_VECTOR_DSNstring(empty)
MEMORA_GRAPH_DRIVERstringsqlite_graph
MEMORA_GRAPH_DSNstring(empty)
MEMORA_LEDGER_DRIVERstringsqlite
MEMORA_LEDGER_DSNstring(empty)
MEMORA_CONTENT_DRIVERstring(empty)
MEMORA_CONTENT_DSNstring(empty)
MEMORA_EMBEDDING_MODELstringnoop:default
MEMORA_EMBEDDING_ASYNCboolfalse — set to the literal true to enable
MEMORA_MCP_ENABLEboolfalse — set to the literal true to enable
MEMORA_UI_COOKIE_SECUREstring(empty) — auto, always or never

MEMORA_EMBEDDING_ASYNC and MEMORA_MCP_ENABLE are the only booleans in this layer, and each is matched against the exact string true; any other value leaves the file setting alone. There are no environment variables for the TLS keys, the API key file, allow_no_auth, or telemetry.

Flags for serve

KeyTypeDefault
--configstring(empty — uses the search path)
--addrstring(empty — falls through to file or env)
--data-dirstring(empty)
--metadata-driverstring(empty)
--vector-driverstring(empty)
--graph-driverstring(empty)
--ledger-driverstring(empty)
--content-driverstring(empty)
--content-dsnstring(empty)
--embedding-modelstring(empty)
--async-embedboolfalse
--api-keystring(empty)
--allow-no-authboolfalse
--modestring(empty)
--mcp-enableboolfalse

An empty flag value means "do not override", so omitting a flag leaves whatever the environment or file supplied. Note that --content-dsn is the only DSN available as a flag; the metadata, vector, graph, and ledger DSNs can only be set through the file or their environment variables.

Flags for mcp

The stdio MCP server takes a smaller set, because it has no listen address and no HTTP surface.

KeyTypeDefault
--configstring(empty — uses the search path)
--data-dirstring(empty)
--metadata-driverstring(empty)
--vector-driverstring(empty)
--ledger-driverstring(empty)
--embedding-modelstring(empty)
--api-keystring(empty)

There is no --graph-driver or --content-driver here; both seams take their configuration from the file or the environment when running under mcp.

A Worked Example

A configuration moving metadata, vectors and the ledger to Postgres, running without the context graph, enabling a file content store, and reading the API key from disk:

[server]
addr = ":7777"
mode = "single-tenant"
api_key_file = "~/.memora/api.key"

[server.tls]
enabled = true
cert_file = "/etc/memora/tls/cert.pem"
key_file = "/etc/memora/tls/key.pem"

[storage]
data_dir = "/var/lib/memora"
metadata_driver = "postgres"
metadata_dsn = "postgres://memora@db:5432/memora?sslmode=require"
vector_driver = "pgvector"
vector_dsn = "postgres://memora@db:5432/memora?sslmode=require"
graph_driver = "none"
ledger_driver = "postgres"
ledger_dsn = "postgres://memora@db:5432/memora?sslmode=require"
content_driver = "file"
content_dsn = "/var/lib/memora/content"

[embedding]
model = "openai:text-embedding-3-small"

[telemetry]
log_level = "info"
log_format = "json"

graph_driver is "none" because sqlite_graph, the only registered graph driver, keeps its edges in the SQLite metadata database and so needs metadata_driver = "sqlite". On Postgres metadata the context graph is therefore unavailable: graph operations report that the graph store is not configured and imprints are not auto-linked. Validate the file before deploying it:

memora-core check-config --config /etc/memora/config.toml