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
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.mdindex 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 fileawait 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 sourceoptions={"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.mdindex 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.pyindex 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.pyindex 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. Adeclared request never degrades to the standard pipeline andrequires 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 resourceinstruction: Processing instruction for semantic extractionwait: Whether to wait for semantic extraction and vectorization to complete