Configuration

Configure Cerememory via TOML file, environment variables, and CLI flags.

Configuration Precedence

Cerememory loads configuration from three sources, in order of precedence (highest wins):

CLI flags -- Highest precedence for options they cover
Environment variables -- CEREMEMORY_ prefix with __ separator
TOML configuration file -- Specified via --config flag
Hard-coded defaults -- Sensible defaults for all settings

TOML Configuration File

Create a cerememory.toml file:

toml

# Data directory for persistent storage (redb files, text index, vector index)
data_dir = "./data"
 
[http]
port = 8420
bind_address = "127.0.0.1"  # use "0.0.0.0" only when you intentionally expose the server
cors_origins = ["http://localhost:3000", "https://app.example.com"]
trusted_proxy_cidrs = ["10.0.0.0/8"]  # optional; only trusted proxies may supply X-Forwarded-For / X-Real-IP
metrics_enabled = false               # opt-in; /metrics is disabled unless enabled
 
[grpc]
port = 8421                           # omit to disable gRPC
tls_cert_path = "/etc/certs/cert.pem" # required when auth is enabled or bind_address is not loopback
tls_key_path = "/etc/certs/key.pem"   # required together with tls_cert_path
 
[auth]
enabled = true
api_keys = ["sk-cerememory-prod-abc123", "sk-cerememory-prod-def456"]
 
[security]
# Optional at-rest encryption for newly written redb store records.
# Prefer CEREMEMORY_SECURITY__STORE_ENCRYPTION_PASSPHRASE over TOML so the
# passphrase is not committed to version control.
# store_encryption_passphrase = "change-me"
# When store encryption is enabled, persistent full-text indexes default to
# in-memory only. Set true if searchable derived text on disk is acceptable.
# persist_search_indexes = false
# Tamper-evident audit log is enabled by default at <data_dir>/audit.jsonl.
# Verify the hash chain with: cerememory audit-verify
# audit_log_enabled = true
# audit_log_path = "/var/lib/cerememory/audit.jsonl"
 
[llm]
# Standard mode runs without an LLM. External providers are an experimental
# opt-in and require the matching cargo feature (`llm-openai`, `llm-claude`,
# or `llm-gemini`) at CLI build time. Without that feature, a non-"none"
# provider is rejected at startup.
provider = "none"     # "openai", "claude" (or "anthropic"), "gemini" (or "google"), or "none"
# api_key = "sk-..."
# model = "claude-sonnet-4-20250514"     # optional model override
# base_url = null                         # optional base URL override
 
[decay]
background_interval_secs = 3600  # background decay tick interval
 
[dream]
background_interval_secs = 86400  # background dream tick interval (default: 24 hours)
 
[rate_limit]
requests_per_second = 100
burst = 50
 
[log]
level = "info"    # trace, debug, info, warn, error
format = "pretty" # "pretty" or "json"

Pass the config file to the CLI:

bash

cerememory serve --config ./cerememory.toml

Environment Variables

All configuration options can be overridden via environment variables with the CEREMEMORY_ prefix. Nested keys use __ (double underscore) as the separator.

Environment Variable	Config Key	Default	Description
`CEREMEMORY_DATA_DIR`	`data_dir`	`./data`	Data directory path
`CEREMEMORY_HTTP__PORT`	`http.port`	`8420`	HTTP server port
`CEREMEMORY_HTTP__BIND_ADDRESS`	`http.bind_address`	`127.0.0.1`	Bind address for HTTP server
`CEREMEMORY_HTTP__CORS_ORIGINS`	`http.cors_origins`	`[]`	Allowed CORS origins. Empty means no cross-origin access
`CEREMEMORY_HTTP__TRUSTED_PROXY_CIDRS`	`http.trusted_proxy_cidrs`	`[]`	Trusted proxy CIDRs allowed to supply forwarded client IP headers
`CEREMEMORY_HTTP__METRICS_ENABLED`	`http.metrics_enabled`	`false`	Enable the `/metrics` endpoint
`CEREMEMORY_GRPC__PORT`	`grpc.port`	None	gRPC port (disabled if unset)
`CEREMEMORY_GRPC__TLS_CERT_PATH`	`grpc.tls_cert_path`	None	TLS certificate path
`CEREMEMORY_GRPC__TLS_KEY_PATH`	`grpc.tls_key_path`	None	TLS key path
`CEREMEMORY_AUTH__ENABLED`	`auth.enabled`	`false`	Enable Bearer token auth
`CEREMEMORY_AUTH_API_KEYS`	`auth.api_keys`	`[]`	Comma-separated Cerememory server API keys
`CEREMEMORY_SECURITY__STORE_ENCRYPTION_PASSPHRASE`	`security.store_encryption_passphrase`	None	Passphrase used to encrypt newly written redb records
`CEREMEMORY_SECURITY__PERSIST_SEARCH_INDEXES`	`security.persist_search_indexes`	`false` when store encryption is set, otherwise `true`	Persist full-text indexes to disk
`CEREMEMORY_SECURITY__AUDIT_LOG_ENABLED`	`security.audit_log_enabled`	`true`	Append-only tamper-evident audit log
`CEREMEMORY_SECURITY__AUDIT_LOG_PATH`	`security.audit_log_path`	`<data_dir>/audit.jsonl`	Audit log path
`CEREMEMORY_LLM__PROVIDER`	`llm.provider`	`none`	LLM provider name
`CEREMEMORY_LLM__API_KEY`	`llm.api_key`	None	External LLM provider API key
`CEREMEMORY_LLM__MODEL`	`llm.model`	None	Model name override
`CEREMEMORY_LLM__BASE_URL`	`llm.base_url`	None	API base URL override
`CEREMEMORY_DECAY__BACKGROUND_INTERVAL_SECS`	`decay.background_interval_secs`	`3600`	Decay tick interval (seconds)
`CEREMEMORY_DREAM__BACKGROUND_INTERVAL_SECS`	`dream.background_interval_secs`	`86400`	Dream tick interval (seconds)
`CEREMEMORY_RATE_LIMIT__REQUESTS_PER_SECOND`	`rate_limit.requests_per_second`	`100`	Rate limit RPS
`CEREMEMORY_RATE_LIMIT__BURST`	`rate_limit.burst`	`50`	Rate limit burst
`CEREMEMORY_LOG__LEVEL`	`log.level`	`info`	Log level
`CEREMEMORY_LOG__FORMAT`	`log.format`	`pretty`	Log format

