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: drop the 0.3.x migration guide and the OAuth proxy note (#5533)
Zayn Jarvis86abe9056f3c
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.tsindex d9350f599..7032c722e 100644--- a/docs/.vitepress/config.ts+++ b/docs/.vitepress/config.ts@@ -57,7 +57,7 @@ const navLabels = {const enNav: DefaultTheme.NavItem[] = [{ text: navLabels.en.start, link: '/en/getting-started/01-introduction', activeMatch: '/en/(getting-started|configuration|agent-integrations)/' },{ text: navLabels.en.concepts, link: '/en/concepts/01-architecture', activeMatch: '/en/concepts/' },- { text: navLabels.en.guide, link: '/en/guides/01-configuration', activeMatch: '/en/(guides|migration|context-compilation)/' },+ { text: navLabels.en.guide, link: '/en/guides/01-configuration', activeMatch: '/en/(guides|context-compilation)/' },{ text: navLabels.en.api, link: '/en/api/01-overview', activeMatch: '/en/api/' },{ text: navLabels.en.faq, link: '/en/faq/faq', activeMatch: '/en/faq/' },{ text: navLabels.en.about, link: '/en/about/01-about-us', activeMatch: '/en/about/' }@@ -66,7 +66,7 @@ const enNav: DefaultTheme.NavItem[] = [const zhNav: DefaultTheme.NavItem[] = [{ text: navLabels.zh.start, link: '/zh/getting-started/01-introduction', activeMatch: '/zh/(getting-started|configuration|agent-integrations)/' },{ text: navLabels.zh.concepts, link: '/zh/concepts/01-architecture', activeMatch: '/zh/concepts/' },- { text: navLabels.zh.guide, link: '/zh/guides/01-configuration', activeMatch: '/zh/(guides|migration|context-compilation)/' },+ { text: navLabels.zh.guide, link: '/zh/guides/01-configuration', activeMatch: '/zh/(guides|context-compilation)/' },{ text: navLabels.zh.api, link: '/zh/api/01-overview', activeMatch: '/zh/api/' },{ text: navLabels.zh.faq, link: '/zh/faq/faq', activeMatch: '/zh/faq/' },{ text: navLabels.zh.about, link: '/zh/about/01-about-us', activeMatch: '/zh/about/' }@@ -309,10 +309,9 @@ export default defineConfig({'/en/getting-started/': localizedGroupedSidebarItems('en', ['getting-started', 'configuration', 'agent-integrations']),'/en/configuration/': localizedGroupedSidebarItems('en', ['getting-started', 'configuration', 'agent-integrations']),'/en/concepts/': localizedSectionSidebarItems('en', 'concepts'),- '/en/guides/': localizedGroupedSidebarItems('en', ['guides', 'migration']),+ '/en/guides/': localizedGroupedSidebarItems('en', ['guides']),'/en/agent-integrations/': localizedGroupedSidebarItems('en', ['getting-started', 'configuration', 'agent-integrations']),- '/en/context-compilation/': localizedGroupedSidebarItems('en', ['guides', 'migration']),- '/en/migration/': localizedGroupedSidebarItems('en', ['guides', 'migration']),+ '/en/context-compilation/': localizedGroupedSidebarItems('en', ['guides']),'/en/api/': localizedReferenceSidebarItems('en'),'/en/faq/': [sidebarSection('en/faq', 'FAQ', false)],'/en/about/': localizedAboutSidebarItems('en'),@@ -333,10 +332,9 @@ export default defineConfig({'/zh/getting-started/': localizedGroupedSidebarItems('zh', ['getting-started', 'configuration', 'agent-integrations']),'/zh/configuration/': localizedGroupedSidebarItems('zh', ['getting-started', 'configuration', 'agent-integrations']),'/zh/concepts/': localizedSectionSidebarItems('zh', 'concepts'),- '/zh/guides/': localizedGroupedSidebarItems('zh', ['guides', 'migration']),+ '/zh/guides/': localizedGroupedSidebarItems('zh', ['guides']),'/zh/agent-integrations/': localizedGroupedSidebarItems('zh', ['getting-started', 'configuration', 'agent-integrations']),- '/zh/context-compilation/': localizedGroupedSidebarItems('zh', ['guides', 'migration']),- '/zh/migration/': localizedGroupedSidebarItems('zh', ['guides', 'migration']),+ '/zh/context-compilation/': localizedGroupedSidebarItems('zh', ['guides']),'/zh/api/': localizedReferenceSidebarItems('zh'),'/zh/faq/': [sidebarSection('zh/faq', '常见问题', false)],'/zh/about/': localizedAboutSidebarItems('zh')diff --git a/docs/.vitepress/docs-navigation.ts b/docs/.vitepress/docs-navigation.tsindex 7b2d4157d..4afc995e9 100644--- a/docs/.vitepress/docs-navigation.ts+++ b/docs/.vitepress/docs-navigation.ts@@ -11,7 +11,6 @@ const sectionNames: Record<string, string> = {guides: 'Guides','agent-integrations': 'Agent Integrations','context-compilation': 'Context Compilation',- migration: 'Migration',api: 'API Reference',faq: 'FAQ',about: 'About',@@ -25,7 +24,6 @@ const zhSectionNames: Record<string, string> = {guides: '指南','agent-integrations': 'Agent 集成','context-compilation': '上下文编译',- migration: '迁移指南',api: 'API 参考',faq: '常见问题',about: '关于',@@ -614,30 +612,12 @@ function guidesSection(return section}-function migrationSection(- locale: 'en' | 'zh',- title: string,- collapsed = true-): DefaultTheme.SidebarItem {- return {- text: title,- collapsed,- items: [- {- text: '0.3.x → 0.4.0',- link: linkFor(path.join(docsRoot, locale, 'migration', '01-user-peer-model.md'))- }- ]- }-}-type LocalizedSidebarSection =| 'getting-started'| 'configuration'| 'concepts'| 'guides'| 'agent-integrations'- | 'migration'type LocalizedSidebarSectionBuilder = (locale: 'en' | 'zh',@@ -654,8 +634,7 @@ const localizedSidebarSectionBuilders: Record<sidebarSection(`${locale}/configuration`, title, collapsed),concepts: conceptsSection,guides: guidesSection,- 'agent-integrations': agentIntegrationSection,- migration: migrationSection+ 'agent-integrations': agentIntegrationSection}function localizedSidebarSection(@@ -707,7 +686,7 @@ export function documentationSections(locale: 'en' | 'zh') {return [...localizedGroupedSidebarItems(locale, ['getting-started', 'configuration', 'agent-integrations']),...localizedSectionSidebarItems(locale, 'concepts'),- ...localizedGroupedSidebarItems(locale, ['guides', 'migration']),+ ...localizedGroupedSidebarItems(locale, ['guides']),...localizedReferenceSidebarItems(locale),sidebarSection(`${locale}/faq`, labels.faq, false),...localizedAboutSidebarItems(locale)diff --git a/docs/.vitepress/theme/docs-sections.ts b/docs/.vitepress/theme/docs-sections.tsindex f08d82170..ae8738808 100644--- a/docs/.vitepress/theme/docs-sections.ts+++ b/docs/.vitepress/theme/docs-sections.ts@@ -5,7 +5,6 @@ export const sections = [{ id: 'agent-integrations', en: 'Agent Integrations', zh: 'Agent 集成', enNote: 'Give your agent memory across sessions.', zhNote: '让 Agent 在不同会话之间保留记忆。' },{ id: 'concepts', en: 'Concepts', zh: '核心概念', enNote: 'Understand the filesystem behind the context.', zhNote: '理解上下文背后的文件系统。' },{ id: 'guides', en: 'Guides', zh: '指南', enNote: 'Configure, deploy, and observe your service.', zhNote: '配置、部署和监控服务。' },- { id: 'migration', en: 'Migration', zh: '迁移指南', enNote: 'Move an existing installation forward.', zhNote: '升级现有部署。' },{ id: 'api', en: 'API Reference', zh: 'API 参考', enNote: 'Resources, memory, retrieval, and administration.', zhNote: '资源、记忆、检索和管理接口。' },{ id: 'faq', en: 'FAQ', zh: '常见问题', enNote: 'Find answers when something gets in the way.', zhNote: '查找问题和解决办法。' },{ id: 'about', en: 'About', zh: '关于', enNote: 'Changelog, roadmap, and ways to contribute.', zhNote: '更新日志、路线图和参与方式。' }diff --git a/docs/en/guides/06-mcp-integration.md b/docs/en/guides/06-mcp-integration.mdindex 771ee2bdb..8f007bd7d 100644--- a/docs/en/guides/06-mcp-integration.md+++ b/docs/en/guides/06-mcp-integration.md@@ -119,9 +119,6 @@ Enable `oauth.enabled` on the server and configure HTTPS as described in the OAu- `OPENVIKING_PUBLIC_BASE_URL` and the `oauth` config block- Token model (`ovat_` / `ovrt_` / `ovac_` prefixes) and revocation-> The community [MCP-Key2OAuth](https://github.com/t0saki/MCP-Key2OAuth)-> Cloudflare Worker proxy is a separate third-party project. The native flow above needs no extra deployment unit and does not pass your API key through a third party; deployments choosing the proxy should review its configuration and credential handling.-## Available MCP Toolsdiff --git a/docs/en/guides/21-private-operations.md b/docs/en/guides/21-private-operations.mdindex fe9fe763e..ca9c81d72 100644--- a/docs/en/guides/21-private-operations.md+++ b/docs/en/guides/21-private-operations.md@@ -4,7 +4,7 @@ description: Apply private-delivery configuration changes, prepare upgrades and# Enterprise Deployment: Upgrades and Troubleshooting-Use ovadmin and Operators to update configuration, upgrade, and troubleshoot your [Enterprise Deployment](20-private-deployment.md). For open-source container updates, see [server deployment](03-deployment.md); for OpenViking data-model migration, see the [migration guide](../migration/01-user-peer-model.md). Check delivery and runtime versions separately.+Use ovadmin and Operators to update configuration, upgrade, and troubleshoot your [Enterprise Deployment](20-private-deployment.md). For open-source container updates, see [server deployment](03-deployment.md). Check delivery and runtime versions separately.## Applying configuration changesdiff --git a/docs/en/migration/01-user-peer-model.md b/docs/en/migration/01-user-peer-model.mddeleted file mode 100644index 535df0859..000000000--- a/docs/en/migration/01-user-peer-model.md+++ /dev/null@@ -1,364 +0,0 @@-# OpenViking 0.3.x to 0.4.0 Upgrade Guide--> **Version scope:** This page documents the historical 0.3.x-to-0.4.0 migration. Its Agent directory compatibility and migration instructions do not apply to current versions. `viking://agent/...` now denotes account-shared directories; Agent ID path compatibility, migration, and cleanup have been removed. The current `admin migrate` command handles legacy sessions only.--For current deployments, use [Administration API](../api/08-admin.md). Keep the source installation and its backup available until the historical migration has been verified; these commands are not a direct upgrade path from 0.3.x to the latest release.--This guide is for users already running OpenViking 0.3.x. It explains what to do before and after upgrading to 0.4.0, which legacy usage remains compatible, how to migrate data, and how to move application code to the new model.--## Upgrade Decision--If you stay on 0.3.x, existing `agent_id`, `viking://agent/...`, and `viking://session/...` behavior does not change. But you also cannot use the 0.4.0 model and tools:--- No User / Peer data model.-- No legacy agent/session migration or cleanup command.-- No request-level `actor_peer_id` peer view.-- Future fixes and features around the new model are not backported to the old model.--If 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. In current HTTP SDK clients it maps to request-level `actor_peer_id`.-- `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.--Recommended order:--```text-Back up- -> Upgrade server / CLI / SDK- -> Verify old data is still readable- -> Run data migration- -> Verify new paths- -> Gradually update application usage- -> Optionally run cleanup-```--## Back Up First--Create a backup with a 0.3.x-compatible package. `0.3.24` is recommended:--```bash-pip install openviking==0.3.24 --upgrade --force-reinstall-ov backup ./backups/openviking-before-0.4.0.ovpack-```--Check the current version:--```bash-python -c "import openviking; print(openviking.__version__)"-ov version-```--Do not run `ov --sudo admin migrate` on 0.3.x. The migration command is only available in 0.4.0 or later.--## Upgrade Server and Clients--Install 0.4.0, restart the server, and make sure CLI / SDK clients are on the same version line:--```bash-pip install openviking==0.4.0 --upgrade --force-reinstall-openviking-server --config ov.conf-```--If you use the Rust `ov` CLI from the repository, rebuild or reinstall it. Otherwise the `ov` binary on PATH may still be the old one.--After upgrading, validate config and legacy reads:--```bash-ov config validate-ov ls viking://agent-ov ls viking://session-ov session list-```--The `viking://session` merged compatibility view is implemented on the server. Upgrading only the CLI does not change server-side reads.--## Compatibility Matrix--| Legacy usage | 0.4.0 behavior |-| --- | --- |-| 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 HTTP SDK `agent_id` | Supported. It searches the selected actor peer view only and does not automatically search unmigrated agent data. |-| `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 HTTP SDK `agent_id` | Supported. The message uses the explicit `peer_id`; no identity is inferred from `agent_id` when it is omitted. |-| `role_id` memory isolation | Not supported. It is ignored after upgrade. |--## Run Migration--After confirming that legacy data is readable, run migration:--```bash-ov --sudo admin migrate --output json-```--The response returns a task id:--```json-{- "task_id": "..."-}-```--Check task status:--```bash-ov --sudo task status <task_id>-ov --sudo task list --task-type legacy_migration-```--HTTP API:--```http-POST /api/v1/admin/migrate-X-API-Key: <root-key>-```--The request body can be empty. It is equivalent to:--```json-{- "action": "migrate"-}-```--Query the task:--```http-GET /api/v1/tasks/{task_id}-X-API-Key: <root-key>-```--ROOT can query migration tasks without normal account/user filtering. Migration creates one root-level task for the whole storage, not one task per account.--## Migration Rules--0.4.0 uses the User / Peer model:--```text-User = natural person or business user-Peer = interaction identity under a User-Session = conversation state under a User-Skill = executable skill under a User-```--Migration targets:--| Legacy data | New location |-| --- | --- |-| `viking://agent/<agent_id>/memories/...` | `viking://user/<user_id>/peers/<agent_id>/memories/...` |-| `viking://agent/<agent_id>/resources/...` | `viking://user/<user_id>/peers/<agent_id>/resources/...` |-| `viking://agent/<agent_id>/skills/<skill>/...` | `viking://user/<user_id>/skills/<skill>/...` |-| `viking://session/<session_id>/...` | `viking://user/<user_id>/sessions/<session_id>/...` |--Shared legacy agent data is copied into each target user's peer directory. If the legacy path already identifies a user owner, it is migrated only to that user.--Migration also handles existing vector records: for memory / resource / skill files or directories that were actually copied, it reads the old record's `vector` / `sparse_vector` and scalar fields, rewrites the URI, and writes a new record. Migration does not re-embed content and does not automatically call `reindex`. When shared legacy agent data is copied to multiple users, vector records are copied once per target user URI.--Old scalar-only records without a vector payload are skipped and counted in `migrated.skipped_vector_records`. Session migration copies file state only and does not handle vector records.--Session owner is resolved in this order:--1. `.meta.json.created_by_user_id`-2. `.meta.json.user_id`, `.meta.json.owner_user_id`, or `.meta.json.created_by`-3. A user hint in the legacy path, such as `/session/alice/sess-001`-4. The only registered user in a single-user account--In a multi-user account, a legacy session without an identifiable owner fails preflight. Runtime compatibility can keep that old session readable temporarily, but owner metadata should be fixed before migration.--Legacy agent instructions are not migrated:--```text-viking://agent/<agent_id>/instructions-```--Migration records a warning and does not create a replacement directory.--## Preflight Checks--Preflight fails before creating a task for:--- Legacy data under a physical account that is not present in the API key user registry.-- A legacy session in a multi-user account with no identifiable owner.-- A session owner that is present but is not a valid OpenViking user id.--Preflight records warnings or skips, then continues, for:--- A target user already has a skill with the same name. The legacy skill is skipped and the existing skill is not overwritten.-- Legacy agent instructions are found. Instructions are not migrated.-- A shared legacy agent exists but no target users exist in the account.--If migration finds legacy data owned by a user missing from the registry, it registers that user automatically. The task result records created users but does not return plaintext user keys.--If `api_key_hashing` is enabled, plaintext keys cannot be recovered from storage. Regenerate the key:--```bash-ov --sudo admin regenerate-key <account_id> <user_id>-```--## Verify Migration--Check the task result:--```bash-ov --sudo task status <task_id>-```--Review:--- `migrated.files` / `migrated.directories`-- `migrated.vector_records` / `migrated.skipped_vector_records`-- `migrated.operations`-- `skipped`-- `warnings`-- `created_users`--Verify new paths:--```bash-ov ls viking://user/<user_id>/peers/<agent_id>/memories-ov ls viking://user/<user_id>/skills-ov ls viking://user/<user_id>/sessions-```--Migration copies data and does not delete legacy paths or old vector records. Re-running it is idempotent: existing target files and skills are skipped instead of overwritten. If retrieval after migration is not as expected, run `reindex` manually on the new paths; the migration flow itself never triggers reindex.--## Application Migration--### Client Config--Legacy config can keep working during the migration window:--```json-{- "agent_id": "legacy-agent"-}-```--Recommended new config:--```json-{- "actor_peer_id": "legacy-agent"-}-```--Do not configure both:--```json-{- "actor_peer_id": "customer-a",- "agent_id": "legacy-agent"-}-```--This fails.--### File Paths--Legacy paths:--```text-viking://agent/code-agent/memories/profile.md-viking://session/sess-001/messages.jsonl-```--New paths:--```text-viking://user/alice/peers/code-agent/memories/profile.md-viking://user/alice/sessions/sess-001/messages.jsonl-```--`viking://session/<session_id>` can remain a read alias for the current user's session, but new writes and long-term references should use `viking://user/<user_id>/sessions/<session_id>`.--### find / search--`find` / `search` no longer accepts legacy agent identity fields and does not automatically include unmigrated agent data. Old `viking://agent/...` paths remain readable through content and filesystem APIs, but migrate them before using the new retrieval paths.--After migration, when old agent data is no longer needed, move all clients to client/request-level `actor_peer_id`.--### Session Messages--Session no longer derives message attribution from a legacy agent id. Use an explicit message `peer_id` whenever the speaker identity is required.--## Deferring Data Migration--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.-- `find` / `search` does not search old `viking://agent` data 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.--This is intended as a migration window, not a long-term state.--## Optional Cleanup--After verifying migration, delete legacy namespaces:--```bash-ov --sudo admin migrate --cleanup --output json-ov --sudo task status <cleanup_task_id>-```--HTTP request body:--```json-{- "action": "cleanup"-}-```--Cleanup deletes only:--```text-/local/<account>/agent-/local/<account>/session-/local/<account>/user/<user>/agent-```--Cleanup deletes old vector records under those legacy URI scopes before deleting the matching AGFS directories. If vector read or delete fails, that directory is skipped so files are not removed while stale index records remain. Cleanup does not delete files or vector records under the new user / peer paths.--It does not delete new model directories:--```text-/local/<account>/user/<user>/peers-/local/<account>/user/<user>/sessions-/local/<account>/user/<user>/skills-```--After cleanup, `viking://agent/...` is no longer the way to read migrated peer data. Use the new paths. `viking://session/...` can still be used as an alias for the current user's new sessions.--## FAQ--### ov ls viking://agent shows only one agent--If `agent_id` or `actor_peer_id` is configured, this is expected. The `viking://agent` root is filtered to the current actor peer.--### ov ls viking://session is still empty--Make sure the server has been restarted on 0.4.0. The `viking://session` merged read view runs on the server; upgrading only the CLI is not enough.--### Config has both actor_peer_id and agent_id--This is not allowed. Keep `agent_id` for legacy mode, or remove it and use `actor_peer_id`.--### Preflight reports an unknown account--The physical storage contains legacy data for an account missing from the API key registry. Restore or recreate that account before migrating.--### Preflight reports an unresolved session owner--Add owner metadata to the legacy session `.meta.json`, or move the session under a path that clearly identifies the owner, then run migration again.--### A skill did not migrate--Check the task `skipped` list. The usual reason is that the target user already had a skill with the same name. Migration does not overwrite existing skills.diff --git a/docs/zh/guides/06-mcp-integration.md b/docs/zh/guides/06-mcp-integration.mdindex f60d81072..736b3ac3f 100644--- a/docs/zh/guides/06-mcp-integration.md+++ b/docs/zh/guides/06-mcp-integration.md@@ -115,8 +115,6 @@ claude mcp add --transport http openviking \- `OPENVIKING_PUBLIC_BASE_URL` 与 `oauth` 配置项- Token 模型(`ovat_` / `ovrt_` / `ovac_` 前缀)与撤销-> 社区项目 [MCP-Key2OAuth](https://github.com/t0saki/MCP-Key2OAuth) Cloudflare Worker 代理是独立的第三方项目。上面的原生流程无需额外部署单元,也不会把 API Key 交给第三方;选择代理时,应单独核对其配置和凭证处理方式。-## 可用的 MCP 工具diff --git a/docs/zh/guides/21-private-operations.md b/docs/zh/guides/21-private-operations.mdindex e29f75629..65a6db796 100644--- a/docs/zh/guides/21-private-operations.md+++ b/docs/zh/guides/21-private-operations.md@@ -4,7 +4,7 @@ description: 私有交付的配置生效、升级验收、回滚准备和故障# 企业私有化部署:升级与排障-使用 ovadmin 和 Operator 维护[企业私有化部署](20-private-deployment.md),包括配置更新、版本升级和故障排查。开源服务的容器更新见[服务端部署](03-deployment.md),OpenViking 数据模型迁移见[迁移指南](../migration/01-user-peer-model.md)。交付包版本和 runtime 版本分别核对。+使用 ovadmin 和 Operator 维护[企业私有化部署](20-private-deployment.md),包括配置更新、版本升级和故障排查。开源服务的容器更新见[服务端部署](03-deployment.md)。交付包版本和 runtime 版本分别核对。## 配置修改如何生效diff --git a/docs/zh/migration/01-user-peer-model.md b/docs/zh/migration/01-user-peer-model.mddeleted file mode 100644index cfec68965..000000000--- a/docs/zh/migration/01-user-peer-model.md+++ /dev/null@@ -1,364 +0,0 @@-# OpenViking 0.3.x 到 0.4.0 升级指南--> **版本范围:** 本页记录 0.3.x 到 0.4.0 的历史迁移流程,不适用于当前版本的 Agent 目录。当前 `viking://agent/...` 统一表示账号内公共目录,已移除 Agent ID 路径兼容及其迁移、cleanup。当前 `admin migrate` 只处理旧 Session 数据。--当前部署请查阅[管理 API](../api/08-admin.md)中的旧数据迁移说明。历史迁移验证完成前,应保留原安装环境及其备份;本页命令不构成从 0.3.x 直接升级到最新版的流程。--本文面向已经运行 OpenViking 0.3.x 的用户,说明升级到 0.4.0 前后需要做什么、哪些旧用法仍然兼容、数据迁移如何执行,以及业务代码如何逐步迁移到新模型。--## 是否需要升级--如果继续停留在 0.3.x,现有 `agent_id`、`viking://agent/...`、`viking://session/...` 行为不会变化,但也无法使用 0.4.0 的能力:--- 没有 User / Peer 数据模型。-- 没有 legacy agent/session 数据迁移和 cleanup 命令。-- 没有 `actor_peer_id` 请求级 peer 视图。-- 后续围绕新模型的修复和能力不会回补到旧模型。--如果升级到 0.4.0,可以先不迁移数据。0.4.0 提供运行期兼容,旧数据不会因为升级立即不可读:--- `agent_id` 仍可临时配置。当前 HTTP SDK client 会把它映射成请求级 `actor_peer_id`。-- `viking://agent/...` 仍可读旧 agent 数据,但只读。-- `viking://session/...` 仍可读旧 session 数据,并会合并新 session 视图。--推荐顺序:--```text-备份- -> 升级 server / CLI / SDK- -> 验证旧数据仍可读- -> 执行数据迁移- -> 验证新路径- -> 逐步迁移业务用法- -> 可选 cleanup-```--## 升级前备份--先用 0.3.x 兼容版本创建备份。建议使用 `0.3.24`:--```bash-pip install openviking==0.3.24 --upgrade --force-reinstall-ov backup ./backups/openviking-before-0.4.0.ovpack-```--确认当前版本:--```bash-python -c "import openviking; print(openviking.__version__)"-ov version-```--不要在 0.3.x 上执行 `ov --sudo admin migrate`。迁移命令只在 0.4.0 或更新版本可用。--## 升级服务和客户端--安装 0.4.0,重启服务端,并确保 CLI / SDK 也升级到同一版本线:--```bash-pip install openviking==0.4.0 --upgrade --force-reinstall-openviking-server --config ov.conf-```--如果使用仓库内 Rust `ov` CLI,需要重新构建或安装 CLI;否则本地 `ov` 可能仍是旧二进制。--升级后先验证配置和旧数据读取:--```bash-ov config validate-ov ls viking://agent-ov ls viking://session-ov session list-```--`viking://session` 的兼容合并发生在服务端。只升级 CLI、不重启 server,不会改变服务端读取行为。--## 兼容性速查--| 旧用法 | 0.4.0 行为 |-| --- | --- |-| 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/...`。 |-| HTTP SDK `find` / `search` 传 `agent_id` | 支持,只查选中的 actor peer 视图,不会自动查未迁移的旧 agent 数据。 |-| `find` / `search` body 传旧 `peer_id` | 不支持。新 peer 视图使用 `actor_peer_id` 或 `X-OpenViking-Actor-Peer`。 |-| 同时配置 `actor_peer_id` 和 `agent_id` | 不支持,会报错。 |-| HTTP SDK `agent_id` client 下显式传 message `peer_id` | 支持。该 message 使用显式 `peer_id`;未提供时不会从 `agent_id` 推导。 |-| `role_id` 记忆隔离 | 不再支持,升级后忽略。 |--## 执行数据迁移--确认升级后旧数据可读,再执行迁移:--```bash-ov --sudo admin migrate --output json-```--响应会返回 task id:--```json-{- "task_id": "..."-}-```--查询任务:--```bash-ov --sudo task status <task_id>-ov --sudo task list --task-type legacy_migration-```--HTTP API:--```http-POST /api/v1/admin/migrate-X-API-Key: <root-key>-```--请求体可以为空,等价于:--```json-{- "action": "migrate"-}-```--查询任务:--```http-GET /api/v1/tasks/{task_id}-X-API-Key: <root-key>-```--ROOT 查询迁移任务时不会按普通 account/user 过滤。迁移会为整个存储创建一个 root 级别 task,不会按 account 分别创建 task。--## 迁移规则--0.4.0 的新模型是 User / Peer:--```text-User = 自然人或业务使用者-Peer = User 下的交互对象-Session = User 下的会话状态-Skill = User 下的可执行技能-```--迁移目标:--| 旧数据 | 新位置 |-| --- | --- |-| `viking://agent/<agent_id>/memories/...` | `viking://user/<user_id>/peers/<agent_id>/memories/...` |-| `viking://agent/<agent_id>/resources/...` | `viking://user/<user_id>/peers/<agent_id>/resources/...` |-| `viking://agent/<agent_id>/skills/<skill>/...` | `viking://user/<user_id>/skills/<skill>/...` |-| `viking://session/<session_id>/...` | `viking://user/<user_id>/sessions/<session_id>/...` |--共享 legacy agent 数据会复制到每个目标 user 的 peer 目录。如果旧路径已经表达了 user owner,只迁移到该 user。--迁移会一并处理已有向量索引:对实际复制成功的 memory / resource / skill 文件或目录,直接读取旧记录中的 `vector` / `sparse_vector` 和标量字段,重写 URI 后写入新记录。迁移不会重新向量化,也不会自动调用 `reindex`。共享 legacy agent 数据复制到多个 user 时,会按每个目标 user URI 写入多份向量记录。--没有向量 payload 的旧标量记录会跳过并计入 `migrated.skipped_vector_records`。Session 迁移只复制文件状态,不处理向量索引。--Session owner 按以下顺序解析:--1. `.meta.json.created_by_user_id`-2. `.meta.json.user_id`、`.meta.json.owner_user_id` 或 `.meta.json.created_by`-3. 旧路径里的 user hint,例如 `/session/alice/sess-001`-4. 单用户 account 下的唯一注册用户--多用户 account 下,如果某个 legacy session 无法识别 owner,preflight 会失败。升级后的运行期兼容可以临时读取旧 session,但正式迁移前仍应补齐 owner。--Legacy agent instructions 不迁移:--```text-viking://agent/<agent_id>/instructions-```--迁移会记录 warning,不创建替代目录。--## 迁移前检查--以下问题会在 task 创建前直接失败:--- 物理存储中存在 legacy 数据,但对应 account 不在 API key user registry 中。-- 多用户 account 下存在无法识别 owner 的 legacy session。-- session owner 存在,但不是合法的 OpenViking user id。--以下问题会记录为 warning 或 skipped,并继续迁移:--- 目标 user 已经存在同名 skill。旧 skill 会被跳过,不覆盖现有 skill。-- 发现 legacy agent instructions。Instructions 不迁移。-- 存在共享 legacy agent,但 account 下没有可迁移的目标 user。--如果迁移发现 legacy 数据 owner 不在 user registry 中,会自动注册该 user。迁移结果只记录自动创建了哪些用户,不返回明文 user key。--如果开启了 `api_key_hashing`,明文 key 无法从存储中反查。需要重新生成:--```bash-ov --sudo admin regenerate-key <account_id> <user_id>-```--## 验证迁移结果--查看任务结果:--```bash-ov --sudo task status <task_id>-```--重点看:--- `migrated.files` / `migrated.directories`-- `migrated.vector_records` / `migrated.skipped_vector_records`-- `migrated.operations`-- `skipped`-- `warnings`-- `created_users`--验证新路径:--```bash-ov ls viking://user/<user_id>/peers/<agent_id>/memories-ov ls viking://user/<user_id>/skills-ov ls viking://user/<user_id>/sessions-```--迁移只复制数据,不删除 legacy 路径或旧向量记录。重复执行是幂等的:已存在的目标文件和 skill 会被跳过,不会覆盖。如果迁移后的检索结果不符合预期,再由用户对新路径手动执行 `reindex`;迁移流程本身不会触发 reindex。--## 业务用法迁移--### Client 配置--旧配置可以先继续用:--```json-{- "agent_id": "legacy-agent"-}-```--推荐逐步改成:--```json-{- "actor_peer_id": "legacy-agent"-}-```--不要同时配置:--```json-{- "actor_peer_id": "customer-a",- "agent_id": "legacy-agent"-}-```--这会报错。--### 文件路径--旧路径:--```text-viking://agent/code-agent/memories/profile.md-viking://session/sess-001/messages.jsonl-```--新路径:--```text-viking://user/alice/peers/code-agent/memories/profile.md-viking://user/alice/sessions/sess-001/messages.jsonl-```--`viking://session/<session_id>` 可以继续作为当前 user session 的读 alias 使用,但新写入和长期引用建议使用 `viking://user/<user_id>/sessions/<session_id>`。--### find / search--`find` / `search` 不再接受 legacy agent 身份字段,也不会自动包含未迁移的旧 agent 数据。旧 `viking://agent/...` 路径仍可通过内容和文件系统接口只读访问,但应先完成迁移再使用新检索路径。--迁移完成并确认不再需要旧 agent 数据后,所有 client 都改为 client/request 级 `actor_peer_id`。--### 会话消息--Session 不再从 legacy agent id 推导消息归属;需要表达说话人时必须显式使用 message `peer_id`。--## 暂不迁移数据--升级后可以暂时不迁移,但要知道这些限制:--- 旧 agent/session 数据可读,但旧 namespace 不可写。-- 新 session 和新资源会写入新 namespace,数据会在新旧路径并存一段时间。-- `find` / `search` 不会默认查旧 `viking://agent` 数据。-- 多用户 account 下 owner 不明确的旧 session,运行期可能可读,但正式迁移会被 preflight 拦截。-- cleanup 之前旧目录和旧向量记录仍会保留。--因此不迁移适合作为短期过渡,不建议作为长期状态。--## 可选 cleanup--确认迁移结果无误后,可以删除旧 namespace:--```bash-ov --sudo admin migrate --cleanup --output json-ov --sudo task status <cleanup_task_id>-```--HTTP 请求体:--```json-{- "action": "cleanup"-}-```--Cleanup 只删除:--```text-/local/<account>/agent-/local/<account>/session-/local/<account>/user/<user>/agent-```--Cleanup 会先删除上述 legacy URI scope 下的旧向量记录,再删除对应 AGFS 目录。若向量读取或删除失败,该目录会被跳过,避免旧文件已删除但旧索引仍残留。Cleanup 不会删除新 user / peer 路径下的文件或向量记录。--不会删除新模型目录:--```text-/local/<account>/user/<user>/peers-/local/<account>/user/<user>/sessions-/local/<account>/user/<user>/skills-```--Cleanup 后,`viking://agent/...` 不再用于读取迁移后的 peer 数据;请使用新路径。`viking://session/...` 仍可作为当前 user session 的 alias 读取新 session。--## 常见问题--### ov ls viking://agent 只看到一个 agent--如果配置了 `agent_id` 或 `actor_peer_id`,这是预期行为。`viking://agent` 根目录会过滤到当前 actor peer,只显示对应 legacy agent。--### ov ls viking://session 仍为空--确认服务端已经重启并加载 0.4.0。`viking://session` 的合并读发生在服务端;只升级 CLI 不会改变服务端读取行为。--### 配置同时有 actor_peer_id 和 agent_id--这是不允许的。保留 `agent_id` 进入 legacy 模式,或删除 `agent_id` 后改用 `actor_peer_id`。--### Preflight 报告 unknown account--物理存储中存在某个 account 的 legacy 数据,但 API key registry 中没有这个 account。先恢复或重新创建该 account,再重新执行迁移。--### Preflight 报告 unresolved session owner--给 legacy session 的 `.meta.json` 补充 owner 字段,或把 session 移到能明确识别 owner 的旧路径下,然后重新执行迁移。--### 某个 skill 没有迁移--查看 task 的 `skipped` 列表。最常见原因是目标 user 已经存在同名 skill。迁移不会覆盖现有 skill。