Skip to content

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

docs: say what to and parent do on collision, and fix the FAQ example (#4556)

Zayn Jarvis5834eb6dea0b
diff --git a/docs/en/faq/faq.md b/docs/en/faq/faq.md
index 45bc9dd21..3c632837e 100644
--- a/docs/en/faq/faq.md
+++ b/docs/en/faq/faq.md
@@ -170,7 +170,7 @@ Embedding, VLM, storage, and other service configuration is managed by the OpenV
# Add single file
await client.add_resource(
path="./document.pdf",
- to="viking://resources/docs/", # Specify storage location
+ parent="viking://resources/docs", # Store under this directory; the name comes from the source
options={"reason": "Project technical documentation"}, # Describe resource purpose to improve retrieval quality
)
@@ -184,6 +184,29 @@ await client.add_resource(
await client.wait_processed()
```
+### What is the difference between `to` and `parent`? Which should I use?
+
+| | `to` | `parent` |
+|---|---|---|
+| What you pass | The exact final URI, **including the leaf name** | An **existing directory**; the leaf name comes from the source |
+| On a name collision | No renaming. An existing target is synced to the new source, so visible entries the source does not contain are deleted | Never overwrites. Falls back to `name_1`, `name_2`, … and returns a warning |
+| When to use it | The final name is known and must be honored verbatim, or you want to update an existing resource in place | The leaf name is derived server-side (URL / repository imports, split documents), or nothing already at the destination may be touched |
+
+Leaving both empty derives the directory and the leaf name from the source, with the same collision handling as `parent`.
+
+`to` and `parent` cannot be combined; passing both is an error.
+
+### What happens when `to` points at an existing directory?
+
+The content is synced to match the new source and the metadata is kept:
+
+- **Dot-prefixed entries survive untouched** — `.abstract.md`, `.overview.md`, `.search_tags.json`, `.image_mappings.json` and friends. The sync enumerates neither side's dotfiles, so they are neither deleted nor overwritten.
+- **Everything else visible is aligned with the source** — entries the source does not contain are deleted, changed ones are overwritten, unchanged ones stay in place and keep their URI, vectors and tags.
+
+So this preserves metadata and replaces the content itself; it is not a delete-and-recreate. Use `parent` when nothing already at the destination may be touched.
+
+Note: `processing_mode="vectors_only"` skips semantic processing, so the surviving `.abstract.md` / `.overview.md` are **not** regenerated and keep describing the content that was just replaced. Use the default `semantic_and_vectors` when summaries must follow the content.
+
### What's the difference between `find()` and `search()`? Which should I use?
| Feature | `find()` | `search()` |
diff --git a/docs/zh/faq/faq.md b/docs/zh/faq/faq.md
index ada8153c2..c62fe8d99 100644
--- a/docs/zh/faq/faq.md
+++ b/docs/zh/faq/faq.md
@@ -163,7 +163,7 @@ Embedding、VLM、存储等服务配置由 OpenViking Server 通过 `ov.conf`
# 添加单个文件
await client.add_resource(
path="./document.pdf",
- to="viking://resources/docs/", # 指定存储位置
+ parent="viking://resources/docs", # 存到这个目录下面,文件名由来源决定
options={"reason": "项目技术文档"}, # 描述资源用途,提升检索质量
)
@@ -177,6 +177,29 @@ await client.add_resource(
await client.wait_processed()
```
+### `to` 和 `parent` 有什么区别?该用哪个?
+
+| | `to` | `parent` |
+|---|---|---|
+| 传什么 | 完整最终 URI,**含叶子名** | 一个**已存在的目录**,叶子名由来源决定 |
+| 撞名怎么办 | 不改名。目标已存在时按新来源同步,来源里没有的可见条目会被删除 | 不覆盖。退到 `name_1`、`name_2`……并返回一条 warning |
+| 什么时候用 | 名字已知且必须逐字生效;或者要原地更新一个已有资源 | 叶子名由服务端派生(URL / 仓库导入、大文件切分),或者目标下已有的内容一点都不能动 |
+
+两个都留空 = 目录和叶子名都从来源推导,撞名行为同 `parent`。
+
+`to` 和 `parent` 不能同时传,会直接报错。
+
+### `to` 指到一个已存在的目录会发生什么?
+
+内容被同步成新来源的样子,metadata 保留。具体是:
+
+- **点号开头的条目原样保留** —— `.abstract.md`、`.overview.md`、`.search_tags.json`、`.image_mappings.json` 等;同步时两侧都不枚举它们,所以既不会被删也不会被覆盖。
+- **其余可见内容和新来源对齐** —— 来源里没有的删掉,变了的覆盖,没变的留在原地(URI 不变,挂在上面的向量和 tags 都还在)。
+
+所以这是「保留 metadata、替换内容本身」,不是把目录删掉重建。不想动目标里已有的东西就用 `parent`。
+
+注意:`processing_mode="vectors_only"` 不跑语义处理,保留下来的 `.abstract.md` / `.overview.md` **不会重算**,会继续描述已经被替换掉的旧内容。需要摘要跟着更新,就用默认的 `semantic_and_vectors`。
+
### `find()` 和 `search()` 有什么区别?应该用哪个?
| 特性 | `find()` | `search()` |
diff --git a/openviking/server/mcp_endpoint.py b/openviking/server/mcp_endpoint.py
index 3feb968ec..45646dc55 100644
--- a/openviking/server/mcp_endpoint.py
+++ b/openviking/server/mcp_endpoint.py
@@ -969,11 +969,16 @@ async def add_resource(
Only applies to remote-URL invocations.
processing_mode: "semantic_and_vectors" for normal semantic processing, or
"vectors_only" to skip semantic understanding and only build vector indexes.
- to: Target URI under viking://resources/ (e.g. "viking://resources/volcengine/OpenViking").
- Required when ``add_type`` is set; otherwise leave empty to derive a URI
- from the source.
- parent: Parent URI under viking://resources/ for remote or local-file imports.
- Mutually exclusive with ``to`` and not supported when ``add_type`` is set.
+ to: Exact final URI including the leaf name (e.g.
+ "viking://resources/volcengine/OpenViking"). Written verbatim; an existing
+ target is synced to match the new source, so visible entries it does not
+ contain are deleted. Required when ``add_type`` is set.
+ parent: Existing directory to store the resource under, for remote or
+ local-file imports; the leaf name comes from the source. Never overwrites
+ — a collision reserves the next free name ("name_1", "name_2", ...) and
+ returns a warning. Mutually exclusive with ``to``; not supported when
+ ``add_type`` is set. Leaving both empty derives the directory and the name
+ from the source and handles collisions like ``parent``.
tags: Optional explicit k=v retrieval tags to apply after ingestion.
tag_mode: Tag update mode, "replace" or "append". Defaults to "replace".
args: Parser-specific options, e.g. {"auth_config": {"token": "..."}}
diff --git a/openviking/service/resource_service.py b/openviking/service/resource_service.py
index 0d455a28e..9d644476c 100644
--- a/openviking/service/resource_service.py
+++ b/openviking/service/resource_service.py
@@ -1417,10 +1417,16 @@ class ResourceService:
the type must be enabled in connector.allowed_add_types. A
declared request never degrades to the standard pipeline and
requires an exact ``to`` target.
- to: Target URI (e.g., "viking://resources/my_resource"). Required
- when ``add_type`` is set.
- parent: Parent URI under which the resource will be stored. Not
- supported when ``add_type`` is set.
+ to: Exact final URI including the leaf name (e.g.,
+ "viking://resources/my_resource"). Written verbatim; an existing
+ target is synced to match the new source, so visible entries it does
+ not contain are deleted. Required when ``add_type`` is set.
+ parent: Existing directory to store the resource under; the leaf name
+ comes from the source. Never overwrites — a collision reserves the
+ next free name ("name_1", "name_2", ...) and returns a warning.
+ Mutually exclusive with ``to`` and not supported when ``add_type``
+ is set. Leaving both empty derives the directory and the name from
+ the source and handles collisions like ``parent``.
reason: Reason for adding the resource
instruction: Processing instruction for semantic extraction
wait: Whether to wait for semantic extraction and vectorization to complete