Skip to content

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

docs(api): add documentation for incremental update feature (#886)

yepperc1480dd50027
diff --git a/docs/en/api/02-resources.md b/docs/en/api/02-resources.md
index e7db29313..a9ab82888 100644
--- a/docs/en/api/02-resources.md
+++ b/docs/en/api/02-resources.md
@@ -47,6 +47,18 @@ Add a resource to the knowledge base.
| timeout | float | No | None | Timeout in seconds (only used when wait=True) |
| watch_interval | float | No | 0 | Watch interval (minutes). >0 enables/updates watch; <=0 disables watch. Only takes effect when target is provided |
+**Incremental Updates**
+
+When you call `add_resource()` repeatedly for the same resource URI, the system performs an incremental update instead of rebuilding everything from scratch:
+
+- **Trigger**: `target` is provided and already exists in the knowledge base.
+- **High-level idea**: each ingestion first builds a temporary resource tree from the new input. During asynchronous semantic processing, the temporary tree is compared against the existing tree at `target`, and only the changed parts are re-processed and synchronized.
+- **Incremental behavior in the semantic stage**:
+ - **Unchanged files**: reuse existing L0 summaries and vector index records; skip vectorization.
+ - **Changed files**: regenerate summaries and vector index entries.
+ - **Directory-level L0/L1 (abstract/overview)**: if the child set and their change status are unchanged, reuse existing results and skip vectorization; otherwise recompute and update.
+- **Filesystem + index sync**: after the semantic DAG finishes, a top-down diff is applied from the temporary tree to `target` to synchronize additions, deletions, and updates. Vector store records are kept consistent: deletions remove corresponding vectors, while moves/overwrites update vector records’ URI mapping, completing an incremental update of both the resource tree and the semantic index.
+
**Python SDK (Embedded / HTTP)**
```python
diff --git a/docs/zh/api/02-resources.md b/docs/zh/api/02-resources.md
index fdcf201be..452ac9849 100644
--- a/docs/zh/api/02-resources.md
+++ b/docs/zh/api/02-resources.md
@@ -47,6 +47,18 @@ Input -> Parser -> TreeBuilder -> AGFS -> SemanticQueue -> Vector Index
| timeout | float | 否 | None | 超时时间(秒),仅在 wait=True 时生效 |
| watch_interval | float | 否 | 0 | 定时更新间隔(分钟)。>0 开启/更新定时任务;<=0 关闭(停用)定时任务。仅在指定 target 时生效 |
+**增量更新(Incremental Update)**
+
+当你为同一个资源 URI 反复调用 `add_resource()` 时,系统会走“增量更新”而不是每次全量重建:
+
+- **触发条件**:请求里显式指定 `target`,且该 `target` 在知识库中已存在。
+- **总体思路**:每次导入都会先把新内容解析/构建成一棵“临时资源树”,随后在异步语义处理阶段,将临时树与 `target` 对应的现有资源树进行对比,只对发生变化的部分做重算与同步。
+- **语义阶段的增量**:
+ - 对**未变化的文件**:复用已有 L0(摘要)与向量索引记录,跳过向量化。
+ - 对**发生变化的文件**:重新生成摘要/向量索引。
+ - 对**目录级 L0/L1(abstract/overview)**:若目录下子项及其变更状态不变,则复用已有结果并跳过向量化;否则重算并更新。
+- **落盘与索引同步**:语义 DAG 结束后会对临时树与 `target` 做一次 top-down diff,同步三类变更:新增(添加新文件/目录)、删除(移除消失项)、更新(覆盖变化项)。同步过程中会同时联动更新向量库中的记录:删除项会删除对应向量记录;移动/覆盖会同步更新向量记录的 URI 映射,从而完成“文件树与向量索引的一致性增量更新”。
+
**Python SDK (Embedded / HTTP)**
```python