Configuration

Membrane is configured via a YAML file, command-line flags, and environment variables. Flags override file values; environment variables are read for secrets not set in the config.

YAML config file

Full example with all available fields:

backend: "sqlite"
db_path: "membrane.db"
# postgres_dsn: "postgres://membrane:membrane@localhost:5432/membrane?sslmode=disable"
listen_addr: ":9090"
decay_interval: "1h"
consolidation_interval: "6h"
default_sensitivity: "low"
selection_confidence_threshold: 0.7
graph_default_root_limit: 10
graph_default_node_limit: 25
graph_default_edge_limit: 100
graph_default_max_hops: 1

# Optional embedding-backed retrieval (Postgres only)
# embedding_endpoint: "https://api.openai.com/v1/embeddings"
# embedding_model: "text-embedding-3-small"
# embedding_dimensions: 1536
# embedding_api_key: ""   # or set MEMBRANE_EMBEDDING_API_KEY

# Optional LLM-backed semantic extraction (Postgres only)
# llm_endpoint: "https://api.openai.com/v1/chat/completions"
# llm_model: "gpt-5-mini"
# llm_api_key: ""         # or set MEMBRANE_LLM_API_KEY

# Optional ingest-side interpretation for CaptureMemory
# ingest_llm_enabled: true
# ingest_llm_endpoint: "https://api.openai.com/v1/chat/completions"
# ingest_llm_model: "gpt-5-mini"
# ingest_llm_api_key: ""  # or set MEMBRANE_INGEST_LLM_API_KEY

# Security (prefer environment variables for keys)
# encryption_key: ""       # or set MEMBRANE_ENCRYPTION_KEY
# api_key: ""              # or set MEMBRANE_API_KEY
# tls_cert_file: ""
# tls_key_file: ""
rate_limit_per_second: 100

Load the file from Go:

cfg, err := membrane.LoadConfig("/etc/membrane/config.yaml")
if err != nil {
    log.Fatal(err)
}

LoadConfig starts from DefaultConfig() and unmarshals the YAML on top, so fields not present in the file retain their defaults.

---

DefaultConfig() defaults

Calling membrane.DefaultConfig() produces:

Field	Default value
Backend	"sqlite"
DBPath	"membrane.db"
ListenAddr	":9090"
DecayInterval	1h
ConsolidationInterval	6h
DefaultSensitivity	"low"
SelectionConfidenceThreshold	0.7
EncryptionKey	"" (unencrypted)
EmbeddingDimensions	1536
RateLimitPerSecond	100
GraphDefaultRootLimit	10
GraphDefaultNodeLimit	25
GraphDefaultEdgeLimit	100
GraphDefaultMaxHops	1
IngestLLMEnabled	false

---

Config struct fields

Storage

backendstring

Storage backend. Options: "sqlite" (default) or "postgres".

db_pathstring

SQLite database file path. Default: "membrane.db". Ignored when backend is "postgres".

postgres_dsnstring

PostgreSQL connection string. Required when backend is "postgres". Falls back to the MEMBRANE_POSTGRES_DSN environment variable if not set in config.

Example: postgres://membrane:membrane@localhost:5432/membrane?sslmode=disable

Network

listen_addrstring

gRPC server listen address. Default: ":9090".

Scheduling

decay_intervalduration

How often the decay scheduler runs. Default: "1h". Accepts Go duration strings ("30m", "2h", etc.).

consolidation_intervalduration

How often the consolidation scheduler runs. Default: "6h". Consolidation extracts semantic facts and competence records from episodic traces.

Ingestion

default_sensitivitystring

Default sensitivity level assigned to records at ingestion when not explicitly overridden. Default: "low".

Valid values: public, low, medium, high, hyper.

Retrieval

selection_confidence_thresholdfloat64

Minimum confidence for competence and plan_graph candidates to pass the selector. Default: 0.7.

graph_default_root_limitint

Default root count applied by the Go facade when RetrieveGraphRequest.RootLimit is zero. Default: 10.

graph_default_node_limitint

Default total graph node limit applied by the Go facade when RetrieveGraphRequest.NodeLimit is zero. Default: 25.

graph_default_edge_limitint

Default graph edge limit applied by the Go facade when RetrieveGraphRequest.EdgeLimit is zero. Default: 100.

graph_default_max_hopsint

Default graph expansion depth applied by the Go facade when RetrieveGraphRequest.MaxHops is zero. Default: 1.

Embedding

embedding_endpointstring

HTTP endpoint for generating record and query embeddings. Requires backend: postgres and embedding_model. Example: https://api.openai.com/v1/embeddings.

embedding_modelstring

Embedding model name sent to the embedding endpoint. Example: text-embedding-3-small.

embedding_dimensionsint

Output dimension of the embedding model. Default: 1536. Must match the model's actual output dimensions.

embedding_api_keystring

API key for the embedding endpoint. Prefer setting MEMBRANE_EMBEDDING_API_KEY instead.

LLM

llm_endpointstring

HTTP endpoint for the LLM used in semantic extraction during consolidation. Requires backend: postgres. Example: https://api.openai.com/v1/chat/completions.

llm_modelstring

Chat model name sent to the LLM endpoint. Example: gpt-5-mini.

llm_api_keystring

API key for the LLM endpoint. Prefer setting MEMBRANE_LLM_API_KEY instead.

Ingest LLM

ingest_llm_enabledbool

Enables ingest-side interpretation during CaptureMemory. Default: false.

ingest_llm_endpointstring

HTTP endpoint for capture-time interpretation and candidate resolution.

ingest_llm_modelstring

Chat model name sent to the ingest-side interpretation endpoint.

ingest_llm_api_keystring

API key for the ingest-side interpretation endpoint. Prefer setting MEMBRANE_INGEST_LLM_API_KEY instead.

Security

encryption_keystring

SQLCipher PRAGMA key value for encrypting the SQLite database at rest. Falls back to MEMBRANE_ENCRYPTION_KEY. When empty, the database is unencrypted.

tls_cert_filestring

Path to TLS certificate PEM file. TLS is disabled when empty.

tls_key_filestring

Path to TLS private key PEM file. Required when tls_cert_file is set.

api_keystring

Shared secret for gRPC client authentication via bearer token. Falls back to MEMBRANE_API_KEY. Authentication is disabled when empty.

rate_limit_per_secondint

Maximum gRPC requests per second per client. 0 disables rate limiting. Default: 100.

---

Environment variables

Variable	Config field	Description
MEMBRANE_ENCRYPTION_KEY	encryption_key	SQLCipher encryption key for the SQLite database
MEMBRANE_POSTGRES_DSN	postgres_dsn	PostgreSQL DSN, read when backend: postgres
MEMBRANE_EMBEDDING_API_KEY	embedding_api_key	API key for the embedding endpoint
MEMBRANE_LLM_API_KEY	llm_api_key	API key for the LLM semantic extraction endpoint
MEMBRANE_INGEST_LLM_API_KEY	ingest_llm_api_key	API key for the ingest-side interpretation endpoint
MEMBRANE_API_KEY	api_key	Bearer token for gRPC client authentication

---

Command-line flags

Flags override values set in the config file.

Flag	Overrides	Description
--config <path>	—	Load YAML config file from <path>
--db <path>	db_path	SQLite database path
--postgres-dsn <dsn>	postgres_dsn + backend	PostgreSQL DSN; also sets backend = "postgres"
--addr <addr>	listen_addr	gRPC listen address
--version	—	Print version and exit