volcengine · yeyitech · Apr 17, 2026
diff --git a/docs/en/guides/06-mcp-integration.md b/docs/en/guides/06-mcp-integration.md
@@ -2,6 +2,38 @@
 
 OpenViking can be used as an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server, allowing any MCP-compatible client to access its memory and resource capabilities.
 
+## Choosing the Integration Pattern
+
+`examples/skills` is not the only or default integration path for agents.
+On current `main`, OpenViking has three common agent integration patterns:
+
+| Pattern | Best for | What you get |
+|---|---|---|
+| MCP server | General-purpose agent hosts that can call MCP tools | Cross-host integration, shared server deployment, explicit tool access |
+| Host-specific plugin/example | Hosts that expose lifecycle hooks beyond plain tool calls | Deeper recall/capture behavior, host-native UX, tighter runtime integration |
+| Embedded SDK / HTTP SDK | Custom applications you own end to end | Full control over ingestion, retrieval, sessions, and storage from application code |
+
+### Where `examples/skills` fits
+
+Use `examples/skills` when your host already has a native "skill", "tool pack", or prompt-driven tool integration mechanism and you want a lightweight, explicit workflow such as:
+
+- add data into OpenViking
+- search OpenViking context on demand
+- operate the OpenViking server from an agent
+
+Those examples are intentionally narrow. They are a good pattern for explicit tool calls, but they are not a replacement for:
+
+- the MCP server, when you want a general integration path across Claude Code, Cursor, Claude Desktop, OpenClaw, and similar hosts
+- host-specific plugins such as the OpenClaw context-engine example or the Claude Code memory plugin, when you need automatic recall/capture tied to the host lifecycle
+- the SDK, when you are embedding OpenViking directly into your own Python service or application
+
+### Quick recommendations
+
+- Start with MCP if you want one integration story that works across multiple agent hosts.
+- Use `examples/skills` if your host already has a strong native skill abstraction and you only need explicit OpenViking tool calls.
+- Use a host-specific plugin/example if you need lifecycle-aware memory behavior, not just callable tools.
+- Use the SDK if you are building the application itself and do not need MCP at all.
+
 ## Transport Modes
 
 OpenViking supports two MCP transport modes:

diff --git a/docs/zh/guides/06-mcp-integration.md b/docs/zh/guides/06-mcp-integration.md
@@ -2,6 +2,38 @@
 
 OpenViking 可以作为 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 服务器使用，任何兼容 MCP 的客户端都可以访问其记忆和资源能力。
 
+## 先选对接入模式
+
+`examples/skills` 不是唯一方案，也不是当前通用 Agent 接入的默认路径。
+在当前主干里，OpenViking 常见有三种 Agent 接入模式：
+
+| 模式 | 适合场景 | 你会得到什么 |
+|---|---|---|
+| MCP server | 能调用 MCP 工具的通用 Agent 宿主 | 跨宿主复用、共享服务部署、显式工具调用 |
+| 宿主专用插件 / 示例 | 宿主本身提供了普通工具调用之外的生命周期 hook | 更深的 recall/capture 能力、宿主原生体验、更紧的运行时集成 |
+| Embedded SDK / HTTP SDK | 你自己全权控制的应用或服务 | 从应用代码直接控制导入、检索、session 与存储 |
+
+### `examples/skills` 适合什么
+
+当宿主本身已经有 “skill / tool pack / prompt tool” 这类原生机制，而你只需要轻量、显式地调用 OpenViking 时，`examples/skills` 很合适。例如：
+
+- 把数据写入 OpenViking
+- 按需查询 OpenViking 上下文
+- 让 Agent 操作 OpenViking 服务端
+
+这些示例是刻意做窄的。它们很适合作为显式工具调用模式，但并不替代：
+
+- MCP server：当你需要一条能覆盖 Claude Code、Cursor、Claude Desktop、OpenClaw 等宿主的通用接入路径
+- 宿主专用插件：例如 OpenClaw context-engine 示例、Claude Code memory plugin，这类集成需要绑定宿主生命周期，做自动 recall/capture
+- SDK：当你是把 OpenViking 直接嵌入到自有 Python 服务或应用中
+
+### 快速建议
+
+- 如果你想要一套能跨多个 Agent 宿主复用的接入方式，优先用 MCP。
+- 如果宿主已经有成熟的 skill 抽象，而且你只需要显式工具调用，选 `examples/skills`。
+- 如果你要的是生命周期感知的记忆行为，而不只是可调用工具，选宿主专用插件 / 示例。
+- 如果你在开发自己的应用，并不需要 MCP，直接用 SDK。
+
 ## 传输模式
 
 OpenViking 支持两种 MCP 传输模式：

diff --git a/examples/basic-usage/README.md b/examples/basic-usage/README.md
@@ -28,6 +28,24 @@ OpenViking currently has three common integration paths:
 
 If you are building anything beyond a one-process local demo, prefer HTTP server mode over spawning isolated local processes repeatedly. For MCP specifically, follow the dedicated [MCP Integration Guide](../../docs/en/guides/06-mcp-integration.md).
 
+## How This Relates to Agent Hosts
+
+If your real goal is "connect OpenViking to an agent host", this SDK example is only one path.
+
+| Integration path | Use it when |
+|---|---|
+| Embedded SDK / HTTP SDK | You own the application code and want direct programmatic control |
+| MCP | Your host already supports MCP and you want a reusable, host-agnostic integration |
+| `examples/skills` | Your host has its own skill/tool abstraction and you only need explicit OpenViking operations |
+| Host-specific plugin examples | You need lifecycle-aware behavior such as automatic recall/capture inside a specific host |
+
+Examples of the host-specific path in this repo:
+
+- [OpenClaw Plugin](../openclaw-plugin/README.md)
+- [Claude Code Memory Plugin](../claude-code-memory-plugin/README.md)
+
+For the general cross-host path, go to the [MCP Integration Guide](../../docs/en/guides/06-mcp-integration.md).
+
 ## Prerequisites
 
 1. Python 3.10+

diff --git a/examples/basic-usage/README_CN.md b/examples/basic-usage/README_CN.md
@@ -29,6 +29,24 @@
 如果不是单进程本地 demo，而是要长期运行或多端接入，优先使用 HTTP 服务端模式。  
 如果你是给 Claude Code、Cursor 这类客户端接入，请直接看 [MCP 集成指南](../../docs/zh/guides/06-mcp-integration.md)。
 
+## 这和 Agent 宿主接入是什么关系
+
+如果你的真实目标是“把 OpenViking 接到某个 Agent 宿主里”，这个 SDK 示例只是其中一条路径。
+
+| 接入路径 | 什么时候用 |
+|---|---|
+| Embedded SDK / HTTP SDK | 你自己控制应用代码，需要直接编程接入 |
+| MCP | 宿主已经支持 MCP，你希望复用一套跨宿主的通用接入方式 |
+| `examples/skills` | 宿主有自己的 skill / tool 抽象，你只需要显式调用 OpenViking 能力 |
+| 宿主专用插件示例 | 你需要和某个宿主的生命周期深度绑定，比如自动 recall / capture |
+
+仓库里宿主专用接入的代表示例包括：
+
+- [OpenClaw 插件](../openclaw-plugin/README_CN.md)
+- [Claude Code 记忆插件](../claude-code-memory-plugin/README_CN.md)
+
+如果你要的是跨宿主通用方案，请直接看 [MCP 集成指南](../../docs/zh/guides/06-mcp-integration.md)。
+
 ## 前置条件
 
 1. Python 3.10+