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(migration): sync legacy agent_id behavior after #2839 (#2861)
Evof181b2bdd11c
diff --git a/docs/en/migration/01-user-peer-model.md b/docs/en/migration/01-user-peer-model.mdindex 509583c52..011b0f426 100644--- a/docs/en/migration/01-user-peer-model.md+++ b/docs/en/migration/01-user-peer-model.md@@ -13,10 +13,10 @@ If you stay on 0.3.x, existing `agent_id`, `viking://agent/...`, and `viking://sIf you upgrade to 0.4.0, you do not need to migrate data immediately. 0.4.0 keeps runtime compatibility so old data remains readable:-- `agent_id` can still be configured temporarily, and maps to request-level `actor_peer_id`.+- `agent_id` can still be configured temporarily. In current HTTP SDK clients it maps to request-level `actor_peer_id`; true legacy agent mode is selected only when requests send `X-OpenViking-Agent`.- `viking://agent/...` can still read old agent data, but is read-only.- `viking://session/...` can still read old session data and merges with the new session view.-- In legacy `agent_id` mode, `find` / `search` search both new peer data and unmigrated legacy agent data.+- `find` / `search` read unmigrated legacy agent data only for true legacy requests that still send `X-OpenViking-Agent`; HTTP SDK `agent_id` now selects only the actor peer view.Recommended order:@@ -74,17 +74,17 @@ The `viking://session` merged compatibility view is implemented on the server. U| Legacy usage | 0.4.0 behavior || --- | --- |-| Client config `agent_id` | Supported. It maps to request-level `actor_peer_id` and marks the request as legacy agent mode. |+| Client config `agent_id` | Supported. In current HTTP SDK clients it maps to request-level `actor_peer_id`; it no longer triggers legacy agent mode by itself. || `ov ls viking://agent` | Supported for reads. If `agent_id` / `actor_peer_id` is set, only the current actor peer's legacy agent is shown. || Read `viking://agent/<agent_id>/...` | Supported for old data. || Write `viking://agent/...` | Not supported. New writes should go to `viking://user/<user_id>/peers/<peer_id>/...`. || `ov ls viking://session` | Supported for reads. It merges new and old sessions. || Read `viking://session/<session_id>/...` | Supported. New path first, legacy path as fallback. || Write `viking://session/...` | Not supported. New sessions are written to `viking://user/<user_id>/sessions/...`. |-| `find` / `search` with `agent_id` | Supported. It searches both new peer data and old agent data. |+| `find` / `search` with HTTP SDK `agent_id` | Supported. It searches the selected actor peer view only; old agent data is searched only by true legacy requests that send `X-OpenViking-Agent`. || `find` / `search` body `peer_id` | Not supported. Use `actor_peer_id` or `X-OpenViking-Actor-Peer` for the new peer view. || Configure both `actor_peer_id` and `agent_id` | Not supported. The client/request fails. |-| Explicit message `peer_id` while using legacy `agent_id` client | Not supported. The request fails. |+| Explicit message `peer_id` while using HTTP SDK `agent_id` | Supported. The explicit message `peer_id` wins for that message; legacy fallback applies only when no message `peer_id` is provided. || `role_id` memory isolation | Not supported. It is ignored after upgrade. |## Run Migration@@ -277,7 +277,7 @@ viking://user/alice/sessions/sess-001/messages.jsonl### find / search-During the migration window, if you still need unmigrated old agent data, keep using:+During the migration window, if you still need unmigrated old agent data, use a true legacy request path that sends `X-OpenViking-Agent`. Current HTTP SDK `agent_id` is an actor-peer alias and no longer makes `find` / `search` include old agent data:```json{@@ -286,11 +286,11 @@ During the migration window, if you still need unmigrated old agent data, keep u}```-After migration, when old agent data is no longer needed, move to client/request-level `actor_peer_id`.+After migration, when old agent data is no longer needed, move all clients to client/request-level `actor_peer_id`.### Session Messages-A legacy `agent_id` client automatically attaches `agent_id` to assistant messages. After moving to the new usage, do not rely on `agent_id`; use message `peer_id` when you need to attribute a message speaker.+A legacy request without an explicit assistant-message `peer_id` can still fall back to its legacy agent id. Current HTTP SDK clients should not rely on `agent_id` for message attribution; use message `peer_id` when you need to identify the speaker.## Deferring Data Migration@@ -298,7 +298,7 @@ It is acceptable as a short-term transition, with these limits:- Old agent/session data is readable, but legacy namespaces are not writable.- New sessions and new resources are written to the new namespace, so data can exist in both old and new paths for a while.-- Legacy `agent_id` retrieval searches both old and new data; pure `actor_peer_id` does not search old `viking://agent` by default.+- True legacy retrieval searches both old and new data when the request sends `X-OpenViking-Agent`; HTTP SDK `agent_id` and pure `actor_peer_id` do not search old `viking://agent` by default.- In multi-user accounts, old sessions without clear owner metadata may be readable at runtime but will fail formal migration preflight.- Legacy directories and old vector records remain until cleanup.diff --git a/docs/zh/migration/01-user-peer-model.md b/docs/zh/migration/01-user-peer-model.mdindex 64ec0c80b..8c9180fd1 100644--- a/docs/zh/migration/01-user-peer-model.md+++ b/docs/zh/migration/01-user-peer-model.md@@ -13,10 +13,10 @@如果升级到 0.4.0,可以先不迁移数据。0.4.0 提供运行期兼容,旧数据不会因为升级立即不可读:-- `agent_id` 仍可临时配置,会映射成 `actor_peer_id`。+- `agent_id` 仍可临时配置。当前 HTTP SDK client 会把它映射成请求级 `actor_peer_id`;只有仍发送 `X-OpenViking-Agent` 的请求才进入真正的 legacy agent 模式。- `viking://agent/...` 仍可读旧 agent 数据,但只读。- `viking://session/...` 仍可读旧 session 数据,并会合并新 session 视图。-- legacy `agent_id` 模式下,`find` / `search` 会同时查新 peer 数据和未迁移的旧 agent 数据。+- 只有真正发送 `X-OpenViking-Agent` 的 legacy 请求会让 `find` / `search` 同时查未迁移的旧 agent 数据;HTTP SDK `agent_id` 现在只选择 actor peer 视图。推荐顺序:@@ -74,17 +74,17 @@ ov session list| 旧用法 | 0.4.0 行为 || --- | --- |-| client 配置 `agent_id` | 支持,映射成请求级 `actor_peer_id`,并标记为 legacy agent 模式。 |+| client 配置 `agent_id` | 支持。当前 HTTP SDK client 会映射成请求级 `actor_peer_id`;它本身不再触发 legacy agent 模式。 || `ov ls viking://agent` | 支持读;如果设置了 `agent_id` / `actor_peer_id`,只显示当前 actor peer 对应的 legacy agent。 || 读 `viking://agent/<agent_id>/...` | 支持读旧数据。 || 写 `viking://agent/...` | 不支持。新写入应进入 `viking://user/<user_id>/peers/<peer_id>/...`。 || `ov ls viking://session` | 支持读,会合并新 session 和旧 session。 || 读 `viking://session/<session_id>/...` | 支持读,按新路径优先、旧路径兜底。 || 写 `viking://session/...` | 不支持。新 session 写入 `viking://user/<user_id>/sessions/...`。 |-| `find` / `search` 传 `agent_id` | 支持,会同时查新 peer 数据和旧 agent 数据。 |+| HTTP SDK `find` / `search` 传 `agent_id` | 支持,只查选中的 actor peer 视图;只有发送 `X-OpenViking-Agent` 的真正 legacy 请求才会查旧 agent 数据。 || `find` / `search` body 传旧 `peer_id` | 不支持。新 peer 视图使用 `actor_peer_id` 或 `X-OpenViking-Actor-Peer`。 || 同时配置 `actor_peer_id` 和 `agent_id` | 不支持,会报错。 |-| legacy `agent_id` client 下显式传 message `peer_id` | 不支持,会报错。 |+| HTTP SDK `agent_id` client 下显式传 message `peer_id` | 支持。该 message 使用显式 `peer_id`;只有没有 message `peer_id` 时才走 legacy fallback。 || `role_id` 记忆隔离 | 不再支持,升级后忽略。 |## 执行数据迁移@@ -277,7 +277,7 @@ viking://user/alice/sessions/sess-001/messages.jsonl### find / search-迁移窗口内,如果还需要读取未迁移的旧 agent 数据,可以继续传:+迁移窗口内,如果还需要读取未迁移的旧 agent 数据,需要使用仍发送 `X-OpenViking-Agent` 的真正 legacy 请求路径。当前 HTTP SDK `agent_id` 是 actor-peer alias,不再让 `find` / `search` 包含旧 agent 数据:```json{@@ -286,11 +286,11 @@ viking://user/alice/sessions/sess-001/messages.jsonl}```-迁移完成并确认不再需要旧 agent 数据后,改为 client/request 级 `actor_peer_id`。+迁移完成并确认不再需要旧 agent 数据后,所有 client 都改为 client/request 级 `actor_peer_id`。### 会话消息-legacy `agent_id` client 会自动给 assistant message 带 `agent_id`。迁移到新用法后,不要再依赖 `agent_id`;需要表达消息说话人时使用 message `peer_id`。+没有显式 assistant message `peer_id` 的 legacy 请求仍可 fallback 到 legacy agent id。当前 HTTP SDK client 不应再依赖 `agent_id` 做消息归属;需要表达说话人时使用 message `peer_id`。## 暂不迁移数据@@ -298,7 +298,7 @@ legacy `agent_id` client 会自动给 assistant message 带 `agent_id`。迁移- 旧 agent/session 数据可读,但旧 namespace 不可写。- 新 session 和新资源会写入新 namespace,数据会在新旧路径并存一段时间。-- legacy `agent_id` 检索会同时查新旧数据;纯 `actor_peer_id` 不会默认查旧 `viking://agent`。+- 发送 `X-OpenViking-Agent` 的真正 legacy 检索会同时查新旧数据;HTTP SDK `agent_id` 和纯 `actor_peer_id` 不会默认查旧 `viking://agent`。- 多用户 account 下 owner 不明确的旧 session,运行期可能可读,但正式迁移会被 preflight 拦截。- cleanup 之前旧目录和旧向量记录仍会保留。