Configuration
The components and key settings an operator can change when running Agent Memory.
This page covers the components and the most important settings that the operator running the service can change.
Where settings are read from
- Request level: some search fields (
mode,tokenBudget,overrides) apply to that call only. - Workspace and tenant settings: written from the console (Settings) or the management API; they override server defaults. The workspace setting is checked first, then the tenant setting.
- Server configuration:
appsettings.jsonand environment variables. Environment variables take precedence and use double underscores (Embedding:Provider→Embedding__Provider).
The Docker image does not include the development settings file; in a container, connection strings, authentication and everything else are supplied through environment variables.
Connections (required)
| Key | Description |
|---|---|
ConnectionStrings__ControlPlaneDb | Control plane database (agentmemory), control_plane role. |
ConnectionStrings__SharedDb | Shared tenant data (tenant_shared), app_runtime role (subject to RLS). |
ConnectionStrings__PlatformDb | Platform rules database. |
ConnectionStrings__*Migrations | Owner connections used for migrations. |
ConnectionStrings__Redis | Redis. |
APP_RUNTIME_PASSWORD, CONTROL_PLANE_PASSWORD | Passwords the migration assigns to the roles. Required in Production. |
Migration: dotnet run --project AgentMemory -- --migrate (after every new release).
AI components
Paid AI guard
Deployment__NoPaidAi defaults to true. In this mode:
- if no embedding provider is set,
hashingis used; - if a paid embedding provider (
bedrock, oropenaiwith a public address) is selected, the service stops at startup; - an LLM can only be used with an OpenAI-compatible server on the internal network (
Llm__Provider=openai+ a localLlm__OpenAI__BaseUrl); otherwise steps that need an LLM fall back to rule-based paths.
To use paid providers, set Deployment__NoPaidAi=false.
With Deployment__AirGapped=true, the service rejects cloud dependencies at startup; only API key authentication and local models are used. See Deployment.
LLM
| Key | Default | Description |
|---|---|---|
Llm__Provider | anthropic | anthropic or openai. Any other value fails at startup. |
Llm__Anthropic__ApiKey, Llm__Anthropic__Model | — | Anthropic. |
Llm__OpenAI__ApiKey, Llm__OpenAI__Model, Llm__OpenAI__BaseUrl | gpt-4o-mini, https://api.openai.com/v1 | OpenAI or any OpenAI-compatible server (Ollama, vLLM, LM Studio) via BaseUrl. |
Llm__TimeoutSeconds | 60 | |
Llm__MaxConcurrentPerTenant | 2 | Concurrent LLM calls per tenant; exceeding it returns 429 RATE_LIMITED. |
Tenants can define their own providers/models and API keys (stored encrypted) on the console's Settings → General page and test the connection. Allowed providers can be restricted with Llm__AllowedProviders.
The LLM is used for: extracting facts from raw text during consolidation, summarizing long content, entity extraction, abstraction, the tenant floor contradiction check, and query parsing/reranking in assisted mode. Writes and deterministic search do not use an LLM.
Embedding
Embedding__Provider | Model | Notes |
|---|---|---|
hashing | Feature hashing | Default. Not semantic; based on word overlap. Free and local. |
onnx | Local ONNX model (Embedding__Onnx__ModelPath, VocabPath, ModelName; e.g. all-MiniLM-L6-v2, 384 dimensions) | Free, local and semantic. The repo's scripts/fetch-eval-model.sh downloads a sample model. |
openai | text-embedding-3-small (1536) | An OpenAI-compatible server can also be used via Embedding__OpenAI__BaseUrl. |
bedrock | Embedding__Bedrock__ModelId (default Titan v2, 1024), Region | AWS Bedrock. |
Vectors are stored at 1536 dimensions; smaller models are padded, and models larger than 1536 are rejected (not truncated).
Switching providers: old vectors can't be compared with the new model. The platform supports rebuild, cutover and rollback with two vector slots per tenant (active + next) (Embedding__Next__* and the admin endpoints). Run an evaluation before switching.
Full-text search
Fts__Language: the PostgreSQL text search configuration — simple (default, language-neutral), turkish, english … Run --migrate after changing it.
Memory behavior (workspace/tenant settings)
| Setting | Default | Effect |
|---|---|---|
retrieval.mode | deterministic | assisted enables LLM query parsing and reranking. |
retrieval.tokenBudget | 4000 | Default context budget. |
retrieval.hideSuperseded | true | Hides superseded memories. |
retrieval.minVectorSimilarity | 0.25 | Minimum similarity for vector results. |
retrieval.scoringVersion | v3 | Scoring version. |
retrieval.valueAware.enabled, retrieval.utilityWeight, retrieval.valueAwareTopN | off, 0.5, 10 | Factors learned utility into ranking. |
dedup.enabled | true | Duplicate check on write. Can be turned off for bulk imports. |
inferenceOnAppend.enabled | true | Relation edges to similar memories on write. |
ingestion.asyncEmbedding | false | Computes embeddings in the background, separate from the write request (the memory may briefly not appear in vector search). |
learning.enabled, learning.utilityAlpha | depends on server configuration, 0.1 | Utility learning from outcome reports. |
screening.enabled, screening.pii.enabled | true | Injection quarantine and personal data detection. |
blocks.maxValueChars, userProfile.maxChars | 2000 | Length limit for blocks and profiles. |
userProfile.autoEnrich | false | Automatically fills the profile from preferences. |
consolidation.maxEntriesPerRun, consolidation.maxFactsPerEntry | 500, 20 | Consolidation limits. |
promotion.workspaceCandidates.enabled | false | Hides consolidation facts until an admin approves them. |
promotion.candidateTtlDays | 14 | Lifetime of tenant rule candidates. |
retention.memoryDays, retention.episodeDays | off | Age-based retention. |
trust.authority.<kind> | 1.0 | Source kind authority (trust score only). |
security.requireMfa | — | Requires multi-factor sign-in for the console. |
Background jobs
| Setting | Default |
|---|---|
MemoryMaintenance__Enabled, IntervalMinutes, IdleTimeoutMinutes | true, 5, 30 — automatic consolidation of idle runs. Runs in the background host (Runtime__Mode=service) or inside the API with MemoryMaintenance__Host=api; don't enable both. |
Webhooks__Enabled, MaxAttempts, DeliveryRetentionDays | true, 5, 30 |
Retention__Enabled, MemoryHistoryDays, ConsoleAuditDays | true, 365, 400 |
Hangfire__Enabled | true — scheduled jobs (retention, webhook delivery, deletion retries, embedding rebuilds). |
Authentication
| Key | Description |
|---|---|
OAuth__Enabled, OAuth__Issuer, OAuth__SigningCertificate, OAuth__EncryptionCertificate | Built-in OAuth server (keyless connection for MCP clients). Without certificates the keys are ephemeral; provide them in production. |
OAuth__AllowedRedirectHosts | Redirect hosts allowed in dynamic client registration (default: claude.ai, localhost, 127.0.0.1). |
Auth__Google__*, Auth__Oidc__* | Google and OIDC (e.g. Microsoft Entra) for console sign-in. |
Auth__Authority, Auth__Audience | JWT validation for an external identity provider. |
SignUp__Mode, SignUp__AllowedDomains | Sign-up policy: open, domain-allowlist, invite-only, approval. |
Auth__Dev__Enabled | Development only: passwordless console sign-in and /dev/auth/token. Does not work in Production. |
Production requires the built-in OAuth server or a fully configured external identity provider (except for air-gapped installs).
Limits and quotas
| Key | Default |
|---|---|
RateLimit__PermitPerMinute | 0 (off). Per-tenant requests per minute; exceeding it returns 429 RATE_LIMITED. |
RateLimit__WorkspacePermitPerMinute, RateLimit__AnonymousPermitPerMinute | 0, 30 |
Api__MaxRequestBodyBytes | 1 MiB (exceeding it returns 413) |
Api__MaxConcurrentRequests | 0 (off). Returns 503 OVERLOADED under overload. |
Quota__Max{WorkspaceMemories,Episodes,Procedures,FileDocs,Projects,ApiKeys,Webhooks,StorageBytes}PerTenant | 0 (unlimited). Can be overridden per tenant. |
The plan-based monthly operation quota applies to /v1/memory/* calls and MCP tool calls (429 QUOTA_EXCEEDED).