Configuration
Configuration reference for self-hosted Agent Memory — connection strings, authentication, model providers, limits, background jobs and sign-up.
Agent Memory is configured with standard .NET configuration. In containers, use environment variables, replacing : with a double underscore: ConnectionStrings:SharedDb becomes ConnectionStrings__SharedDb. Never put secrets in appsettings.json or the image.
Behaviour that tenants can tune themselves (retrieval, consolidation, screening, retention) is documented in Workspace settings; the configuration keys listed there set the deployment-wide defaults.
Environment
| Variable | Notes |
|---|---|
ASPNETCORE_ENVIRONMENT | Production for real deployments. Production refuses development fallbacks: missing connection strings, a plaintext key ring or no authentication mode stop start-up with an error naming the missing key. |
ASPNETCORE_URLS | Defaults to http://0.0.0.0:8080 in the image. |
Connection strings
| Key | Used by | Notes |
|---|---|---|
ConnectionStrings:ControlPlaneDb | API, worker | Control-plane database (agentmemory), connecting as the control_plane role. |
ConnectionStrings:SharedDb | API, worker | Shared tenant database (tenant_shared), connecting as the app_runtime role. |
ConnectionStrings:PlatformDb | API, worker | Platform memory database (agentmemory_platform). |
ConnectionStrings:Redis | API, worker | e.g. redis:6379,abortConnect=False. |
ConnectionStrings:ControlPlaneDbMigrations | migrations | Owner connection to agentmemory. |
ConnectionStrings:SharedDbMigrations | migrations | Owner connection to tenant_shared. |
ConnectionStrings:PlatformDbMigrations | migrations | Owner connection to agentmemory_platform (falls back to PlatformDb). |
APP_RUNTIME_PASSWORD | migrations | Password the migration sets for the app_runtime role. Required in Production. |
CONTROL_PLANE_PASSWORD | migrations | Password the migration sets for the control_plane role. |
Db:MaxPoolSize | API, worker | Connection pool size per database. Default 30. |
Db:CommandTimeoutSeconds | API, worker | Database command timeout. |
Database:ApplyMigrationsOnStartup | API | Default true: the API applies pending migrations before serving (requires the *Migrations connection strings). Set false when a separate --migrate job owns schema changes. |
Public URL and proxies
| Key | Default | Notes |
|---|---|---|
App:PublicBaseUrl | — | The public URL of the deployment, used in links and emails. |
ForwardedHeaders:TrustedNetworks:<n> | — | CIDR ranges of reverse proxies whose X-Forwarded-* headers are trusted. |
ForwardedHeaders:AssumeHttps | true in Production | Treat requests as HTTPS when the proxy sends no X-Forwarded-Proto. |
Authentication
In Production one of the three modes below is required. API keys work in every mode. See Deployment.
Built-in OAuth 2.1 server
| Key | Default | Notes |
|---|---|---|
OAuth:Enabled | false | Turn on the authorization server (MCP sign-in, console login). |
OAuth:Issuer | — | The exact public HTTPS URL clients use. |
OAuth:SigningCertificate, OAuth:EncryptionCertificate | — | Base64 PKCS#12. Set both, or neither (ephemeral keys — tokens are invalidated on every restart). |
OAuth:AccessTokenMinutes | 60 | |
OAuth:RefreshTokenDays | 14 | Refresh tokens roll on every use. |
OAuth:IdentityTokenMinutes | 20 | |
OAuth:AuthorizationCodeMinutes | 5 |
The OAuth server federates the actual sign-in to Google or an OpenID Connect provider — at least one must be configured:
| Key | Notes |
|---|---|
Auth:Google:ClientId, Auth:Google:ClientSecret | Google sign-in. Register <issuer>/signin-google as a redirect URI. |
Auth:Oidc:Authority, Auth:Oidc:ClientId, Auth:Oidc:ClientSecret | An OpenID Connect provider such as Entra ID ("Continue with Microsoft"). |
Auth:Oidc:GoogleDomainHint | With an OIDC provider that federates Google, route "Continue with Google" through it (use Google). |
Auth:Email:MaxCodesPerAddressPerHour, Auth:Email:MaxCodesPerIpPerHour | Limits for one-time email sign-in codes (defaults 5 and 30; 0 = no limit). Email codes need SMTP. |
External identity provider
| Key | Notes |
|---|---|
Auth:Authority | OIDC issuer whose tokens the API validates. |
Auth:Audience | Audience of data-plane and MCP tokens. Must equal the public URL MCP clients call. |
Auth:AdminAudience | Audience of control-plane (provisioning) tokens. |
API keys only — Deployment:AirGapped=true. See Air-gapped.
Development only — Auth:Dev:Enabled and Auth:Dev:SigningKey enable a symmetric development token path outside Production. They are ignored in Production.
Key ring
| Key | Notes |
|---|---|
DataProtection:KeyEncryptionCertificate | Base64 PKCS#12 that encrypts the ASP.NET Data Protection key ring (which protects webhook secrets, tenant provider keys and console cookies). Required in Production; falls back to OAuth:EncryptionCertificate. |
DataProtection:PreviousKeyEncryptionCertificates:<n> | Previous certificates, kept so keys encrypted before a rotation stay readable. |
Sign-up and console
| Key | Default | Notes |
|---|---|---|
SignUp:Mode | open | Who may create an account: open, domain-allowlist, invite-only or approval. Invites work in every mode. |
SignUp:AllowedDomains | — | Comma-separated email domains for domain-allowlist. Only verified emails count. |
SelfService:Enabled | false | Just-in-time personal workspaces for external-IdP users on /v1/mcp. |
SelfService:MaxNewTenantsPerIpPerDay | 20 | Cap on self-service tenant creation per IP. |
Admin:RootEmail | — | The platform operator's email; that signed-in user gets the operator console. |
Email:Smtp:Host, Port, Username, Password, From, UseStartTls | — | Outbound email for sign-in codes, invites and notifications. |
Model providers
| Key | Default | Notes |
|---|---|---|
Deployment:NoPaidAi | true | While on, the platform makes no paid AI calls: paid embedding providers are refused at start-up and LLM features use their rule-based fallbacks — unless the LLM is a local OpenAI-compatible server. Set false to use Anthropic, OpenAI or Bedrock. |
Llm:Provider | anthropic | anthropic or openai. |
Llm:Anthropic:ApiKey, Llm:Anthropic:Model | —, provider default | |
Llm:OpenAI:ApiKey, Llm:OpenAI:Model | —, gpt-4o-mini | |
Llm:OpenAI:BaseUrl | OpenAI | Any OpenAI-compatible endpoint: Ollama, vLLM, LM Studio, LocalAI. |
Llm:TimeoutSeconds, Llm:Resilience:* | Per-call timeout, retries and circuit breaker for provider calls. | |
Llm:MaxConcurrentPerTenant | 2 | Concurrent LLM calls per tenant; excess waits briefly, then answers 429 RATE_LIMITED. |
Llm:AllowedProviders | Comma-separated providers tenants may choose for their own keys. | |
Embedding:Provider | hashing when unset and spending is blocked | openai (text-embedding-3-small, 1536 dimensions), bedrock, onnx (local, 384 dimensions by default) or hashing (local fallback). |
Embedding:OpenAI:BaseUrl | OpenAI | OpenAI-compatible embeddings endpoint. Uses OpenAI:ApiKey (or Llm:OpenAI:ApiKey). |
Embedding:Onnx:ModelPath, Embedding:Onnx:VocabPath, Embedding:Onnx:Dimensions | Local sentence-transformer ONNX model. | |
Embedding:Bedrock:ModelId, Embedding:Bedrock:Region, Embedding:Bedrock:Dimensions | amazon.titan-embed-text-v2:0, us-east-1, 1024 | |
Embedding:TargetDimensions | 1536 | Stored vector width; provider output is adapted to it. |
What uses the LLM: fact extraction at consolidation, session compression, episode summaries, file summaries and — in assisted retrieval mode — query decomposition and reranking. Everything has a non-LLM path, so the platform works without any provider.
Changing the embedding model
Embeddings from different models are not comparable. Switching Embedding:Provider or model on a deployment with data requires re-embedding; a model wider than the stored columns is refused at start-up. See Operations.
Rate limiting
| Key | Default | Notes |
|---|---|---|
RateLimit:PermitPerMinute | 0 (off) | Requests per minute per tenant. Set a value in production. |
RateLimit:AnonymousPermitPerMinute | 30 | Per-IP limit for unauthenticated traffic (applies when the limiter is on). |
RateLimit:WorkspacePermitPerMinute | 0 (off) | Additional per-workspace fairness window for API-key traffic. |
Api:MaxConcurrentRequests | 0 (off) | Concurrency ceiling for /v1 and /api; excess answers 503 OVERLOADED. |
Api:MaxConcurrentRequestsQueue | 20 | Requests allowed to wait for a slot. |
Api:MaxRequestBodyBytes | 1048576 | Request body cap (413 above it). |
Api:LegacySunset | Wed, 30 Jun 2027 00:00:00 GMT | Sunset header on the deprecated /api aliases. |
Background work
| Key | Default | Notes |
|---|---|---|
MemoryMaintenance:Enabled | true | Idle-run consolidation in the console host's service mode. |
MemoryMaintenance:Host | — | Set to api to run idle-run consolidation inside the API instead of a worker. |
MemoryMaintenance:IntervalMinutes | 5 | How often idle runs are looked for. |
MemoryMaintenance:IdleTimeoutMinutes | 30 | Inactivity before a run is consolidated automatically. |
MemoryMaintenance:MaxRunsPerTenantPerCycle | 10 | Fairness cap per pass. |
Runtime:Mode | interactive | Console host: service runs the background worker. |
Hangfire:Enabled | true | Scheduler for the API's jobs (webhooks, retention, erasure, ingestion effects). |
Retention:Enabled | true | Daily retention sweep. |
Webhooks:DispatchIntervalSeconds, Webhooks:MaxAttempts, Webhooks:TimeoutSeconds, Webhooks:SecretRotationWindowHours | 5, 5, 10, 24 | See Webhooks. |
Ingestion:EffectsEnabled | Worker for deferred ingestion effects (embeddings, webhook events). |
Observability
| Key | Notes |
|---|---|
Otel:Enabled | Emit OpenTelemetry traces and metrics. |
Otel:OtlpEndpoint / OTEL_EXPORTER_OTLP_ENDPOINT | Where to send them. |
RequestLog:HashKey | HMAC key used to hash query text in the activity log. Generate one with openssl rand -hex 32. |
HealthEndpoints:Enabled, HealthEndpoints:Urls | Console host's own health server (default http://0.0.0.0:8080). |
In Production, logs are JSON lines with tenant-correlated scopes.
Air-gapped and billing
| Key | Notes |
|---|---|
Deployment:AirGapped | Refuse to start while any configured dependency would leave the network. See Air-gapped. |
Stripe:*, Billing:* | Hosted billing. Leave unset on self-hosted deployments. |
Deployment
Build the Agent Memory image, run it with PostgreSQL and Redis using Docker Compose, apply migrations and create the first tenant and API key.
Air-gapped
Run Agent Memory with no outbound network access — local models, API-key authentication and a start-up guard that refuses any dependency that would leave the perimeter.