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
feat(config): 配置检索打分和 embedding 输入 (#1770)
Qin Haojieb35d38a323b2
diff --git a/README.md b/README.mdindex 2e4a86eaa..1e1b7e267 100644--- a/README.md+++ b/README.md@@ -323,7 +323,9 @@ If you prefer manual configuration, create `~/.openviking/ov.conf`, remove the c"dimension": 1024, // Vector dimension"model" : "<model-name>" // Embedding model name (e.g., doubao-embedding-vision-251215 or text-embedding-3-large)},- "max_concurrent": 10 // Max concurrent embedding requests (default: 10)+ "max_concurrent": 10, // Max concurrent embedding requests (default: 10)+ "text_source": "content_only", // Text file vectorization source: content_only|summary_first|summary_only+ "max_input_tokens": 4096 // Max estimated raw text tokens sent to embedding},"vlm": {"api_base" : "<api-endpoint>", // API endpoint addressdiff --git a/docs/en/concepts/07-retrieval.md b/docs/en/concepts/07-retrieval.mdindex b1666881d..2fcceb3cd 100644--- a/docs/en/concepts/07-retrieval.md+++ b/docs/en/concepts/07-retrieval.md@@ -107,7 +107,7 @@ while dir_queue:for r in results:# Score propagation- final_score = 0.5 * embedding_score + 0.5 * parent_score+ final_score = score_propagation_alpha * embedding_score + (1 - score_propagation_alpha) * parent_scoreif final_score > threshold:collected.append(r)@@ -124,7 +124,7 @@ while dir_queue:| Parameter | Value | Description ||-----------|-------|-------------|-| `SCORE_PROPAGATION_ALPHA` | 0.5 | 50% embedding + 50% parent |+| `retrieval.score_propagation_alpha` | 0.5 | Child-score weight in the propagation blend; `0.5` means 50% child score + 50% parent score || `MAX_CONVERGENCE_ROUNDS` | 3 | Convergence detection rounds || `GLOBAL_SEARCH_TOPK` | 10 | Global search candidates || `MAX_RELATIONS` | 5 | Max relations per resource |diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex 00283aae7..70ebb15ac 100644--- a/docs/en/guides/01-configuration.md+++ b/docs/en/guides/01-configuration.md@@ -193,6 +193,8 @@ Embedding model configuration for vector search, supporting dense, sparse, and h"embedding": {"max_concurrent": 10,"max_retries": 3,+ "text_source": "content_only",+ "max_input_tokens": 4096,"dense": {"provider": "volcengine","api_key": "your-api-key",@@ -210,6 +212,8 @@ Embedding model configuration for vector search, supporting dense, sparse, and h|-----------|------|-------------|| `max_concurrent` | int | Maximum concurrent embedding requests (`embedding.max_concurrent`, default: `10`) || `max_retries` | int | Maximum retry attempts for transient embedding provider errors (`embedding.max_retries`, default: `3`; `0` disables retry) |+| `text_source` | str | Text used for vectorizing text files. `content_only` reads raw content, `summary_first` uses summary when available and falls back to content, `summary_only` uses only summary. Default: `content_only` |+| `max_input_tokens` | int | Maximum estimated raw text tokens sent to the embedding model when content is used. Default: `4096` || `provider` | str | `"volcengine"`, `"openai"`, `"vikingdb"`, `"jina"`, `"voyage"`, `"dashscope"`, or `"gemini"` || `api_key` | str | API key || `model` | str | Model name |@@ -723,6 +727,26 @@ Reranking model for search result refinement. Supports VikingDB (Volcengine), CoIf rerank is not configured, search uses vector similarity only.+### retrieval++Retrieval ranking configuration for final search scores.++```json+{+ "retrieval": {+ "hotness_alpha": 0.0,+ "score_propagation_alpha": 0.5+ }+}+```++| Parameter | Type | Description | Default |+|-----------|------|-------------|---------|+| `hotness_alpha` | float | Weight for blending hotness into final retrieval scores. `0.0` disables the hotness boost and keeps scores equal to semantic similarity; `1.0` uses only hotness. Valid range: `0.0` to `1.0`. | `0.0` |+| `score_propagation_alpha` | float | Weight for each child result's own score when blending with its parent score during hierarchical retrieval. `0.5` keeps the existing equal blend; `1.0` ignores the parent score; `0.0` uses only the parent score. Valid range: `0.0` to `1.0`. | `0.5` |++Keep `hotness_alpha` at `0.0` when you need scores to reflect pure vector similarity. Set it above `0.0` only when frequently accessed or recently updated contexts should receive a ranking boost.+### storageStorage configuration for context data, including file storage (RAGFS) and vector database storage (VectorDB).@@ -1140,6 +1164,8 @@ For detailed encryption explanations, see [Data Encryption](../concepts/10-encry"embedding": {"max_concurrent": 10,"max_retries": 3,+ "text_source": "content_only",+ "max_input_tokens": 4096,"dense": {"provider": "volcengine","api_key": "string",@@ -1167,6 +1193,10 @@ For detailed encryption explanations, see [Data Encryption](../concepts/10-encry"threshold": 0.1,"extra_headers": {}},+ "retrieval": {+ "hotness_alpha": 0.0,+ "score_propagation_alpha": 0.5+ },"encryption": {"enabled": false,"provider": "local|vault|volcengine_kms",diff --git a/docs/zh/concepts/07-retrieval.md b/docs/zh/concepts/07-retrieval.mdindex 6b622c5e1..28a1fbb70 100644--- a/docs/zh/concepts/07-retrieval.md+++ b/docs/zh/concepts/07-retrieval.md@@ -107,7 +107,7 @@ while dir_queue:for r in results:# 分数传播- final_score = 0.5 * embedding_score + 0.5 * parent_score+ final_score = score_propagation_alpha * embedding_score + (1 - score_propagation_alpha) * parent_scoreif final_score > threshold:collected.append(r)@@ -124,7 +124,7 @@ while dir_queue:| 参数 | 值 | 说明 ||------|-----|------|-| `SCORE_PROPAGATION_ALPHA` | 0.5 | 50% embedding + 50% parent |+| `retrieval.score_propagation_alpha` | 0.5 | 分数传播混合中子节点自身分数的权重;`0.5` 表示 50% 子节点分数 + 50% 父节点分数 || `MAX_CONVERGENCE_ROUNDS` | 3 | 收敛检测轮数 || `GLOBAL_SEARCH_TOPK` | 10 | 全局搜索候选数 || `MAX_RELATIONS` | 5 | 每资源最大关联数 |diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex d024dccef..d3312aff9 100644--- a/docs/zh/guides/01-configuration.md+++ b/docs/zh/guides/01-configuration.md@@ -194,6 +194,8 @@ openviking-server doctor"embedding": {"max_concurrent": 10,"max_retries": 3,+ "text_source": "content_only",+ "max_input_tokens": 4096,"dense": {"provider": "volcengine","api_key": "your-api-key",@@ -212,6 +214,8 @@ openviking-server doctor|------|------|------|| `max_concurrent` | int | 最大并发 Embedding 请求数(`embedding.max_concurrent`,默认:`10`) || `max_retries` | int | Embedding provider 瞬时错误的最大重试次数(`embedding.max_retries`,默认:`3`;`0` 表示禁用重试) |+| `text_source` | str | 文本文件向量化时使用的文本来源。`content_only` 读取原文内容;`summary_first` 优先使用摘要,没有摘要时回退到原文;`summary_only` 只使用摘要。默认:`content_only` |+| `max_input_tokens` | int | 使用原文内容向量化时,发送给 embedding 模型的最大估算 token 数。默认:`4096` || `provider` | str | `"volcengine"`、`"openai"`、`"vikingdb"`、`"jina"`、`"voyage"`、`"minimax"`、`"dashscope"` 或 `"gemini"` || `api_key` | str | API Key || `model` | str | 模型名称 |@@ -695,6 +699,26 @@ AST 提取支持:Python、JavaScript/TypeScript、Rust、Go、Java、C/C++。如果未配置 Rerank,搜索仅使用向量相似度。+### retrieval++最终搜索分数的召回排序配置。++```json+{+ "retrieval": {+ "hotness_alpha": 0.0,+ "score_propagation_alpha": 0.5+ }+}+```++| 参数 | 类型 | 说明 | 默认值 |+|------|------|------|--------|+| `hotness_alpha` | float | hotness 分数在最终召回分数中的混合权重。`0.0` 表示关闭 hotness boost,最终分数等于语义相似度;`1.0` 表示只使用 hotness。有效范围:`0.0` 到 `1.0`。 | `0.0` |+| `score_propagation_alpha` | float | 层级检索中,子节点自身分数与父节点传播分数混合时,子节点自身分数的权重。`0.5` 保持当前 50/50 行为;`1.0` 表示忽略父节点分数;`0.0` 表示只使用父节点分数。有效范围:`0.0` 到 `1.0`。 | `0.5` |++如果需要分数严格反映向量相似度,保持 `hotness_alpha` 为 `0.0`。只有当希望高频访问或最近更新的上下文获得排序提升时,才将它设置为大于 `0.0`。+### storage用于存储上下文数据 ,包括文件存储(RAGFS)和向量库存储(VectorDB)。@@ -1114,6 +1138,8 @@ openviking add-resource ./docs --exclude "*.tmp""embedding": {"max_concurrent": 10,"max_retries": 3,+ "text_source": "content_only",+ "max_input_tokens": 4096,"dense": {"provider": "volcengine","api_key": "string",@@ -1141,6 +1167,10 @@ openviking add-resource ./docs --exclude "*.tmp""threshold": 0.1,"extra_headers": {}},+ "retrieval": {+ "hotness_alpha": 0.0,+ "score_propagation_alpha": 0.5+ },"encryption": {"enabled": false,"provider": "local|vault|volcengine_kms",diff --git a/examples/ov.conf.example b/examples/ov.conf.exampleindex 7e3ee09a3..6838e9900 100644--- a/examples/ov.conf.example+++ b/examples/ov.conf.example@@ -89,6 +89,8 @@"provider": "volcengine","input": "multimodal"},+ "text_source": "content_only",+ "max_input_tokens": 4096,"circuit_breaker": {"failure_threshold": 5,"reset_timeout": 60,@@ -157,6 +159,10 @@"model": "qwen3-rerank","threshold": 0.1},+ "retrieval": {+ "hotness_alpha": 0.0,+ "score_propagation_alpha": 0.5+ },"auto_generate_l0": true,"auto_generate_l1": true,"default_search_mode": "thinking",diff --git a/openviking/retrieve/hierarchical_retriever.py b/openviking/retrieve/hierarchical_retriever.pyindex 338caf8ec..bdcde7a0c 100644--- a/openviking/retrieve/hierarchical_retriever.py+++ b/openviking/retrieve/hierarchical_retriever.py@@ -31,7 +31,7 @@ from openviking_cli.retrieve.types import (RelatedContext,TypedQuery,)-from openviking_cli.utils.config import RerankConfig+from openviking_cli.utils.config import RerankConfig, RetrievalConfigfrom openviking_cli.utils.logger import get_loggerlogger = get_logger(__name__)@@ -47,10 +47,8 @@ class HierarchicalRetriever:MAX_CONVERGENCE_ROUNDS = 3 # Stop after multiple rounds with unchanged topkMAX_RELATIONS = 5 # Maximum relations per resource- SCORE_PROPAGATION_ALPHA = 0.5 # Score propagation coefficientDIRECTORY_DOMINANCE_RATIO = 1.2 # Directory score must exceed max child scoreGLOBAL_SEARCH_TOPK = 10 # Global retrieval count (more candidates = better rerank precision)- HOTNESS_ALPHA = 0.2 # Weight for hotness score in final ranking (0 = disabled)LEVEL_URI_SUFFIX = {0: ".abstract.md", 1: ".overview.md"}def __init__(@@ -58,6 +56,7 @@ class HierarchicalRetriever:storage: VikingDBManager,embedder: Optional[Any],rerank_config: Optional[RerankConfig] = None,+ retrieval_config: Optional[RetrievalConfig] = None,):"""Initialize hierarchical retriever with rerank_config.@@ -65,10 +64,14 @@ class HierarchicalRetriever:storage: VikingVectorIndexBackend instanceembedder: Embedder instance (supports dense/sparse/hybrid)rerank_config: Rerank configuration (optional, will fallback to vector search only)+ retrieval_config: Retrieval ranking configuration."""self.vector_store = storageself.embedder = embedderself.rerank_config = rerank_config+ self.retrieval_config = retrieval_config or RetrievalConfig()+ self.hotness_alpha = self.retrieval_config.hotness_alpha+ self.score_propagation_alpha = self.retrieval_config.score_propagation_alpha# Use rerank threshold if available, otherwise use a defaultself.threshold = rerank_config.threshold if rerank_config else 0@@ -405,7 +408,7 @@ class HierarchicalRetriever:f"[RecursiveSearch] Added initial candidate: {uri} (score: {score:.4f})")- alpha = self.SCORE_PROPAGATION_ALPHA+ alpha = self.score_propagation_alpha# Initialize: process starting pointsfor uri, score in starting_points:@@ -505,9 +508,8 @@ class HierarchicalRetriever:"""Convert candidate results to MatchedContext list.Blends semantic similarity with a hotness score derived from- ``active_count`` and ``updated_at`` so that frequently-accessed,- recently-updated contexts get a ranking boost. The blend weight- is controlled by ``HOTNESS_ALPHA`` (0 disables the boost).+ ``active_count`` and ``updated_at`` when configured. The blend weight+ is controlled by ``retrieval.hotness_alpha`` (0 disables the boost)."""results = []@@ -530,25 +532,26 @@ class HierarchicalRetriever:if not math.isfinite(semantic_score):semantic_score = 0.0- # --- hotness boost ---- updated_at_raw = c.get("updated_at")- if isinstance(updated_at_raw, str):- try:- updated_at_val = parse_iso_datetime(updated_at_raw)- except (ValueError, TypeError):+ alpha = self.hotness_alpha+ if alpha > 0:+ updated_at_raw = c.get("updated_at")+ if isinstance(updated_at_raw, str):+ try:+ updated_at_val = parse_iso_datetime(updated_at_raw)+ except (ValueError, TypeError):+ updated_at_val = None+ elif isinstance(updated_at_raw, datetime):+ updated_at_val = updated_at_raw+ else:updated_at_val = None- elif isinstance(updated_at_raw, datetime):- updated_at_val = updated_at_raw- else:- updated_at_val = None-- h_score = hotness_score(- active_count=c.get("active_count", 0),- updated_at=updated_at_val,- )- alpha = self.HOTNESS_ALPHA- final_score = (1 - alpha) * semantic_score + alpha * h_score+ h_score = hotness_score(+ active_count=c.get("active_count", 0),+ updated_at=updated_at_val,+ )+ final_score = (1 - alpha) * semantic_score + alpha * h_score+ else:+ final_score = semantic_scoreif not math.isfinite(final_score):final_score = 0.0level = c.get("level", 2)diff --git a/openviking/service/core.py b/openviking/service/core.pyindex 63293dd84..11fbeb71c 100644--- a/openviking/service/core.py+++ b/openviking/service/core.py@@ -274,6 +274,7 @@ class OpenVikingService:query_embedder=self._embedder,rerank_config=config.rerank,vector_store=self._vikingdb_manager,+ retrieval_config=config.retrieval,enable_recorder=enable_recorder,encryptor=self._encryptor,)diff --git a/openviking/storage/viking_fs.py b/openviking/storage/viking_fs.pyindex fe932f322..112a07341 100644--- a/openviking/storage/viking_fs.py+++ b/openviking/storage/viking_fs.py@@ -49,7 +49,7 @@ from openviking_cli.utils.uri import VikingURIif TYPE_CHECKING:from openviking.storage.transaction.lock_handle import LockHandlefrom openviking.storage.viking_vector_index_backend import VikingVectorIndexBackend- from openviking_cli.utils.config import RerankConfig+ from openviking_cli.utils.config import RerankConfig, RetrievalConfiglogger = get_logger(__name__)@@ -112,6 +112,7 @@ def init_viking_fs(query_embedder: Optional[Any] = None,rerank_config: Optional["RerankConfig"] = None,vector_store: Optional["VikingVectorIndexBackend"] = None,+ retrieval_config: Optional["RetrievalConfig"] = None,timeout: int = 10,enable_recorder: bool = False,encryptor: Optional[Any] = None,@@ -123,6 +124,7 @@ def init_viking_fs(agfs_config: AGFS configuration object for backend settingsquery_embedder: Embedder instancererank_config: Rerank configuration+ retrieval_config: Retrieval ranking configurationvector_store: Vector store instanceenable_recorder: Whether to enable IO recordingencryptor: FileEncryptor instance for encryption/decryption@@ -134,6 +136,7 @@ def init_viking_fs(query_embedder=query_embedder,rerank_config=rerank_config,vector_store=vector_store,+ retrieval_config=retrieval_config,encryptor=encryptor,)@@ -205,6 +208,7 @@ class VikingFS:query_embedder: Optional[Any] = None,rerank_config: Optional["RerankConfig"] = None,vector_store: Optional["VikingVectorIndexBackend"] = None,+ retrieval_config: Optional["RetrievalConfig"] = None,timeout: int = 10,encryptor: Optional[Any] = None,):@@ -212,6 +216,7 @@ class VikingFS:self.query_embedder = query_embedderself.rerank_config = rerank_configself.vector_store = vector_store+ self.retrieval_config = retrieval_configself._encryptor = encryptorself._bound_ctx: contextvars.ContextVar[Optional[RequestContext]] = contextvars.ContextVar("vikingfs_bound_ctx", default=None@@ -1113,6 +1118,7 @@ class VikingFS:storage=storage,embedder=embedder,rerank_config=self.rerank_config,+ retrieval_config=self.retrieval_config,)# Infer context_type (None = search all types)@@ -1271,6 +1277,7 @@ class VikingFS:storage=storage,embedder=embedder,rerank_config=self.rerank_config,+ retrieval_config=self.retrieval_config,)async def _execute(tq: TypedQuery):diff --git a/openviking/utils/embedding_utils.py b/openviking/utils/embedding_utils.pyindex e0e23ca1b..04148b9cc 100644--- a/openviking/utils/embedding_utils.py+++ b/openviking/utils/embedding_utils.py@@ -6,6 +6,7 @@ Embedding utilities for OpenViking.Common logic for creating Context objects and enqueuing them to EmbeddingQueue."""+import mathimport osfrom datetime import datetime, timezonefrom typing import Dict, Optional@@ -22,6 +23,46 @@ from openviking_cli.utils import VikingURI, get_loggerfrom openviking_cli.utils.config import get_openviking_configlogger = get_logger(__name__)+_EMBEDDING_TRUNCATION_SUFFIX = "\n...(truncated for embedding)"+++def _estimate_embedding_input_tokens(text: str) -> int:+ """Estimate tokens for the raw text embedding input guard."""+ if not text:+ return 0+ cjk_chars = sum(+ 1+ for char in text+ if "\u4e00" <= char <= "\u9fff"+ or "\u3040" <= char <= "\u30ff"+ or "\uac00" <= char <= "\ud7af"+ )+ other_chars = len(text) - cjk_chars+ return max(1, cjk_chars + math.ceil(other_chars / 4))+++def _truncate_embedding_input(+ text: str,+ max_tokens: int,+ suffix: str = _EMBEDDING_TRUNCATION_SUFFIX,+) -> str:+ """Trim raw text before embedding using the local estimate above."""+ if not text:+ return text+ if max_tokens <= 0:+ return suffix.lstrip()+ if _estimate_embedding_input_tokens(text) <= max_tokens:+ return text++ low = 0+ high = len(text)+ while low < high:+ mid = (low + high + 1) // 2+ if _estimate_embedding_input_tokens(text[:mid]) <= max_tokens:+ low = mid+ else:+ high = mid - 1+ return text[:low].rstrip() + suffixasync def _decrement_embedding_tracker(semantic_msg_id: Optional[str], count: int) -> None:@@ -326,14 +367,9 @@ async def vectorize_file(content_type = get_resource_content_type(file_name)embedding_cfg = get_openviking_config().embedding- configured_text_source = getattr(embedding_cfg, "text_source", "summary_first")+ configured_text_source = getattr(embedding_cfg, "text_source", "content_only")effective_text_source = "summary_only" if use_summary else configured_text_source- max_input_chars = int(getattr(embedding_cfg, "max_input_chars", 1000) or 1000)-- def _truncate_text(value: str) -> str:- if len(value) <= max_input_chars:- return value- return value[:max_input_chars] + "\n...(truncated for embedding)"+ max_input_tokens = int(getattr(embedding_cfg, "max_input_tokens", 4096) or 4096)if content_type is None:# Unsupported file type: fall back to summary if available@@ -356,7 +392,7 @@ async def vectorize_file(content = await viking_fs.read_file(file_path, ctx=ctx)if isinstance(content, bytes):content = content.decode("utf-8", errors="replace")- content = _truncate_text(content)+ content = _truncate_embedding_input(content, max_input_tokens)context.set_vectorize(Vectorize(text=content))except Exception as e:logger.warning(diff --git a/openviking_cli/utils/config/__init__.py b/openviking_cli/utils/config/__init__.pyindex e600004cf..64a5a6489 100644--- a/openviking_cli/utils/config/__init__.py+++ b/openviking_cli/utils/config/__init__.py@@ -77,6 +77,7 @@ from .parser_config import ()from .prompts_config import PromptsConfigfrom .rerank_config import RerankConfig+from .retrieval_config import RetrievalConfigfrom .storage_config import StorageConfigfrom .telemetry_config import TelemetryConfig, TracerConfigfrom .vectordb_config import VectorDBBackendConfig@@ -131,6 +132,7 @@ __all__ = ["OpenVikingConfigSingleton","OVCLIConfig","RerankConfig",+ "RetrievalConfig","StorageConfig","VectorDBBackendConfig","VLMConfig",diff --git a/openviking_cli/utils/config/embedding_config.py b/openviking_cli/utils/config/embedding_config.pyindex d490f1619..16e40c9c8 100644--- a/openviking_cli/utils/config/embedding_config.py+++ b/openviking_cli/utils/config/embedding_config.py@@ -358,13 +358,13 @@ class EmbeddingConfig(BaseModel):description="Maximum retry attempts for embedding provider calls (0 disables retry)",)text_source: str = Field(- default="summary_first",+ default="content_only",description="Text source for file vectorization: summary_first|summary_only|content_only",)- max_input_chars: int = Field(- default=1000,+ max_input_tokens: int = Field(+ default=4096,ge=100,- description="Maximum characters sent to embeddings when raw text fallback is used",+ description="Maximum estimated tokens sent to embeddings when raw text fallback is used",)model_config = {"extra": "forbid"}diff --git a/openviking_cli/utils/config/open_viking_config.py b/openviking_cli/utils/config/open_viking_config.pyindex 46d85b35d..c8058e056 100644--- a/openviking_cli/utils/config/open_viking_config.py+++ b/openviking_cli/utils/config/open_viking_config.py@@ -38,6 +38,7 @@ from .parser_config import ()from .prompts_config import PromptsConfigfrom .rerank_config import RerankConfig+from .retrieval_config import RetrievalConfigfrom .storage_config import StorageConfigfrom .telemetry_config import TelemetryConfigfrom .vlm_config import VLMConfig@@ -64,6 +65,11 @@ class OpenVikingConfig(BaseModel):rerank: RerankConfig = Field(default_factory=RerankConfig, description="Rerank configuration")+ retrieval: RetrievalConfig = Field(+ default_factory=RetrievalConfig,+ description="Retrieval ranking configuration",+ )+# Encryption configurationencryption: EncryptionConfig = Field(default_factory=EncryptionConfig, description="Encryption configuration"diff --git a/openviking_cli/utils/config/retrieval_config.py b/openviking_cli/utils/config/retrieval_config.pynew file mode 100644index 000000000..b29c28ecd--- /dev/null+++ b/openviking_cli/utils/config/retrieval_config.py@@ -0,0 +1,30 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0++from pydantic import BaseModel, Field+++class RetrievalConfig(BaseModel):+ """Configuration for retrieval ranking behavior."""++ hotness_alpha: float = Field(+ default=0.0,+ ge=0.0,+ le=1.0,+ description=(+ "Weight for blending hotness into final retrieval scores. "+ "0 disables hotness boost; 1 uses only hotness."+ ),+ )+ score_propagation_alpha: float = Field(+ default=0.5,+ ge=0.0,+ le=1.0,+ description=(+ "Weight for each child result's own score when blending with its parent score "+ "during hierarchical retrieval. 0 uses only the parent score; "+ "1 uses only the child score."+ ),+ )++ model_config = {"extra": "forbid"}diff --git a/tests/retrieve/test_hierarchical_retriever_rerank.py b/tests/retrieve/test_hierarchical_retriever_rerank.pyindex 45af89ee6..36bb233ca 100644--- a/tests/retrieve/test_hierarchical_retriever_rerank.py+++ b/tests/retrieve/test_hierarchical_retriever_rerank.py@@ -9,7 +9,7 @@ from openviking.retrieve.hierarchical_retriever import HierarchicalRetriever, Refrom openviking.server.identity import RequestContext, Rolefrom openviking_cli.retrieve.types import ContextType, TypedQueryfrom openviking_cli.session.user_id import UserIdentifier-from openviking_cli.utils.config import RerankConfig+from openviking_cli.utils.config import RerankConfig, RetrievalConfigclass DummyEmbedResult:@@ -182,6 +182,35 @@ class LevelTwoGlobalStorage(DummyStorage):return []+class DirectChildProxy:+ async def search_children_in_tenant(+ self,+ parent_uri: str,+ query_vector=None,+ sparse_query_vector=None,+ context_type=None,+ target_directories=None,+ extra_filter=None,+ limit: int = 10,+ ):+ return [+ {+ "uri": f"{parent_uri}/file-a",+ "abstract": "child A",+ "_score": 0.2,+ "level": 2,+ "context_type": "resource",+ },+ {+ "uri": f"{parent_uri}/file-b",+ "abstract": "child B",+ "_score": 0.8,+ "level": 2,+ "context_type": "resource",+ },+ ]++class FakeRerankClient:def __init__(self, scores):self.scores = list(scores)@@ -366,3 +395,83 @@ async def test_quick_mode_skips_rerank(monkeypatch):"viking://resources/file-a",]assert fake_client.calls == []+++async def test_score_propagation_alpha_uses_configured_weight():+ retriever = HierarchicalRetriever(+ storage=DummyStorage(),+ embedder=None,+ rerank_config=None,+ retrieval_config=RetrievalConfig(score_propagation_alpha=1.0),+ )++ candidates = await retriever._recursive_search(+ vector_proxy=DirectChildProxy(),+ query="hello",+ query_vector=None,+ sparse_query_vector=None,+ starting_points=[("viking://resources", 0.4)],+ limit=1,+ mode=RetrieverMode.QUICK,+ )++ assert candidates[0]["uri"] == "viking://resources/file-b"+ assert candidates[0]["_final_score"] == pytest.approx(0.8)+++async def test_default_retrieval_config_uses_semantic_score_without_hotness(monkeypatch):+ monkeypatch.setattr(+ "openviking.retrieve.hierarchical_retriever.hotness_score",+ lambda *args, **kwargs: pytest.fail("hotness_score should not be called by default"),+ )+ retriever = HierarchicalRetriever(+ storage=DummyStorage(),+ embedder=None,+ rerank_config=None,+ )++ result = await retriever._convert_to_matched_contexts(+ [+ {+ "uri": "viking://resources/file-a",+ "abstract": "child A",+ "_score": 1.0,+ "level": 2,+ "context_type": "resource",+ }+ ],+ ctx=_ctx(),+ )++ assert result[0].score == pytest.approx(1.0)+++async def test_retrieval_hotness_alpha_blends_when_configured(monkeypatch):+ monkeypatch.setattr(+ "openviking.retrieve.hierarchical_retriever.hotness_score",+ lambda *args, **kwargs: 0.5,+ )+ retriever = HierarchicalRetriever(+ storage=DummyStorage(),+ embedder=None,+ rerank_config=None,+ retrieval_config=RetrievalConfig(hotness_alpha=0.2),+ )++ result = await retriever._convert_to_matched_contexts(+ [+ {+ "uri": "viking://resources/file-a",+ "abstract": "child A",+ "_score": 1.0,+ "level": 2,+ "context_type": "resource",+ }+ ],+ ctx=_ctx(),+ )++ assert result[0].score == pytest.approx(0.9)diff --git a/tests/test_config_loader.py b/tests/test_config_loader.pyindex 39dc0b7ca..a9ed1455d 100644--- a/tests/test_config_loader.py+++ b/tests/test_config_loader.py@@ -186,6 +186,37 @@ def test_openviking_config_warns_when_agent_scope_mode_is_configured(monkeypatchOpenVikingConfigSingleton.reset_instance()+def test_openviking_config_retrieval_hotness_alpha_defaults_to_zero(monkeypatch):+ monkeypatch.setenv(OPENVIKING_CONFIG_ENV, "/tmp/codex-no-config.json")++ from openviking_cli.utils.config.open_viking_config import (+ OpenVikingConfig,+ OpenVikingConfigSingleton,+ )++ config = OpenVikingConfig.from_dict({})++ assert config.retrieval.hotness_alpha == 0.0+ assert config.retrieval.score_propagation_alpha == 0.5++ OpenVikingConfigSingleton.reset_instance()++[email protected]("field_name", ["hotness_alpha", "score_propagation_alpha"])+def test_openviking_config_retrieval_alpha_validates_range(monkeypatch, field_name):+ monkeypatch.setenv(OPENVIKING_CONFIG_ENV, "/tmp/codex-no-config.json")++ from openviking_cli.utils.config.open_viking_config import (+ OpenVikingConfig,+ OpenVikingConfigSingleton,+ )++ with pytest.raises(ValueError):+ OpenVikingConfig.from_dict({"retrieval": {field_name: 1.5}})++ OpenVikingConfigSingleton.reset_instance()++def test_openviking_config_singleton_preserves_value_error_for_bad_config(tmp_path, monkeypatch):monkeypatch.setenv(OPENVIKING_CONFIG_ENV, "/tmp/codex-no-config.json")diff --git a/tests/test_memory_lifecycle.py b/tests/test_memory_lifecycle.pyindex f5b68730f..af4a9eabd 100644--- a/tests/test_memory_lifecycle.py+++ b/tests/test_memory_lifecycle.py@@ -106,8 +106,8 @@ class TestHotnessBlending:# B should overtake A due to hotnessassert blended_b > blended_a- def test_default_alpha_preserves_semantic_dominance(self):- """With default alpha=0.2, a large semantic gap is not overturned."""+ def test_small_alpha_preserves_semantic_dominance(self):+ """With a small alpha, a large semantic gap is not overturned."""alpha = 0.2# Memory A: much higher semantic, colddiff --git a/tests/unit/test_embedding_vectorize_strategy.py b/tests/unit/test_embedding_vectorize_strategy.pyindex 7bbb2c28c..bfd6a8c1c 100644--- a/tests/unit/test_embedding_vectorize_strategy.py+++ b/tests/unit/test_embedding_vectorize_strategy.py@@ -25,17 +25,23 @@ def test_embedding_text_source_validation_accepts_supported_values():assert cfg.text_source == value+def test_embedding_text_source_defaults_to_content_only():+ cfg = _cfg()+ assert cfg.text_source == "content_only"+ assert cfg.max_input_tokens == 4096++@pytest.mark.parametrize("bad_value", ["summary", "content", "auto", ""])def test_embedding_text_source_validation_rejects_invalid_values(bad_value):with pytest.raises(ValueError, match="embedding.text_source"):_cfg(text_source=bad_value)-def test_embedding_max_input_chars_validation_accepts_reasonable_value():- cfg = _cfg(max_input_chars=1000)- assert cfg.max_input_chars == 1000+def test_embedding_max_input_tokens_validation_accepts_reasonable_value():+ cfg = _cfg(max_input_tokens=1000)+ assert cfg.max_input_tokens == 1000-def test_embedding_max_input_chars_validation_rejects_too_small_value():+def test_embedding_max_input_tokens_validation_rejects_too_small_value():with pytest.raises(ValueError):- _cfg(max_input_chars=10)+ _cfg(max_input_tokens=10)diff --git a/tests/unit/test_vectorize_file_strategy.py b/tests/unit/test_vectorize_file_strategy.pyindex 5be9a387e..0eded560d 100644--- a/tests/unit/test_vectorize_file_strategy.py+++ b/tests/unit/test_vectorize_file_strategy.py@@ -34,6 +34,8 @@ class DummyFS:class DummyUser:account_id = "default"+ user_id = "default"+ agent_id = "default-agent"def user_space_name(self):return "user/default"@@ -46,6 +48,10 @@ class DummyReq:def __init__(self):self.user = DummyUser()self.account_id = "default"+ self.namespace_policy = types.SimpleNamespace(+ isolate_user_scope_by_agent=False,+ isolate_agent_scope_by_user=False,+ )@pytest.mark.asyncio@@ -57,7 +63,7 @@ async def test_vectorize_file_uses_summary_first(monkeypatch):embedding_utils,"get_openviking_config",lambda: types.SimpleNamespace(- embedding=types.SimpleNamespace(text_source="summary_first", max_input_chars=1000)+ embedding=types.SimpleNamespace(text_source="summary_first", max_input_tokens=1000)),)monkeypatch.setattr(@@ -81,13 +87,14 @@ async def test_vectorize_file_uses_summary_first(monkeypatch):@pytest.mark.asyncioasync def test_vectorize_file_truncates_content_when_content_only(monkeypatch):queue = DummyQueue()+ content = " ".join(f"token-{i}" for i in range(200))monkeypatch.setattr(embedding_utils, "get_queue_manager", lambda: DummyQueueManager(queue))- monkeypatch.setattr(embedding_utils, "get_viking_fs", lambda: DummyFS("A" * 1500))+ monkeypatch.setattr(embedding_utils, "get_viking_fs", lambda: DummyFS(content))monkeypatch.setattr(embedding_utils,"get_openviking_config",lambda: types.SimpleNamespace(- embedding=types.SimpleNamespace(text_source="content_only", max_input_chars=1000)+ embedding=types.SimpleNamespace(text_source="content_only", max_input_tokens=20)),)monkeypatch.setattr(@@ -105,5 +112,5 @@ async def test_vectorize_file_truncates_content_when_content_only(monkeypatch):assert len(queue.items) == 1text = queue.items[0].get_vectorization_text()- assert text.startswith("A" * 1000)assert text.endswith("...(truncated for embedding)")+ assert "token-199" not in text