Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""Parameter contract and normalization for server-side context assembly."""
from __future__ import annotations
from dataclasses import dataclass, field
from typing import Any, Dict, Literal, Mapping, Optional, Sequence, Tuple, Union
from openviking.core.retrieval_types import SearchType
Detail = Literal["abstract", "overview", "full"]
# "auto" no longer selects a strategy; it is accepted as a synonym for "unset".
DetailRequest = Union[Literal["auto", "abstract", "overview", "full"], Dict[str, Detail]]
Tier = Literal["uri", "abstract", "overview", "full"]
Purpose = Literal["chat", "coding"]
MEMORY_CATEGORIES: Tuple[str, ...] = ("events", "entities", "preferences", "experiences")
# Built-in memory types outside MEMORY_CATEGORIES — cases, patterns, tools,
# trajectories and skill-usage memories — cannot own a quota bucket: their
# retrieval scope is the memory root, which every other bucket already covers.
# Flat retrieval still reaches them, so they report under one catch-all category
# that carries a tier default and an other-peer penalty like any named one.
OTHER_MEMORY_CATEGORY = "memories"
CATEGORY_KEYS: Tuple[str, ...] = (*MEMORY_CATEGORIES, "resources", "skills")
# Every category an entry may be reported as. Quotas take CATEGORY_KEYS only;
# `detail` and per-category penalties accept the catch-all as well.
REPORTED_CATEGORY_KEYS: Tuple[str, ...] = (*CATEGORY_KEYS, OTHER_MEMORY_CATEGORY)
TIER_ORDER: Tuple[Tier, ...] = ("uri", "abstract", "overview", "full")
TIER_RANK: Dict[str, int] = {tier: rank for rank, tier in enumerate(TIER_ORDER)}
PINNABLE_TIERS: Tuple[Detail, ...] = ("abstract", "overview", "full")
DEFAULT_MAX_TOKENS = 1600
DEFAULT_LIMIT = 10
MAX_EXCLUDE_URIS = 200
MAX_PLANNED_QUERIES = 3
READ_CONCURRENCY = 8
OTHER_PEER_OVERFETCH = 4
# Candidates reranked per served slot, as HierarchicalRetriever.RERANK_CANDIDATE_MULTIPLIER.
RERANK_CANDIDATE_MULTIPLIER = 2
ORIGIN_ORDER: Tuple[str, ...] = ("actor_peer", "self", "other_peer")
# Tier a category is served at when the caller does not pin ``detail``.
#
# ``events`` is the only memory type whose body is long enough for the
# ``# Summary`` section to be a real compression, so it is the only one worth a
# file read. The others sit at ``abstract`` because the memory writer stores the
# whole stripped body in that scalar (it doubles as the embedding text), which
# makes ``abstract`` the complete file at zero read cost. Once the writer stores
# a separate summary scalar, ``events`` moves back to ``abstract`` here and the
# default path stops reading files altogether.
# ``resources``/``skills`` stay at their generated 256-char abstract: their
# bodies are large and may carry credentials, so deepening is opt-in.
DEFAULT_TIER_BY_CATEGORY: Dict[str, Tier] = {
"events": "overview",
"entities": "abstract",
"preferences": "abstract",
"experiences": "abstract",
"resources": "abstract",
"skills": "abstract",
OTHER_MEMORY_CATEGORY: "abstract",
}
DEFAULT_TIER: Tier = "abstract"
# Categories whose stored ``abstract`` holds the whole file body, because the
# memory writer reuses that scalar as embedding text. For them ``overview`` sits
# *below* ``abstract`` on the content ladder, so standing in for a missing or
# oversized abstract discloses less rather than more. A resource or skill
# abstract is the short generated summary instead, and substituting overview
# there would read a body the caller never asked for — the deepening those two
# categories opt into explicitly.
FULL_BODY_ABSTRACT_CATEGORIES: frozenset[str] = frozenset(
(*MEMORY_CATEGORIES, OTHER_MEMORY_CATEGORY)
)
# How far leftover budget may raise a category above its default tier. A
# category absent here never deepens, which is what keeps the default path from
# reading resource bodies.
DEPTH_CEILING_BY_CATEGORY: Dict[str, Tier] = {"events": "full"}
# Purpose presets are first-pass bucket ceilings. Their total is the candidate
# width for bucketed retrieval, and slots a bucket leaves unused go to the best
# remaining hits of the other buckets; ``limit`` belongs only to flat mode.
PURPOSE_PRESETS: Dict[str, Dict[str, int]] = {
"coding": {
"events": 1,
"entities": 2,
"preferences": 1,
"experiences": 1,
"resources": 3,
"skills": 2,
},
"chat": {
"events": 3,
"entities": 3,
"preferences": 1,
"experiences": 1,
"resources": 1,
"skills": 1,
},
}
DEFAULT_QUOTAS: Dict[str, int] = {
"events": 10,
"entities": 10,
"preferences": 3,
"experiences": 0,
}
DEFAULT_OTHER_PEER_PENALTIES: Dict[str, float] = {
"events": 0.1,
"entities": 0.1,
"preferences": 0.02,
"experiences": 0.02,
"resources": 0.02,
"skills": 0.02,
OTHER_MEMORY_CATEGORY: 0.1,
}
@dataclass
class AssembleParams:
"""Resolved request contract for one context assembly run."""
query: str = ""
search_type: SearchType = "semantic"
image_url: str | list[str] | None = None
limit: int = DEFAULT_LIMIT
score_threshold: Optional[float] = None
filter: Optional[Dict[str, Any]] = None
events_time_decay_protection: Optional[str] = None
session_id: Optional[str] = None
query_expansion: Literal["off", "auto"] = "auto"
max_tokens: int = DEFAULT_MAX_TOKENS
quotas: Optional[Mapping[str, int]] = None
purpose: Optional[Purpose] = None
detail: Any = None
dedup_turns: int = 0
exclude_uris: Sequence[str] = field(default_factory=tuple)
peer_scope: Literal["actor", "all"] = "all"
other_peer_penalty: Any = None
rewrite: Any = False
rewrite_max_bullets: int = 6
render: bool = True
def normalize_quotas(
quotas: Optional[Mapping[str, Any]],
purpose: Optional[str] = None,
) -> Optional[Dict[str, int]]:
"""Resolve the active quota map, or ``None`` when bucketed sampling is off."""
if quotas is None:
if not purpose:
return None
preset = PURPOSE_PRESETS.get(purpose)
return dict(preset) if preset else None
resolved: Dict[str, int] = {}
for key, value in quotas.items():
if key not in CATEGORY_KEYS:
continue
try:
resolved[key] = max(0, int(value))
except (TypeError, ValueError):
resolved[key] = 0
return resolved
def _clamp_penalty(value: Any, fallback: float) -> float:
try:
penalty = float(value)
except (TypeError, ValueError):
penalty = fallback
return min(1.0, max(0.0, penalty))
def normalize_penalties(value: Any = None) -> Dict[str, float]:
"""Normalize other-peer score penalties per category."""
if value is None:
return dict(DEFAULT_OTHER_PEER_PENALTIES)
if isinstance(value, Mapping):
merged = dict(DEFAULT_OTHER_PEER_PENALTIES)
for key, penalty in value.items():
if key not in DEFAULT_OTHER_PEER_PENALTIES:
continue
merged[key] = _clamp_penalty(penalty, merged[key])
return merged
penalty = _clamp_penalty(value, 0.0)
return dict.fromkeys(REPORTED_CATEGORY_KEYS, penalty)
def normalize_exclude_uris(values: Optional[Sequence[str]]) -> set[str]:
return {str(uri).strip() for uri in (values or ())[:MAX_EXCLUDE_URIS] if str(uri).strip()}
@dataclass(frozen=True)
class DetailPins:
"""Resolved ``detail`` request field: an explicit tier per category, if any."""
scalar: Optional[Detail] = None
by_category: Mapping[str, Detail] = field(default_factory=dict)
def for_category(self, category: str) -> Optional[Detail]:
"""The pinned tier for ``category``, or ``None`` to use its default."""
return self.by_category.get(category, self.scalar)
def as_stats(self) -> Any:
return dict(self.by_category) if self.by_category else self.scalar
def normalize_detail(value: Any) -> DetailPins:
"""Resolve ``detail`` from a scalar, a per-category mapping, or nothing.
Unknown tiers are dropped rather than raised: the MCP tool signature cannot
enforce an enum, and a stray value there must degrade to the defaults
instead of failing the whole call.
"""
if isinstance(value, DetailPins):
return value
if isinstance(value, Mapping):
return DetailPins(
by_category={
key: tier
for key, tier in value.items()
if key in REPORTED_CATEGORY_KEYS and tier in PINNABLE_TIERS
}
)
return DetailPins(scalar=value if value in PINNABLE_TIERS else None)