Skip to main content

Configure Omega memory profiles

A MemoryProfile controls how Omega forms, retrieves, retains, and consolidates memory for an authenticated scope. A profile is policy, not an authorization grant: the server derives tenant, owner, and scope references, and generated RBAC and ACL checks still determine visibility.

Use profiles when administrators need consistent limits for memory types, retention, retrieval modes, context size, provider privacy, or consolidation.

Read the effective profile​

Read the resolved profile for the current principal:

GET /v1/graymatter/omega/memory-profile
curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $VALKYR_AUTH_TOKEN" \
  https://api-0.valkyrlabs.com/v1/graymatter/omega/memory-profile \
  | jq '{profileKey, scopeKind, memoryTypes, allowedRetrievalModes, providerPrivacy, policyVersion}'

The response is the effective policy after server-side inheritance and narrowing. Do not treat a stored profile row as proof that the current principal may read a memory or use a provider.

Profile controls​

ControlPurpose
memoryTypesLimits the durable memory classifications allowed by the profile.
retentionDaysSets a bounded retention period.
formationModeControls whether extracted candidates are explicit, suggested, or automatic.
extractionModeControls extraction from bounded interaction evidence. It does not change an explicit remember request.
consolidationEnabled, consolidationThresholdEnables consolidation and sets its minimum eligible count.
providerPrivacySelects PRIVATE_ONLY, TENANT_APPROVED, or EXTERNAL_WITH_APPROVAL.
allowedRetrievalModes, defaultRetrievalModeLimits the usable FAST, BALANCED, DEEP, AUDIT, and PRIVATE modes.
maxContextTokensCaps the context budget from 256 through 100,000 tokens.
externalProviderApprovalRequiredPreserves an approval requirement for external disclosure.

The current live contract resolves tenant and user scopes. Other scope values remain in the schema for compatible policy ordering but are not a signal that their write path is enabled.

Create a profile​

Manage stored profiles through the generated MemoryProfile API. Send only policy choices. Do not send ownerId, tenantId, scopeRef, audit dates, or other server-owned fields.

{
  "profileKey": "tenant-agent-memory",
  "scopeKind": "TENANT",
  "status": "ACTIVE",
  "memoryTypes": ["preference", "decision", "todo", "business_fact"],
  "retentionDays": 365,
  "formationMode": "SUGGESTED",
  "extractionMode": "SUGGESTED",
  "consolidationEnabled": true,
  "consolidationThreshold": 50,
  "providerPrivacy": "TENANT_APPROVED",
  "allowedRetrievalModes": ["FAST", "BALANCED"],
  "defaultRetrievalMode": "BALANCED",
  "maxContextTokens": 4096,
  "externalProviderApprovalRequired": true,
  "policyVersion": "tenant-memory-v1"
}

Only an authorized tenant administrator can create a tenant profile. A user profile may narrow the inherited tenant policy; it cannot widen allowed modes, privacy, retention, context, or formation behavior.

Validate a change​

After creating or updating a stored profile:

  1. Read the effective profile through /v1/graymatter/omega/memory-profile as the intended user.
  2. Confirm the returned policyVersion, retrieval modes, provider privacy, and context limit.
  3. Exercise a bounded remember or recall request and inspect its receipt and policy result.
  4. Test a disallowed mode or provider path and confirm that it fails closed.