Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
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_searchdefaults to 8 results. - If a specific
ov_searchcall passeslimit=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,
peerandclawscope compatibility,memory_recallandov_searchruntime defaulting,- explicit request arguments overriding runtime defaults.