diff --git a/docs/en/guides/06-mcp-integration.md b/docs/en/guides/06-mcp-integration.md index e85161017..e170cb19c 100644 --- 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 index 7ed728cda..d3c9106ba 100644 --- 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 index 3bfc2fb76..289f851a5 100644 --- 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 index 19667fb83..80f5700f8 100644 --- 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+