Skip to content

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

fix(reindex): reject non-recursive semantic namespace requests (#5395)

Evob22332c40edd
diff --git a/docs/en/api/12-content.md b/docs/en/api/12-content.md
index eb726bffc..6f663bce8 100644
--- a/docs/en/api/12-content.md
+++ b/docs/en/api/12-content.md
@@ -631,7 +631,7 @@ For `resource` and `skill`, `semantic_and_vectors` refreshes directory/file sema
For `semantic_and_vectors`, semantic generation and vector rebuilding are sequenced by the reindex executor. The semantic refresh step does not enqueue its own background vectorization work; vectors are rebuilt by the reindex step so `wait=true` reflects the reindex operation itself.
-For a `resource` or `memory` directory, `recursive=false` regenerates only the target directory's `.abstract.md` and `.overview.md`, then rebuilds only that directory's L0/L1 vectors. Child directories do not regenerate semantic artifacts, and neither child directories nor files are re-vectorized. The target aggregation still reads existing summaries from deterministically sampled child directories; sampled direct files are summarized as inputs to the target aggregation. For a `skill` target, `recursive=false` regenerates the skill directory's L0/L1 semantic artifacts and vectors from `SKILL.md`, but does not rebuild the `SKILL.md` L2 vector. This flag does not change existing behavior for `vectors_only`, `prune_orphans`, or namespace targets.
+For a `resource` or `memory` directory, `recursive=false` regenerates only the target directory's `.abstract.md` and `.overview.md`, then rebuilds only that directory's L0/L1 vectors. Child directories do not regenerate semantic artifacts, and neither child directories nor files are re-vectorized. The target aggregation still reads existing summaries from deterministically sampled child directories; sampled direct files are summarized as inputs to the target aggregation. For a `skill` target, `recursive=false` regenerates the skill directory's L0/L1 semantic artifacts and vectors from `SKILL.md`, but does not rebuild the `SKILL.md` L2 vector. Namespace targets (such as `viking://user/<user_id>` or its `skills` container) do not support `recursive=false` with `semantic_and_vectors`; these requests are rejected before starting reindex work. Select a concrete resource, memory, or skill directory for a non-recursive refresh. This flag does not change existing behavior for `vectors_only` or `prune_orphans`.
For `prune_orphans`, source existence is checked against the filesystem. If an entire directory is missing, vector records for files and semantic sidecars below that directory, such as `.abstract.md` and `.overview.md`, are pruned together. `dry_run` is rejected for other modes.
diff --git a/docs/zh/api/12-content.md b/docs/zh/api/12-content.md
index 8060524ce..e2ffe90df 100644
--- a/docs/zh/api/12-content.md
+++ b/docs/zh/api/12-content.md
@@ -631,7 +631,7 @@ session 子树会被跳过。
对于 `semantic_and_vectors`,语义刷新和向量重建由 reindex executor 串行编排。语义刷新阶段不会再额外向后台 embedding queue 投递自己的向量化任务;向量由 reindex 阶段统一重建,因此 `wait=true` 表示等待 reindex 操作本身完成。
-对 `resource` 或 `memory` 目录设置 `recursive=false` 时,只重新生成目标目录的 `.abstract.md`、`.overview.md`,并重建该目录的 L0/L1 向量;下级目录不会重新生成语义产物,下级目录和文件也不会重新向量化。目标目录仍会读取本轮确定性采样命中的既有下级摘要;若采样命中直接文件,仍会为当前目录聚合准备这些文件的摘要。对 `skill` 目标设置 `recursive=false` 时,会根据 `SKILL.md` 重新生成 skill 目录的 L0/L1 语义产物及向量,但不会重建 `SKILL.md` 的 L2 向量。该参数不改变 `vectors_only`、`prune_orphans` 或 namespace 目标的既有行为。
+对 `resource` 或 `memory` 目录设置 `recursive=false` 时,只重新生成目标目录的 `.abstract.md`、`.overview.md`,并重建该目录的 L0/L1 向量;下级目录不会重新生成语义产物,下级目录和文件也不会重新向量化。目标目录仍会读取本轮确定性采样命中的既有下级摘要;若采样命中直接文件,仍会为当前目录聚合准备这些文件的摘要。对 `skill` 目标设置 `recursive=false` 时,会根据 `SKILL.md` 重新生成 skill 目录的 L0/L1 语义产物及向量,但不会重建 `SKILL.md` 的 L2 向量。namespace 目标(例如 `viking://user/<user_id>` 或其 `skills` 容器)不支持在 `semantic_and_vectors` 模式下设置 `recursive=false`;这类请求会在启动重建前被拒绝。非递归刷新请选择具体的 resource、memory 或 skill 目录。该参数不改变 `vectors_only` 或 `prune_orphans` 的既有行为。
对于 `prune_orphans`,源文件是否存在以当前文件系统为准。如果整个目录已经不存在,该目录下的正文文件向量和语义 sidecar 向量(例如 `.abstract.md`、`.overview.md`)会一起清理。`dry_run` 用在其他模式时会被拒绝。
diff --git a/openviking/service/reindex_executor.py b/openviking/service/reindex_executor.py
index 4860dd5a9..9027517d2 100644
--- a/openviking/service/reindex_executor.py
+++ b/openviking/service/reindex_executor.py
@@ -213,6 +213,15 @@ class ReindexExecutor:
) -> dict[str, Any]:
object_type = self._infer_target_type(uri)
self._validate_mode(object_type, mode)
+ if (
+ mode == "semantic_and_vectors"
+ and not recursive
+ and object_type in {"global_namespace", "user_namespace", "skill_namespace"}
+ ):
+ raise InvalidArgumentError(
+ "recursive=false is not supported for namespace reindex targets. "
+ "Select a resource, memory, or skill directory instead."
+ )
if dry_run and mode != "prune_orphans":
raise InvalidArgumentError("dry_run is only supported for prune_orphans reindex mode.")
ingest_options = self._resolve_ingest_options(
diff --git a/tests/server/test_admin_rebuild_api.py b/tests/server/test_admin_rebuild_api.py
index 428f0af01..ef0cc0dc7 100644
--- a/tests/server/test_admin_rebuild_api.py
+++ b/tests/server/test_admin_rebuild_api.py
@@ -1481,6 +1481,40 @@ async def test_reindex_memory_semantic_and_vectors_rebuilds_full_subtree(monkeyp
assert seen["vectors"] == ["viking://user/default/memories"]
[email protected]("wait", [True, False])
+ "uri",
+ [
+ "viking://",
+ "viking://user",
+ "viking://user/alice",
+ "viking://user/alice/skills",
+ "viking://agent/skills",
+ ],
+)
+async def test_reindex_rejects_non_recursive_namespace_before_starting_work(monkeypatch, uri, wait):
+ from openviking.service.reindex_executor import ReindexExecutor
+ from openviking_cli.exceptions import InvalidArgumentError
+
+ def unexpected_tracker():
+ pytest.fail("unsupported non-recursive reindex must not start task tracking")
+
+ monkeypatch.setattr("openviking.service.reindex_executor.get_task_tracker", unexpected_tracker)
+ ctx = RequestContext(
+ user=UserIdentifier(account_id="test", user_id="alice"),
+ role=Role(Role.ROOT),
+ )
+ with pytest.raises(InvalidArgumentError, match="recursive=false.*namespace"):
+ await ReindexExecutor().execute(
+ uri=uri,
+ mode="semantic_and_vectors",
+ recursive=False,
+ wait=wait,
+ ctx=ctx,
+ )
+
+
@pytest.mark.asyncio
async def test_reindex_resource_non_recursive_limits_semantics_and_vectors(monkeypatch):
from openviking.service.reindex_executor import ReindexExecutor, _ReindexCounters