Configuration

Environment Variables

The MemoryLayer server can be configured via environment variables:

Variable	Description	Default
MEMORYLAYER_SERVER_HOST	Server bind address	127.0.0.1
MEMORYLAYER_SERVER_PORT	Server port	61001
MEMORYLAYER_DATA_DIR	Server data directory	~/.config/memorylayer-server
MEMORYLAYER_SQLITE_STORAGE_PATH	SQLite database path (relative to data dir)	memorylayer.db
MEMORYLAYER_STORAGE_BACKEND	Storage backend (sqlite or turso)	sqlite
MEMORYLAYER_EMBEDDING_PROVIDER	Embedding provider (embed_server, openai, google, mock)	embed_server
MEMORYLAYER_EMBEDDING_OPENAI_API_KEY	OpenAI API key (for OpenAI embeddings)	—
MEMORYLAYER_EMBEDDING_GOOGLE_API_KEY	Google API key (for Google GenAI embeddings)	—
MEMORYLAYER_EMBED_SERVER_URL	Base URL of the memorylayer-embed-server peer	http://localhost:61051
MEMORYLAYER_EMBED_TRANSPORT	Transport for the embed-server peer (http or aether)	http
MEMORYLAYER_EMBED_AETHER_TARGET	Aether service target when EMBED_TRANSPORT=aether	sv::memorylayer-embed::default
MEMORYLAYER_RERANKER_PROVIDER	Reranker provider (rrf, llm, hyde, embed_server, none)	rrf
MEMORYLAYER_SESSION_IMPLICIT_CREATE	Auto-create a session on first use	true
MEMORYLAYER_SESSION_TOUCH_TTL	Session sliding TTL in seconds	3600
MEMORYLAYER_SESSION_TOKEN_BUDGET_TOTAL	Total token budget per session before extraction triggers	12000
MEMORYLAYER_SESSION_TOKEN_TRIGGER_INIT	Token threshold that arms the first extraction trigger	10000
MEMORYLAYER_SESSION_TOKEN_TRIGGER_GROWTH	Token growth between subsequent extraction triggers	5000

Use the --verbose CLI flag to enable debug logging.

Embedding Providers

MemoryLayer’s memorylayer-server core supports four embedding providers:

Provider	Purpose
embed_server (default)	Delegates to a memorylayer-embed-server peer over HTTP (or mTLS via Aether). Use this for self-hosted text and multi-vector workloads.
openai	OpenAI Embeddings API (works with any OpenAI-compatible endpoint).
google	Google GenAI Embeddings API.
mock	Deterministic hash-based vectors; for tests and demos that need no network access or API key.

Removed in v0.1.x: the in-process local (sentence-transformers), colpali (colpali-engine), and qwen3-vl (qwen-vl-utils) providers were removed. Setting any of those names for MEMORYLAYER_EMBEDDING_PROVIDER raises a startup error with migration guidance. All self-hosted/multi-vector workloads now go through the embed_server provider, which proxies to the standalone memorylayer-embed-server package.

embed_server (default, self-hosted)

Run memorylayer-embed-server as a peer process or container, then point the core server at it:

# On a GPU-equipped peer
pip install "memorylayer-embed-server[gpu]"
memorylayer-embed serve --port 61051

# On the core server
export MEMORYLAYER_EMBEDDING_PROVIDER=embed_server
export MEMORYLAYER_EMBED_SERVER_URL=http://embed-host:61051
memorylayer serve

For cross-datacenter / mTLS deployments, set MEMORYLAYER_EMBED_TRANSPORT=aether and MEMORYLAYER_EMBED_AETHER_TARGET=sv::memorylayer-embed::default.

OpenAI

pip install memorylayer-server[openai]
export MEMORYLAYER_EMBEDDING_OPENAI_API_KEY="sk-..."
export MEMORYLAYER_EMBEDDING_PROVIDER="openai"
memorylayer serve

Google GenAI

pip install memorylayer-server[google]
export MEMORYLAYER_EMBEDDING_GOOGLE_API_KEY="..."
export MEMORYLAYER_EMBEDDING_PROVIDER="google"
memorylayer serve

Mock (testing only)

export MEMORYLAYER_EMBEDDING_PROVIDER="mock"
memorylayer serve

No network access required; produces deterministic hash-based vectors.

Context Environment

The Context Environment provides server-side Python sandboxes for memory analysis and computation.

Variable	Description	Default
MEMORYLAYER_CONTEXT_EXECUTOR	Executor backend (smolagents or restricted)	smolagents
MEMORYLAYER_CONTEXT_MAX_EXEC_SECONDS	Timeout per code execution	30
MEMORYLAYER_CONTEXT_MAX_OUTPUT_CHARS	Max captured stdout characters	50000
MEMORYLAYER_CONTEXT_QUERY_MAX_TOKENS	Max tokens for server-side LLM queries	4096
MEMORYLAYER_CONTEXT_MAX_MEMORY_BYTES	Memory limit per sandbox	268435456 (256 MB)
MEMORYLAYER_CONTEXT_RLM_MAX_ITERATIONS	Max iterations for RLM loops	10
MEMORYLAYER_CONTEXT_RLM_MAX_EXEC_SECONDS	Total timeout for RLM loops	120
MEMORYLAYER_CONTEXT_MAX_OPERATIONS	Max sandbox operations per execution	1000000

