Configuration

This page lists the settings most operators need after the quick start.

For a first local setup, use Quick Start and change only the required values. The quick start uses local-only access and does not enable Traefik. Come back here when you need Redis, different AI providers, stricter limits, or public access.

Required Settings

The server requires a complete embedding configuration at startup: AI_API_URL, AI_API_KEY, AI_API_EMBEDDING_MODEL, and AI_API_EMBEDDING_DIMENSIONS. Dense-Mem uses an OpenAI-compatible embedding API. The compose examples supply OpenAI defaults, but production setups should set all four values explicitly so the model and stored vector dimensions are obvious.

Dense-Mem validates embedding configuration on startup. Do not change embedding model or dimensions casually after storing memory. Mixed vector dimensions can break search.

Local Ports

The main Dense-Mem server always listens on container port 8080. Change host exposure with the compose port variables, such as DENSE_MEM_PORT for the base example or DENSE_MEM_DEMO_PORT for the demo example.

The base example publishes these local URLs:

Keep the control portal on 127.0.0.1 for local use. It manages API keys.

Manager/member profile access is not controlled by a feature flag. It is active after the RBAC migration and is stored in the team_profiles.role column.

General Runtime Settings

These settings are stored in Postgres app_config and can be edited from the control portal Config tab.

SSO Settings

SSO is optional. Leave SSO_PUBLIC_BASE_URL empty when the deployment should not show SSO login in /ui.

These settings can be managed from the control portal SSO configuration screen. See Portals And API Keys for generic OIDC provider setup, group mappings, and the example ZITADEL configuration.

Database Settings

Postgres stores teams, profiles, API key metadata, migrations, and audit logs.

Dense-Mem's first Postgres migration uses gen_random_uuid() and creates the pgcrypto extension when it is missing. Fresh installs that use the bundled postgres:18-alpine compose service normally work without a manual step because the configured POSTGRES_USER owns the database. External, managed, or reused Postgres databases may use a restricted runtime role; in that case, install the extension once with a database owner or admin role before starting Dense-Mem:

psql "$ADMIN_POSTGRES_DSN" -c 'CREATE EXTENSION IF NOT EXISTS pgcrypto;'

For bundled compose, this preflight uses the Postgres service's own configured user and database:

docker compose exec postgres sh -lc \
  'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "CREATE EXTENSION IF NOT EXISTS pgcrypto;"'

If that command also fails with permission denied, the database or volume was not initialized with the configured runtime user as a database owner. Use an admin role to install the extension, or recreate the Postgres volume only when the existing data is disposable.

Neo4j stores memory graph data, claims, facts, relationships, and vector-backed search data.

AI Provider Settings

Embeddings are required for normal writes and recall.

AI_API_URL, AI_API_KEY, AI_API_EMBEDDING_MODEL, and AI_API_EMBEDDING_DIMENSIONS are all required by the server. The defaults above come from the compose examples and target OpenAI's text-embedding-3-small model. For another provider, change the URL, model, and dimension together.

Common OpenAI choices:

Choose the embedding model and dimensions before storing important memory. Changing either later requires re-embedding or rebuilding vector indexes; do not mix vectors from different embedding configurations.

Claim verification can use the same provider or a separate verifier provider.

Provider traffic may leave your environment. The embedding provider sees memory text and recall queries. The verifier provider sees claims and supporting evidence.

Redis

Redis is optional for a single local server.

Use Redis when you run multiple Dense-Mem server instances or need shared rate limits and shared SSE concurrency controls.

For the expert compose Redis service, set REDIS_ADDR=redis:6379, then start Redis:

docker compose --profile redis up -d

See Public HTTPS And Redis for the deployment guide.

Public HTTPS

The quick start is local only. Skip this section unless you intentionally want Dense-Mem reachable through a public HTTPS domain.

For public HTTPS, download the expert compose example after the local setup works:

curl -fsSLo docker-compose.yml \
  https://raw.githubusercontent.com/markhuangai/dense-mem/main/examples/docker-compose.expert.yml

Set:

DENSE_MEM_DOMAIN=dense-mem.example.com
ACME_EMAIL=[email protected]

Start:

docker compose --profile traefik up -d

Traefik exposes the main MCP and API service. It does not route to the control portal. Keep the portal private.

See Public HTTPS And Redis for the operator guide.

Public Edge Limits

Telemetry

Prometheus telemetry is optional and disabled by default.

To enable telemetry with the base or expert compose example:

curl -fsSLo prometheus.yml \
  https://raw.githubusercontent.com/markhuangai/dense-mem/main/examples/prometheus.yml
curl -fsSLo docker-compose.telemetry.yml \
  https://raw.githubusercontent.com/markhuangai/dense-mem/main/examples/docker-compose.telemetry.yml
​
export TELEMETRY_SCRAPE_TOKEN="$(openssl rand -hex 32)"
docker compose -f docker-compose.yml -f docker-compose.telemetry.yml up -d

The overlay starts Prometheus on 127.0.0.1:9090, keeps metrics on the private Compose network, scrapes the control server's /metrics endpoint with the scrape token, and sets TELEMETRY_PROMETHEUS_JOB=dense-mem by default.

See Telemetry for portal usage, demo telemetry, and troubleshooting.

Dreaming

Dreaming is optional and disabled by default. It creates reviewable hypotheses, not facts. Confirmed dream feedback enters the normal memory pipeline as evidence.

These settings are stored in Postgres app_config and can be edited from the control portal Config tab.

The schedule uses APP_TIMEZONE and runs at most once per profile per local day. See Dreaming.

Community Detection

Community detection is optional and disabled by default. It groups related graph nodes and persists profile-scoped community summaries for later inspection and opt-in recall expansion.

These settings are stored in Postgres app_config and can be edited from the control portal Config tab.

The schedule uses APP_TIMEZONE. Manual detection is also available through the detect_community MCP tool.

AI_COMMUNITY_MAX_NODES is still an environment variable because it controls a startup/runtime safety cap for Neo4j GDS projections.

See Community Memory.

Operation Logs

Operation logs are database-backed server logs shown in the control portal Logs tab. They are separate from Prometheus telemetry.

The server flushes logs in batches and prunes old rows hourly.

Runtime Limits

Logging

Safer First-Run Checklist

Before using Dense-Mem seriously:

• set real secrets instead of template values
• keep the control portal on 127.0.0.1
• create one read-write key for your main assistant
• create read-only keys for automation that should not write memory
• verify your AI provider and model dimensions before storing important memory
• back up Docker volumes if the memory matters