Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

4.9 KB
Raw Blame

OpenViking Runtime Query Config

Runtime query config lets operators tune recall and search behavior without restarting OpenClaw. It is intended for live debugging and rollout control around recall limit, candidate count, score threshold, target resource types, and ranking weights.

This document describes the runtime query config capability ported from the broader #2613 work into the split OpenViking plugin PR series.

Configuration Layers

Effective query config is resolved per request with this priority:

explicit tool request arguments
  > session runtime config
  > peer runtime config
  > static plugin config
  > code defaults

The higher layer wins field by field. Object fields such as ranking weights are shallow-merged. Array fields such as resourceTypes replace the lower layer.

Scopes

Runtime config has two persistent scopes:

Scope Meaning
peer Applies to the current OpenClaw peer/assistant identity across sessions.
session Applies only to the current session identity.

For command compatibility, --scope claw is accepted as an alias for peer.

Supported Fields

Field Purpose
recallLimit Number of final recall results to inject or display.
candidateLimit Number of candidates requested before local ranking/filtering by explicit memory_recall.
candidateMultiplier Multiplier used to derive the explicit memory_recall candidate count when candidateLimit is not explicit.
scoreThreshold Minimum score; auto-recall sends it to context search, while explicit memory_recall also applies local post-processing.
maxInjectedChars Injection budget; auto-recall converts it to server max_tokens at four characters per token.
recallPreferAbstract Pin server-assembled auto-recall to abstract detail; explicit memory_recall prefers abstracts locally.
resourceTypes Default semantic recall target types: user, agent, resource.
targetUri Force a single viking:// target URI for search.
ovSearchLimit Default result count for ov_search.
rankingWeights Local ranking weights for explicit memory_recall, such as base score and lexical overlap.
categoryWeights Optional category-specific adjustments for explicit memory_recall.
resourceTypeWeights Optional resource-type adjustments for explicit memory_recall.

Automatic recall uses one session-aware context search and consumes recallLimit, scoreThreshold, maxInjectedChars, recallPreferAbstract, and resourceTypes. Candidate expansion and local ranking-weight fields remain available to explicit memory_recall, but no longer alter automatic recall assembly.

Session history is not a semantic recall target. Use ov_archive_search and ov_archive_expand for session archive recovery.

Slash Command

Get

/ov-query-config get --scope session
/ov-query-config get --scope peer

The response includes the effective config and per-field sources, which are useful for understanding why a value is active.

Set

/ov-query-config set --scope peer \
  --recallLimit 6 \
  --candidateLimit 40 \
  --scoreThreshold 0.15 \
  --resourceTypes user,agent,resource
/ov-query-config set --scope session \
  --ovSearchLimit 8 \
  --recallPreferAbstract true

Weights

/ov-query-config set --scope peer \
  --weight baseScore=1,leaf=0.12,lexicalOverlapMax=0.2 \
  --categoryWeight preference=0.2,event=0.1 \
  --resourceTypeWeight user=0.15,resource=0.1

Unset

/ov-query-config unset recallLimit scoreThreshold rankingWeights --scope session

Reset

/ov-query-config reset --scope session
/ov-query-config reset --scope peer

Persistence

Runtime query config can be persisted by configuring runtimeQueryConfigPath.

{
  "plugins": {
    "entries": {
      "openviking": {
        "config": {
          "runtimeQueryConfigPath": "/path/to/runtime-query-config.json"
        }
      }
    }
  }
}

If the file is missing, the store starts empty. If the file is malformed, the plugin keeps the last known-good in-memory config and reports a warning instead of breaking recall.

Interaction With Tools

memory_recall and ov_search use runtime config as defaults. Explicit arguments on the current tool call still win.

Examples:

  • If peer scope sets ovSearchLimit=8, ov_search defaults to 8 results.
  • If a specific ov_search call passes limit=3, that request returns 3 results and does not mutate runtime config.
  • If session scope sets scoreThreshold, it overrides peer/static threshold only for that session.

Verification

The split implementation is covered by unit tests for:

  • normalization and persistence,
  • layer precedence,
  • empty patch rejection,
  • peer and claw scope compatibility,
  • memory_recall and ov_search runtime defaulting,
  • explicit request arguments overriding runtime defaults.