Which API Key Do I Need?

Cerememory uses two different kinds of keys:

Setting	Purpose	Needed For
`auth.api_keys` / `CEREMEMORY_AUTH_API_KEYS`	Protect access to the Cerememory HTTP/gRPC server itself	Any remote client calling `/v1/*` when auth is enabled
`llm.api_key` / `CEREMEMORY_LLM__API_KEY`	Let Cerememory call an external LLM provider	Automatic embedding, summarization, relation extraction, image/audio understanding

If you are only using Cerememory as a local memory database, you do not need an LLM key.

Features That Work Without An LLM Key

Store and recall text or structured memories
Search by text
Search by precomputed embeddings you provide yourself
Store and recall raw journal entries
Dream tick processing (without LLM, outputs raw concatenation)
Inspect, stats, timeline, associate
Forget, decay tick, mode switching
Export and import archives
MCP / CLI / HTTP / gRPC basic CRUD flows

Features That Require An LLM Key

Automatic text embedding generation
Image embedding / image recall cues
Audio transcription / audio recall cues
Consolidation summarization
Relation extraction during consolidation
Dream tick intelligent summarization (topic inference, secrecy-aware redaction)
Other multimodal understanding features that call a provider

CLI Flag Overrides

CLI flags take the highest precedence for the specific options they cover:

bash

cerememory serve --port 9000 --grpc-port 8421 --data-dir /var/cerememory --config ./cerememory.toml

Flag	Overrides
`--port`	`http.port`
`--grpc-port`	`grpc.port`
`--data-dir`	`data_dir`
`--config`	Path to TOML config file

At-Rest Encryption and Audit Log

The [security] section controls how Cerememory protects data on disk:

Store encryption. Setting security.store_encryption_passphrase (or the matching CEREMEMORY_SECURITY__STORE_ENCRYPTION_PASSPHRASE env var) encrypts newly written redb records. Existing plaintext records remain readable so the engine can run during migration. Run cerememory migrate-store-encryption --confirm to rewrite legacy plaintext payloads with encryption.
Persistent indexes. When store encryption is on, full-text indexes default to in-memory only. Set security.persist_search_indexes = true only if it is acceptable for derived text to appear on disk.
Audit log. A tamper-evident JSONL hash chain is enabled by default at <data_dir>/audit.jsonl. Disable with security.audit_log_enabled = false, or relocate via security.audit_log_path. Verify integrity with cerememory audit-verify (it picks up the configured path automatically, or accepts an explicit --path).

Validation

The configuration is validated at startup. The following rules are enforced:

data_dir must not be empty
HTTP port must be non-zero
HTTP bind address must not be empty and must parse as a valid IP (127.0.0.1, 0.0.0.0, ...) or localhost
gRPC port (if set) must be non-zero and different from HTTP port
If auth is enabled, at least one non-blank Cerememory API key must be configured
API key lists must not contain blank or whitespace-only entries
TLS cert and key must be provided together (both or neither)
http.trusted_proxy_cidrs entries must be valid CIDR ranges
Rate limit requests_per_second and burst must both be greater than zero
decay.background_interval_secs and dream.background_interval_secs must both be greater than zero
When [llm].provider is not "none": api_key is required and must not be blank; model and base_url, if present, must not be blank
security.store_encryption_passphrase, when present, must not be blank
security.audit_log_path, when present, must not be blank

These additional checks are enforced at startup, before any HTTP/gRPC listener binds:

gRPC requires TLS when auth is enabled or http.bind_address is non-loopback
HTTP API binds on non-loopback addresses are rejected unless auth is enabled (no public unauthenticated API)
MCP proxy upstreams over plaintext non-loopback HTTP are rejected when an --server-api-key (or CEREMEMORY_SERVER_API_KEY) is configured
A CLI built without the matching llm-* feature rejects a non-none [llm].provider at startup

Data Directory Structure

When Cerememory starts, it creates the following structure inside data_dir:

data

episodic.redb

semantic.redb

procedural.redb

emotional.redb

raw_journal.redb

vectors.redb

text_index

raw_journal_text_index

Next Steps

Operations

Run cerememory serve as a long-lived service with launchd, systemd, probes, and backups

CLI Reference

Every CLI command and flag