Platform
Workspace settings
Tune retrieval, consolidation, screening, retention, learning and promotion per workspace or per organization, and how setting values are resolved.
Most of Agent Memory's behaviour can be tuned without a deployment. Settings are changed in the web console under Settings, at one of two scopes:
- Workspace settings apply to one project.
- Tenant settings apply to the whole organization.
How a value is resolved
For each setting, the first value found wins:
- a workspace override,
- a tenant override,
- the deployment's configuration key (self-hosted operators set these — listed below),
- the built-in default.
Numeric values are kept inside a fixed range, so an override can tune behaviour but not disable a guardrail.
Retrieval
| Setting | Scope | Default | Range / values | Effect |
|---|---|---|---|---|
retrieval.tokenBudget | workspace | 4000 | 256–32,000 | Token budget of the compiled context. A request's tokenBudget overrides it. |
retrieval.mode | workspace | deterministic | assisted, deterministic | Whether recall may call the LLM to decompose queries and rerank. |
retrieval.scoringVersion | workspace | v3 | v1, v2, v3 | Scoring configuration. |
retrieval.minVectorSimilarity | workspace | 0.25 | 0–1 | Minimum cosine similarity for a vector match. |
retrieval.minProcedureSimilarity | workspace | 0.25 | 0–1 | Minimum similarity for a procedure to be recalled. |
retrieval.hideSuperseded | workspace | on | Hide replaced memories from every retrieval path. | |
retrieval.valueAware.enabled | workspace | off | Blend learned utility into ranking. | |
retrieval.utilityWeight | workspace | 0.5 | 0–1 | How strongly utility re-weights value-aware ranking. |
retrieval.valueAwareTopN | workspace | 10 | 1–100 | How many top results value-aware re-ranking considers. |
See Retrieval.
Ingestion and screening
| Setting | Scope | Default | Effect |
|---|---|---|---|
screening.enabled | workspace | on | Screen appended content for prompt injection and exfiltration; flagged content is quarantined. |
screening.pii.enabled | workspace | on | Detect personal data on write; flagged memories are never promoted to tenant conventions and are redacted in exports. |
dedup.enabled | workspace | on | Merge near-duplicate appends into the existing memory. |
inferenceOnAppend.enabled | workspace | on | Derive facts and inferences automatically when memories are appended. |
ingestion.asyncEmbedding | workspace | off | Embed through a durable, retried background effect after the append commits, instead of inline. When on, a memory may not be semantically searchable the instant the append returns — check the ingestion receipt. |
Consolidation
| Setting | Scope | Default | Range | Effect |
|---|---|---|---|---|
consolidation.maxEntriesPerRun | workspace | 500 | 1–10,000 | Session entries a consolidation extracts facts from; the rest are recorded as episode events only. |
consolidation.maxFactsPerEntry | workspace | 20 | 1–100 | Facts kept per entry. |
consolidation.maxDerivativeSentences | workspace | 200 | 10–2,000 | Sentence fragments embedded per episode. |
Blocks and profiles
| Setting | Scope | Default | Range | Effect |
|---|---|---|---|---|
blocks.maxValueChars | workspace | 2000 | 200–10,000 | Maximum characters per memory block. |
userProfile.maxChars | workspace | 2000 | 200–10,000 | Maximum characters per user profile. |
userProfile.autoEnrich | workspace | off | Append preference facts found at consolidation to the user's profile. |
Learning
| Setting | Scope | Default | Range | Effect |
|---|---|---|---|---|
learning.enabled | tenant | on in the shipped API configuration | Record which memories each run saw and update their utility from outcomes. | |
learning.utilityAlpha | tenant | 0.1 | 0.01–1 | Step size of the utility update per outcome. |
See Learning loop.
Promotion and governance
| Setting | Scope | Default | Range | Effect |
|---|---|---|---|---|
promotion.workspaceCandidates.enabled | workspace | off | Hold consolidated facts as review candidates, hidden from recall until a tenant admin approves them. | |
promotion.candidateTtlDays | tenant | 14 | 1–365 | Days an unreviewed promotion candidate waits before it is marked expired (kept, not deleted). |
governance.floorSemanticThreshold | tenant | 0.75 | 0.5–0.95 | Similarity above which content counts as overlapping a tenant floor. |
trust.authority.<kind> | tenant | 1.0 | 0–1 | Source-authority component of the trust score for memories whose sourceKind is <kind> (agent, user, document, import, system, derived). Affects trust only, never ranking. |
Retention
| Setting | Scope | Default | Range | Effect |
|---|---|---|---|---|
retention.memoryDays | workspace | not active | 1–3,650 | Age after which the daily sweep deletes memories (with the full erasure cascade). Only runs when overridden or configured. |
retention.episodeDays | workspace | not active | 1–3,650 | Age after which an ended episode's verbatim events and sentence fragments are removed; the summary stays. Only runs when overridden or configured. |
retention.requestLogDays | workspace | 30 | 1–3,650 | How long activity-log entries are kept. |
retention.webhookDeliveryDays | workspace | 30 | 1–365 | How long webhook delivery attempts are kept. |
Model provider
| Setting | Scope | Default | Effect |
|---|---|---|---|
llm.provider | tenant | anthropic | LLM provider for extraction, inference and summarization: anthropic or openai. |
llm.model | tenant | provider default | Model name for the selected provider. |
Organizations can store their own provider API key in the console (Settings → secrets) so LLM work for their tenant uses it. Keys are encrypted at rest and never returned. On air-gapped deployments a tenant override cannot route LLM calls outside the network.
Security
| Setting | Scope | Default | Effect |
|---|---|---|---|
security.requireMfa | tenant | off | Require MFA-verified sign-ins for console access to the organization. |
Configuration keys for self-hosting
Each setting's deployment-wide default comes from a configuration key, settable as an environment variable with __ in place of ::
| Setting | Configuration key |
|---|---|
retrieval.tokenBudget | Memory:Retrieval:TokenBudget |
retrieval.mode | Memory:Retrieval:Mode |
retrieval.scoringVersion | Memory:Retrieval:ScoringVersion |
retrieval.minVectorSimilarity | Memory:Retrieval:MinVectorSimilarity |
retrieval.minProcedureSimilarity | Memory:Retrieval:MinProcedureSimilarity |
retrieval.hideSuperseded | Memory:Retrieval:HideSuperseded |
retrieval.valueAware.enabled | Memory:Retrieval:ValueAware:Enabled |
retrieval.utilityWeight | Memory:Retrieval:UtilityWeight |
retrieval.valueAwareTopN | Memory:Retrieval:ValueAwareTopN |
screening.enabled | Memory:ContentScreening:Enabled |
screening.pii.enabled | Memory:ContentScreening:Pii:Enabled |
dedup.enabled | Memory:Dedup:Enabled |
inferenceOnAppend.enabled | Memory:InferenceOnAppend:Enabled |
ingestion.asyncEmbedding | Ingestion:AsyncEmbedding |
consolidation.maxEntriesPerRun | Memory:Consolidation:MaxEntriesPerRun |
consolidation.maxFactsPerEntry | Memory:Consolidation:MaxFactsPerEntry |
consolidation.maxDerivativeSentences | Memory:Consolidation:MaxDerivativeSentences |
blocks.maxValueChars | Memory:Blocks:MaxValueChars |
userProfile.maxChars | Memory:UserProfile:MaxChars |
userProfile.autoEnrich | Memory:UserProfile:AutoEnrich |
learning.enabled | Memory:Learning:Enabled |
learning.utilityAlpha | Memory:Learning:UtilityAlpha |
promotion.workspaceCandidates.enabled | Memory:Promotion:WorkspaceCandidates:Enabled |
promotion.candidateTtlDays | Memory:Promotion:CandidateTtlDays |
governance.floorSemanticThreshold | Memory:FloorConflict:SemanticThreshold |
trust.authority.<kind> | Memory:Trust:Authority:<Kind> |
retention.memoryDays | Memory:RetentionDays |
retention.episodeDays | Memory:EpisodeRetentionDays |
retention.requestLogDays | RequestLog:RetentionDays |
retention.webhookDeliveryDays | Webhooks:DeliveryRetentionDays |
llm.provider | Llm:Provider |
llm.model | Llm:Model |
security.requireMfa | Security:RequireMfa |
See Configuration for the rest of the deployment configuration.