OpenViking/docs/design/agent-evolution-global-switch-design.md

Global Agent Evolution Switch Design

Scope

Agent Evolution is controlled by one deployment-level switch for the entire OpenViking server instance. All accounts and users served by the same process share the same effective value.

The switch controls whether session commits may generate or update these memory types:

• cases
• trajectories
• experiences

Disabling the switch does not delete existing files and does not prevent existing experiences from being searched or read.

Configuration

Add the switch directly to ServerConfig:

{
  "server": {
    "agent_evolution": {
      "enabled": false
    }
  }
}

The default is false.

server.user_config_defaults remains responsible only for existing per-user defaults such as add targets. Agent Evolution is no longer part of active UserConfig resolution.

This setting belongs to the HTTP server deployment surface. Embedded/local SDK clients do not load ServerConfig, so they preserve the historical enabled behavior instead of becoming permanently unable to produce Agent memory.

Commit Behavior

SessionService passes the deployment-level Agent Evolution configuration into each Session. A commit applies the global value after validating the session-level memory_policy:

• When enabled, the session policy remains authoritative. A session may still exclude cases, trajectories, or experiences.
• When disabled, the commit removes all three Agent Evolution memory types from the effective policy. A session cannot enable them through memory_policy.

Phase 1 stores the effective boolean and skip reason in archive metadata. Asynchronous Phase 2 reads that snapshot, so normal queue processing and direct recovery of that archive use the value accepted at commit time.

When a later commit rolls earlier failed archives into one recovery batch, the entire batch uses the triggering archive's snapshot. OpenViking keeps one extraction policy per batch instead of splitting the merged conversation across different Agent Evolution settings. Therefore, changing the deployment setting before a later recovery commit can affect replayed messages from earlier failed archives.

Archives created before the snapshot field existed preserve the historical enabled behavior during recovery.

Removed User-Level Surface

Remove Agent Evolution from the active per-user configuration and resolution logic. Retain a deprecated parse-only schema field so existing user_config.json files remain loadable; its value is ignored.

Remove the user-level management surfaces introduced by the current branch:

• GET /api/v1/user-settings/memory
• PATCH /api/v1/user-settings/memory
• Python SDK memory-setting methods
• Embedded client memory-setting methods
• ov user-settings memory
• ov user-settings set-memory
• Agent Evolution fields accepted during account or user creation

Existing stored agent_evolution fields are ignored after upgrade. They do not override the deployment-level setting.

Compatibility

• Existing experiences remain readable and searchable.
• Embedded/local SDK clients preserve their historical enabled behavior because they do not have the HTTP server configuration surface.
• Existing user config files containing agent_evolution continue to parse, preventing an upgrade from breaking users that already wrote the branch-era configuration.
• Session-level memory_policy remains supported as an allow-list below the global switch.
• Queue payload structure remains unchanged; the commit-time decision stays in archive metadata.

Verification

Tests cover:

• Default global value is disabled.
• Explicit global enablement produces Agent Evolution memory when the session policy permits it.
• Global disablement cannot be bypassed by session memory_policy.
• Different users in one server receive the same effective value.
• Existing user config with the deprecated field loads but does not affect the result.
• Phase 2 uses the archived commit-time value.
• Existing experiences remain readable while production is disabled.