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(guides):Add concise OVPack guide in Chinese and English (#1126)
zgyba5d1f443c87
diff --git a/docs/en/guides/09-ovpack.md b/docs/en/guides/09-ovpack.mdnew file mode 100644index 000000000..6b1189350--- /dev/null+++ b/docs/en/guides/09-ovpack.md@@ -0,0 +1,232 @@+# OVPack Import and Export++OVPack is OpenViking's packaging format for exporting/importing context subtrees (e.g., resources and memories) for backup, migration, and sharing.++## Quick Start++### Export Resources++Export OpenViking resources to an `.ovpack` file.++**CLI**+```bash+openviking export viking://resources/my-project/ ./exports/my-project.ovpack+```++**Python SDK**+```python+from openviking import AsyncOpenViking++async def export_example():+ client = AsyncOpenViking()+ await client.initialize()+ try:+ exported_path = await client.export_ovpack(+ uri="viking://resources/my-project/",+ to="./exports/my-project.ovpack"+ )+ print(f"Export successful: {exported_path}")+ finally:+ await client.close()+```++### Import Resources++Import an `.ovpack` file into OpenViking.++**CLI**+```bash+# Basic import+openviking import ./exports/my-project.ovpack viking://resources/imported/++# Force overwrite+openviking import ./exports/my-project.ovpack viking://resources/imported/ --force++# Skip vectorization (faster)+openviking import ./exports/my-project.ovpack viking://resources/imported/ --no-vectorize+```++**Python SDK**+```python+from openviking import AsyncOpenViking++async def import_example():+ client = AsyncOpenViking()+ await client.initialize()+ try:+ imported_uri = await client.import_ovpack(+ file_path="./exports/my-project.ovpack",+ parent="viking://resources/imported/",+ force=True,+ vectorize=True+ )+ print(f"Import successful: {imported_uri}")+ await client.wait_processed()+ finally:+ await client.close()+```++**HTTP API**+```bash+# Step 1: Upload the local ovpack file+TEMP_FILE_ID=$(+ curl -sS -X POST http://localhost:1933/api/v1/resources/temp_upload \+ -H "X-API-Key: your-key" \+ -F 'file=@./exports/my-project.ovpack' \+ | jq -r '.result.temp_file_id'+)++# Step 2: Import using temp_file_id+curl -X POST http://localhost:1933/api/v1/pack/import \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key" \+ -d "{+ \"temp_file_id\": \"$TEMP_FILE_ID\",+ \"parent\": \"viking://resources/imported/\",+ \"force\": true,+ \"vectorize\": true+ }"+```++## Memory Import and Export++OpenViking memories are stored under fixed directory structures:++- User memories: `viking://user/{user_space}/memories/`+- Agent memories: `viking://agent/{agent_space}/memories/`++When migrating memories with OVPack, you must import the `.ovpack` into the parent of the corresponding space (not an arbitrary directory). Otherwise you may end up with paths like `.../memories/memories/...`, and OpenViking will not be able to access and use them as memories.++### Export/Import User Memories (CLI)++```bash+# Export the whole user memories subtree+openviking export viking://user/default/memories/ ./exports/user-memories.ovpack++# Import into the user space root (imports to viking://user/default/memories/)+openviking import ./exports/user-memories.ovpack viking://user/default/ --force+```++### Export/Import Agent Memories (CLI)++```bash+openviking export viking://agent/default/memories/ ./exports/agent-memories.ovpack+openviking import ./exports/agent-memories.ovpack viking://agent/default/ --force+```++### Export/Import Memories (Python SDK)++```python+from openviking import AsyncOpenViking++async def export_import_user_memories():+ client = AsyncOpenViking()+ await client.initialize()+ try:+ await client.export_ovpack(+ uri="viking://user/default/memories/",+ to="./exports/user-memories.ovpack",+ )++ await client.import_ovpack(+ file_path="./exports/user-memories.ovpack",+ parent="viking://user/default/",+ force=True,+ vectorize=True,+ )+ finally:+ await client.close()++async def export_import_agent_memories():+ client = AsyncOpenViking()+ await client.initialize()+ try:+ await client.export_ovpack(+ uri="viking://agent/default/memories/",+ to="./exports/agent-memories.ovpack",+ )+ await client.import_ovpack(+ file_path="./exports/agent-memories.ovpack",+ parent="viking://agent/default/",+ force=True,+ vectorize=True,+ )+ finally:+ await client.close()+```++### Export/Import Memories (HTTP API)++```bash+# Export user memories+curl -X POST http://localhost:1933/api/v1/pack/export \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key" \+ -d '{+ "uri": "viking://user/default/memories/",+ "to": "./exports/user-memories.ovpack"+ }'++# Import user memories (upload first, then import via temp_file_id)+TEMP_FILE_ID=$(+ curl -sS -X POST http://localhost:1933/api/v1/resources/temp_upload \+ -H "X-API-Key: your-key" \+ -F 'file=@./exports/user-memories.ovpack' \+ | jq -r '.result.temp_file_id'+)+curl -X POST http://localhost:1933/api/v1/pack/import \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key" \+ -d "{+ \"temp_file_id\": \"$TEMP_FILE_ID\",+ \"parent\": \"viking://user/default/\",+ \"force\": true,+ \"vectorize\": true+ }"+```++### Vectorization on Import++- Vectorization is enabled by default (useful for `find/search`).+- For faster restore, you can disable it and process later with `--no-vectorize`:++```bash+openviking import ./exports/user-memories.ovpack viking://user/default/ --force --no-vectorize+```++## Use Cases++### Resource Backup+```bash+DATE=$(date +%Y%m%d)+openviking export viking://resources/ ./backups/backup_${DATE}.ovpack+```++### Resource Migration+```bash+# Export on Machine A+openviking export viking://resources/my-project/ ./migration.ovpack++# Import on Machine B+openviking import ./migration.ovpack viking://resources/ --force+```++### Resource Sharing+```bash+# Export+openviking export viking://resources/shared-docs/ ./shared-docs.ovpack++# Recipient imports+openviking import ./shared-docs.ovpack viking://resources/team-shared/+```++## FAQ++**Q: Can I manually extract and view OVPack files?**+A: Yes! OVPack is a standard ZIP format and can be opened with any compression tool.++**Q: What if large OVPack imports are slow?**+A: Use `--no-vectorize` for fast import, then vectorize later.++**Q: How to handle duplicate resources during import?**+A: Use `--force` to overwrite existing resources.diff --git a/docs/zh/guides/09-ovpack.md b/docs/zh/guides/09-ovpack.mdnew file mode 100644index 000000000..3b7ce01d5--- /dev/null+++ b/docs/zh/guides/09-ovpack.md@@ -0,0 +1,243 @@+# OVPack 导入导出++OVPack 是 OpenViking 的打包格式,用于导出/导入任意上下文子树(例如资源、记忆),以便备份、迁移和分享。++## 快速开始++### 导出资源++将 OpenViking 中的资源导出为 `.ovpack` 文件。++**CLI**+```bash+openviking export viking://resources/my-project/ ./exports/my-project.ovpack+```++**Python SDK**+```python+from openviking import AsyncOpenViking++async def export_example():+ client = AsyncOpenViking()+ await client.initialize()+ try:+ exported_path = await client.export_ovpack(+ uri="viking://resources/my-project/",+ to="./exports/my-project.ovpack"+ )+ print(f"导出成功: {exported_path}")+ finally:+ await client.close()+```++**HTTP API**+```bash+curl -X POST http://localhost:1933/api/v1/pack/export \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key" \+ -d '{+ "uri": "viking://resources/my-project/",+ "to": "./exports/my-project.ovpack"+ }'+```++### 导入资源++将 `.ovpack` 文件导入到 OpenViking 中。++**CLI**+```bash+# 基本导入+openviking import ./exports/my-project.ovpack viking://resources/imported/++# 强制覆盖+openviking import ./exports/my-project.ovpack viking://resources/imported/ --force++# 跳过向量化(更快)+openviking import ./exports/my-project.ovpack viking://resources/imported/ --no-vectorize+```++**Python SDK**+```python+from openviking import AsyncOpenViking++async def import_example():+ client = AsyncOpenViking()+ await client.initialize()+ try:+ imported_uri = await client.import_ovpack(+ file_path="./exports/my-project.ovpack",+ parent="viking://resources/imported/",+ force=True,+ vectorize=True+ )+ print(f"导入成功: {imported_uri}")+ await client.wait_processed()+ finally:+ await client.close()+```++**HTTP API**+```bash+# 第一步:上传本地 ovpack 文件+TEMP_FILE_ID=$(+ curl -sS -X POST http://localhost:1933/api/v1/resources/temp_upload \+ -H "X-API-Key: your-key" \+ -F 'file=@./exports/my-project.ovpack' \+ | jq -r '.result.temp_file_id'+)++# 第二步:使用 temp_file_id 导入+curl -X POST http://localhost:1933/api/v1/pack/import \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key" \+ -d "{+ \"temp_file_id\": \"$TEMP_FILE_ID\",+ \"parent\": \"viking://resources/imported/\",+ \"force\": true,+ \"vectorize\": true+ }"+```++## 记忆导入导出++OpenViking 的记忆会写入固定的目录结构中:++- 用户记忆:`viking://user/{user_space}/memories/`+- Agent 记忆:`viking://agent/{agent_space}/memories/`++使用 OVPack 迁移记忆时,必须把 `.ovpack` 导入到对应 space 的父目录(而不是随便一个目录),否则会变成例如 `.../memories/memories/...` 的路径,OpenViking 将无法按“记忆”语义访问和使用这些文件。++### 导出/导入用户记忆(CLI)++```bash+# 导出:整个用户 memories 子树+openviking export viking://user/default/memories/ ./exports/user-memories.ovpack++# 导入:注意 parent 需要是 user space 根目录(导入后会生成 viking://user/default/memories/)+openviking import ./exports/user-memories.ovpack viking://user/default/ --force+```++### 导出/导入 Agent 记忆(CLI)++```bash+openviking export viking://agent/default/memories/ ./exports/agent-memories.ovpack+openviking import ./exports/agent-memories.ovpack viking://agent/default/ --force+```++### 导出/导入记忆(Python SDK)++```python+from openviking import AsyncOpenViking++async def export_import_user_memories():+ client = AsyncOpenViking()+ await client.initialize()+ try:+ await client.export_ovpack(+ uri="viking://user/default/memories/",+ to="./exports/user-memories.ovpack",+ )++ await client.import_ovpack(+ file_path="./exports/user-memories.ovpack",+ parent="viking://user/default/",+ force=True,+ vectorize=True,+ )+ finally:+ await client.close()++async def export_import_agent_memories():+ client = AsyncOpenViking()+ await client.initialize()+ try:+ await client.export_ovpack(+ uri="viking://agent/default/memories/",+ to="./exports/agent-memories.ovpack",+ )+ await client.import_ovpack(+ file_path="./exports/agent-memories.ovpack",+ parent="viking://agent/default/",+ force=True,+ vectorize=True,+ )+ finally:+ await client.close()+```++### 导出/导入记忆(HTTP API)++```bash+# 导出用户记忆+curl -X POST http://localhost:1933/api/v1/pack/export \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key" \+ -d '{+ "uri": "viking://user/default/memories/",+ "to": "./exports/user-memories.ovpack"+ }'++# 导入用户记忆(先上传,再用 temp_file_id 导入)+TEMP_FILE_ID=$(+ curl -sS -X POST http://localhost:1933/api/v1/resources/temp_upload \+ -H "X-API-Key: your-key" \+ -F 'file=@./exports/user-memories.ovpack' \+ | jq -r '.result.temp_file_id'+)+curl -X POST http://localhost:1933/api/v1/pack/import \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key" \+ -d "{+ \"temp_file_id\": \"$TEMP_FILE_ID\",+ \"parent\": \"viking://user/default/\",+ \"force\": true,+ \"vectorize\": true+ }"+```++### 导入后是否向量化++- 默认会向量化(便于 `find/search` 检索)。+- 如果只做快速恢复、稍后再统一处理,可使用 `--no-vectorize`:++```bash+openviking import ./exports/user-memories.ovpack viking://user/default/ --force --no-vectorize+```++## 使用场景++### 资源备份+```bash+DATE=$(date +%Y%m%d)+openviking export viking://resources/ ./backups/backup_${DATE}.ovpack+```++### 资源迁移+```bash+# 机器 A 导出+openviking export viking://resources/my-project/ ./migration.ovpack++# 机器 B 导入+openviking import ./migration.ovpack viking://resources/ --force+```++### 资源分享+```bash+# 导出+openviking export viking://resources/shared-docs/ ./shared-docs.ovpack++# 接收者导入+openviking import ./shared-docs.ovpack viking://resources/team-shared/+```++## 常见问题++**Q: OVPack 文件可以手动解压查看吗?**+A: 可以!OVPack 是标准的 ZIP 格式,可以用任何解压工具打开。++**Q: 大体积 OVPack 导入很慢怎么办?**+A: 使用 `--no-vectorize` 先快速导入,之后再统一向量化。++**Q: 导入时如何处理重名资源?**+A: 使用 `--force` 参数覆盖已存在的资源。