Executor Backends

The Context Environment supports two executor backends:

# Use smolagents executor (default, recommended)
export MEMORYLAYER_CONTEXT_EXECUTOR="smolagents"

# Use restricted executor (no imports, AST-based whitelist)
export MEMORYLAYER_CONTEXT_EXECUTOR="restricted"

The smolagents backend provides a more capable execution environment with support for common data science libraries. The restricted backend uses an AST-based whitelist for maximum safety but limited functionality.

Docker

The official Docker image (scitrera/memorylayer-server) installs the core server with all cloud and document-parser extras. It does not pin an embedding provider in the image itself — the runtime falls back to the code default embed_server, so you must either run a memorylayer-embed-server peer container and set MEMORYLAYER_EMBED_SERVER_URL, or override the provider (mock for tests, openai / google for cloud).

Container Defaults

Variable	Docker Default	Code Default
MEMORYLAYER_SERVER_HOST	0.0.0.0	127.0.0.1
MEMORYLAYER_EMBEDDING_PROVIDER	(unset; falls back to code default)	embed_server
MEMORYLAYER_DATA_DIR	/data	~/.config/memorylayer-server

Passing Environment Variables

Use -e flags to configure the container:

docker run -d \
  --name memorylayer \
  -p 61001:61001 \
  -v memorylayer-data:/data \
  -e MEMORYLAYER_EMBEDDING_PROVIDER=openai \
  -e MEMORYLAYER_EMBEDDING_OPENAI_API_KEY=sk-... \
  scitrera/memorylayer-server

LLM Provider Configuration

Some features (reflection, smart extraction, context environment queries) require an LLM provider. LLM providers are configured via profiles:

# OpenAI LLM
-e MEMORYLAYER_LLM_PROFILE_DEFAULT_PROVIDER=openai \
-e MEMORYLAYER_LLM_PROFILE_DEFAULT_API_KEY=sk-...

# Anthropic Claude
-e MEMORYLAYER_LLM_PROFILE_DEFAULT_PROVIDER=anthropic \
-e MEMORYLAYER_LLM_PROFILE_DEFAULT_API_KEY=sk-ant-...

# Google Gemini
-e MEMORYLAYER_LLM_PROFILE_DEFAULT_PROVIDER=google \
-e MEMORYLAYER_LLM_PROFILE_DEFAULT_API_KEY=...

# Self-hosted via a memorylayer-embed-server peer
-e MEMORYLAYER_LLM_PROFILE_DEFAULT_PROVIDER=embed_server \
-e MEMORYLAYER_LLM_PROFILE_DEFAULT_MODEL=qwen          # must match a profile/alias on the embed server
# Optional per-profile transport overrides (otherwise piggybacks on the embed-server client already wired for embeddings):
-e MEMORYLAYER_LLM_PROFILE_DEFAULT_EMBED_SERVER_URL=http://embed-peer:61051 \
-e MEMORYLAYER_LLM_PROFILE_DEFAULT_EMBED_SERVER_TRANSPORT=http

Each profile is independent: two profiles can point at two different embed-server peers, or mix cloud + self-hosted. Activities route to profiles via MEMORYLAYER_LLM_ASSIGN_<ACTIVITY>=<profile_name> (e.g. MEMORYLAYER_LLM_ASSIGN_REFLECT=private). Tool calling, structured output, and reasoning_effort are forwarded canonically across all four real providers. See the LLM Profiles reference for the full schema and recipes.

Without an LLM provider, the server still handles core memory operations (remember, recall, forget, associate) but features that require synthesis or generation will be unavailable.

Data Persistence

Mount a volume to /data to persist the SQLite database across container restarts:

-v memorylayer-data:/data          # Named volume
-v /path/on/host:/data             # Bind mount

Health Check

The container includes a built-in health check at GET /health (every 30s, 10s startup grace period). Use GET /health/ready for readiness checks that verify storage connectivity.

Storage

SQLite (Default)

The default storage backend is SQLite with sqlite-vec for vector operations.

The SQLite database is a single file that contains all memories, embeddings, associations, and session data.

Database Location

The default storage path is memorylayer.db (relative to the data directory). The data directory defaults to ~/.config/memorylayer-server/ and can be overridden with MEMORYLAYER_DATA_DIR, so the database is typically created at ~/.config/memorylayer-server/memorylayer.db.

# Override the data directory
export MEMORYLAYER_DATA_DIR="/var/lib/memorylayer"

# Or specify an explicit database path
export MEMORYLAYER_SQLITE_STORAGE_PATH="/var/lib/memorylayer/data.db"