ZaynJarvis · Oct 15, 2026 · Oct 13, 2026 · Oct 13, 2026 · Oct 13, 2026 · Oct 13, 2026
diff --git a/.github/workflows/_build.yml b/.github/workflows/_build.yml
@@ -320,6 +320,9 @@ jobs:
         from openviking.pyagfs import get_binding_client
         import openviking.storage.vectordb.engine as engine
 
+        if importlib.util.find_spec("openviking.integrations") is not None:
+            raise SystemExit("Server wheel must not ship the removed framework namespace")
+
         binding_client, _ = get_binding_client()
         if binding_client is None:
             raise SystemExit("ragfs binding client was not installed")
@@ -555,6 +558,9 @@ jobs:
         from openviking.pyagfs import get_binding_client
         import openviking.storage.vectordb.engine as engine
 
+        if importlib.util.find_spec("openviking.integrations") is not None:
+            raise SystemExit("Server wheel must not ship the removed framework namespace")
+
         binding_client, _ = get_binding_client()
         if binding_client is None:
             raise SystemExit("ragfs binding client was not installed")
@@ -591,6 +597,9 @@ jobs:
 
         import openviking.storage.vectordb.engine as engine
 
+        if importlib.util.find_spec("openviking.integrations") is not None:
+            raise SystemExit("Server wheel must not ship the removed framework namespace")
+
         print(f"Loaded runtime engine variant {engine.ENGINE_VARIANT}")
         print(f"Available engine variants {engine.AVAILABLE_ENGINE_VARIANTS}")
 

diff --git a/.github/workflows/framework-layout.yml b/.github/workflows/framework-layout.yml
@@ -0,0 +1,45 @@
+name: Framework Integration Layout
+
+on:
+  pull_request:
+    paths:
+      - 'integrations/frameworks/**'
+      - 'openviking/integrations/**'
+      - 'examples/langchain/**'
+      - 'examples/langchain-langgraph/**'
+      - 'examples/agent-framework/**'
+      - 'tests/unit/test_langchain_*.py'
+      - 'tests/integration/langchain_langgraph/**'
+      - '.github/workflows/framework-layout.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'integrations/frameworks/**'
+      - 'openviking/integrations/**'
+      - 'examples/langchain/**'
+      - 'examples/langchain-langgraph/**'
+      - 'examples/agent-framework/**'
+      - 'tests/unit/test_langchain_*.py'
+      - 'tests/integration/langchain_langgraph/**'
+      - '.github/workflows/framework-layout.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  layout:
+    name: Framework package locations
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - name: Install test runner
+        run: python -m pip install pytest
+      - name: Check framework package locations
+        # These guards need only pytest and Git, without server-test configuration.
+        run: >-
+          python -m pytest -q --noconftest --rootdir=. -c /dev/null
+          tests/unit/test_langchain_package_boundary.py
+          -k 'server_source_excludes_removed_framework_namespace or framework_sources_and_tests_use_package_locations'
diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml
@@ -181,7 +181,7 @@ jobs:
             echo "cuvs_changed=false" >> $GITHUB_OUTPUT
           fi
 
-          LANGCHAIN_PATTERN="examples/langchain/|openviking/integrations/langchain/|tests/(unit/test_langchain|integration/langchain_langgraph/)|examples/langchain-langgraph/|^pyproject\.toml$|^uv\.lock$|\.github/workflows/(pr|python-langchain-release)\.yml"
+          LANGCHAIN_PATTERN="integrations/frameworks/langchain/|^openviking/integrations/|^tests/unit/test_langchain_[^/]*\.py$|^tests/integration/langchain_langgraph/|^examples/(langchain|langchain-langgraph|agent-framework)/|^pyproject\.toml$|^uv\.lock$|\.github/workflows/(pr|python-langchain-release)\.yml"
           LANGCHAIN_CHANGED_FILES=$(git diff --name-only origin/${{ github.base_ref }} HEAD | grep -E "$LANGCHAIN_PATTERN" || true)
 
           if [ -n "$LANGCHAIN_CHANGED_FILES" ]; then
@@ -292,55 +292,51 @@ jobs:
       - name: Install standalone integration
         run: |
           uv pip install --system -e sdk/python
-          uv pip install --system -e "examples/langchain[langgraph,test,dev]"
+          uv pip install --system -e "integrations/frameworks/langchain[langgraph,test,dev]"
 
       - name: Check package formatting and lint
         run: |
           ruff format --check \
-            examples/langchain/src \
-            examples/langchain/tests \
-            openviking/integrations/langchain \
-            tests/integration/langchain_langgraph \
-            tests/unit/test_langchain*.py
+            integrations/frameworks/langchain/src \
+            integrations/frameworks/langchain/tests \
+            tests/unit/test_langchain_package_boundary.py
           ruff check \
-            examples/langchain/src \
-            examples/langchain/tests \
-            openviking/integrations/langchain \
-            tests/integration/langchain_langgraph \
-            tests/unit/test_langchain*.py
+            integrations/frameworks/langchain/src \
+            integrations/frameworks/langchain/tests \
+            tests/unit/test_langchain_package_boundary.py
 
       - name: Type-check package
         run: >-
           mypy
-          --config-file examples/langchain/pyproject.toml
-          examples/langchain/src/langchain_openviking
+          --config-file integrations/frameworks/langchain/pyproject.toml
+          integrations/frameworks/langchain/src/langchain_openviking
 
       - name: Run LangChain and LangGraph tests
         run: |
           python -m pytest -q --noconftest -o addopts='' \
-            tests/unit/test_langchain*.py \
-            tests/integration/langchain_langgraph
+            integrations/frameworks/langchain/tests \
+            tests/unit/test_langchain_package_boundary.py
 
       - name: Build and inspect distributions
         run: |
-          python -m build examples/langchain
-          python -m twine check examples/langchain/dist/*
+          python -m build integrations/frameworks/langchain
+          python -m twine check integrations/frameworks/langchain/dist/*
 
       - name: Verify the installed wheel
         if: matrix.python-version == '3.12'
         run: |
-          WHEEL_PATH="${GITHUB_WORKSPACE}/$(find examples/langchain/dist -name '*.whl' -print -quit)"
+          WHEEL_PATH="${GITHUB_WORKSPACE}/$(find integrations/frameworks/langchain/dist -name '*.whl' -print -quit)"
           uv venv .langchain-wheel-venv --python "${{ matrix.python-version }}"
           uv pip install \
             --python .langchain-wheel-venv/bin/python \
             sdk/python \
             "${WHEEL_PATH}"
           cd /tmp
           "${GITHUB_WORKSPACE}/.langchain-wheel-venv/bin/python" \
-            "${GITHUB_WORKSPACE}/examples/langchain/tests/installed_base_smoke.py"
+            "${GITHUB_WORKSPACE}/integrations/frameworks/langchain/tests/installed_base_smoke.py"
           uv pip install \
             --python "${GITHUB_WORKSPACE}/.langchain-wheel-venv/bin/python" \
             "${WHEEL_PATH}[langgraph]"
           "${GITHUB_WORKSPACE}/.langchain-wheel-venv/bin/python" \
-            "${GITHUB_WORKSPACE}/examples/langchain/tests/installed_smoke.py"
+            "${GITHUB_WORKSPACE}/integrations/frameworks/langchain/tests/installed_smoke.py"
           uv pip check --python "${GITHUB_WORKSPACE}/.langchain-wheel-venv/bin/python"
diff --git a/.github/workflows/python-agent-framework.yml b/.github/workflows/python-agent-framework.yml
@@ -3,11 +3,13 @@ name: Microsoft Agent Framework Integration
 on:
   pull_request:
     paths:
+      - 'integrations/frameworks/microsoft-agent-framework/**'
       - 'examples/agent-framework/**'
       - '.github/workflows/python-agent-framework.yml'
   push:
     branches: [main]
     paths:
+      - 'integrations/frameworks/microsoft-agent-framework/**'
       - 'examples/agent-framework/**'
       - '.github/workflows/python-agent-framework.yml'
 
@@ -26,7 +28,7 @@ jobs:
             sdk: 'openviking-sdk>=0.1.13,<0.2'
     defaults:
       run:
-        working-directory: examples/agent-framework
+        working-directory: integrations/frameworks/microsoft-agent-framework
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-python@v6

diff --git a/.github/workflows/python-langchain-release.yml b/.github/workflows/python-langchain-release.yml
@@ -50,12 +50,12 @@ jobs:
           python-version: "3.12"
 
       - name: Install build dependencies
-        working-directory: examples/langchain
+        working-directory: integrations/frameworks/langchain
         run: python -m pip install build setuptools setuptools-scm twine wheel
 
       - name: Resolve package version
         id: version
-        working-directory: examples/langchain
+        working-directory: integrations/frameworks/langchain
         run: |
           PACKAGE_VERSION=$(python -m setuptools_scm)
           echo "package_version=$PACKAGE_VERSION" >> "$GITHUB_OUTPUT"
@@ -74,18 +74,18 @@ jobs:
           fi
 
       - name: Build distributions
-        working-directory: examples/langchain
+        working-directory: integrations/frameworks/langchain
         run: python -m build
 
       - name: Validate distributions
-        working-directory: examples/langchain
+        working-directory: integrations/frameworks/langchain
         run: python -m twine check dist/*
 
       - name: Upload distributions
         uses: actions/upload-artifact@v7
         with:
           name: langchain-openviking-distributions
-          path: examples/langchain/dist/*
+          path: integrations/frameworks/langchain/dist/*
 
   publish-testpypi:
     name: Publish to TestPyPI

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -91,7 +91,7 @@ only the contacts relevant to the change.
 | Storage | RAGFS, PathLock, QueueFS, and encryption | `openviking/storage`, `openviking/pyagfs`, `openviking/crypto`, `crates/ragfs*` | `@baojun-zhang` |
 | Integration | Agent plugins and MCP | `agent-plugins`, memory plugin examples, server MCP | `@t0saki`, `@ZaynJarvis` |
 | Integration | VikingBot and agent compilation | `bot`, `ov compile` | `@yeshion23333`, `@fujiajie666` |
-| Client | SDKs, CLI, and LangChain | `sdk`, `crates/ov_cli`, `examples/langchain` | `@zhoujh01`, `@t0saki`, `@ehz0ah` |
+| Client | SDKs, CLI, and LangChain | `sdk`, `crates/ov_cli`, `integrations/frameworks/langchain` | `@zhoujh01`, `@t0saki`, `@ehz0ah` |
 | Product | Web Studio | `web-studio` | `@yufeng201`, `@ZaynJarvis` |
 | Project | Documentation, CI, and plugin releases | `docs`, `.github/workflows` | `@yufeng201`, `@ZaynJarvis` |
 

diff --git a/README.md b/README.md
@@ -316,6 +316,8 @@ Setup guides for each integration:
 
 For setup instructions and integration details, see [Integrations](https://openviking.ai/integrations).
 
+For framework applications, see the [LangChain/LangGraph and Microsoft Agent Framework packages](integrations/frameworks/README.md), with a guide to adding other adapters.
+
 ## Desktop App (Beta)
 
 The desktop app is a console for macOS and Windows x64 (beta). It configures supported local agent integrations, inspects recall and capture events in sessions, and syncs local memories and skills to OpenViking.
@@ -424,6 +426,7 @@ The OpenViking project uses different licenses for different components:
 - **Main Project**: AGPLv3 - see the [LICENSE](./LICENSE) file for details
 - **crates/ov\_cli**: Apache 2.0 - see the [LICENSE](./crates/LICENSE) for details
 - **examples**: Apache 2.0 - see the [LICENSE](./examples/LICENSE) for details. The Hermes plugin in `examples/hermes-plugin` retains its [MIT license](./examples/hermes-plugin/LICENSE).
+- **integrations/frameworks**: adapters declare AGPLv3 in their package metadata and source headers; see each package's `LICENSE`. Their runnable examples retain Apache 2.0; see each package's `examples/LICENSE`.
 - **third\_party**: Respective original licenses of third-party projects
 
 Please also note: any wholesale rewriting and subsequent re-open-sourcing of this project is prohibited; any request to translate all or a substantial portion of the project code into another coding language requires prior written authorization from Volcano Engine. For permission requests, please contact the Volcano Engine team — see [Community & Contributing](#community--contributing) for contact channels.
diff --git a/docs/en/about/02-changelog.md b/docs/en/about/02-changelog.md
@@ -7,6 +7,15 @@ This changelog is automatically generated from [GitHub Releases](https://github.
 
 ## Unreleased
 
+- **LangChain import migration (breaking change)**: The server no longer ships
+  `openviking.integrations.langchain` or its forwarding modules. Old imports fail
+  immediately; there is no deprecation period or compatibility stub. Install
+  `langchain-openviking` (or `pip install "langchain-openviking[langgraph]"` for
+  LangGraph) and replace the `openviking.integrations.langchain` prefix with
+  `langchain_openviking`, including submodule imports. For example, use
+  `from langchain_openviking import OpenVikingRetriever`. The maintained packages
+  and examples now live under `integrations/frameworks/`; package names and
+  canonical imports are unchanged. See the [migration guide](../agent-integrations/07-langchain-langgraph.md).
 - **Working Memory defaults off (behavior change)**: Commits continue to archive raw messages
   and extract long-term memories, but generate no WM/checkpoint summaries by default.
   Update installed agent plugins separately: automatic archive injection and takeover now

diff --git a/docs/en/agent-integrations/07-langchain-langgraph.md b/docs/en/agent-integrations/07-langchain-langgraph.md
@@ -11,9 +11,11 @@ pip install langchain-openviking                 # LangChain adapters
 pip install "langchain-openviking[langgraph]"    # LangGraph middleware support
 ```
 
-The integration is released independently from the OpenViking server. The full
-package keeps forwarding the legacy `openviking.integrations.langchain` import
-path to `langchain-openviking` for existing applications.
+The integration is released independently from the OpenViking server. Starting
+with the next server release after v0.5.0, the legacy
+`openviking.integrations.langchain` namespace is removed without a compatibility
+shim. v0.5.0 still provides it. Install the standalone package and import from
+`langchain_openviking` instead; see the [Unreleased migration notes](../about/02-changelog.md#unreleased).
 
 ## Connection
 
@@ -311,17 +313,17 @@ finish an async lifecycle with `recorder.close()`.
 The repository includes runnable examples that work without model credentials using an in-memory test client:
 
 ```bash
-uv run --project examples/langchain --extra langgraph python examples/langchain-langgraph/langchain/rag/quick_app.py
-uv run --project examples/langchain --extra langgraph python examples/langchain-langgraph/langchain/context-backend/quick_app.py
-uv run --project examples/langchain --extra langgraph python examples/langchain-langgraph/langchain/message-history/quick_app.py
-uv run --project examples/langchain --extra langgraph python examples/langchain-langgraph/langgraph/agent/quick_app.py
-uv run --project examples/langchain --extra langgraph python examples/langchain-langgraph/langgraph/middleware/quick_app.py
+uv run --project integrations/frameworks/langchain --extra langgraph python integrations/frameworks/langchain/examples/langchain/rag/quick_app.py
+uv run --project integrations/frameworks/langchain --extra langgraph python integrations/frameworks/langchain/examples/langchain/context-backend/quick_app.py
+uv run --project integrations/frameworks/langchain --extra langgraph python integrations/frameworks/langchain/examples/langchain/message-history/quick_app.py
+uv run --project integrations/frameworks/langchain --extra langgraph python integrations/frameworks/langchain/examples/langgraph/agent/quick_app.py
+uv run --project integrations/frameworks/langchain --extra langgraph python integrations/frameworks/langchain/examples/langgraph/middleware/quick_app.py
 ```
 
-For a real OpenViking server and OpenAI-compatible model flow, see the [live LangGraph app](https://github.com/volcengine/OpenViking/blob/main/examples/langchain-langgraph/langgraph/agent/live_app.py).
+For a real OpenViking server and OpenAI-compatible model flow, see the [live LangGraph app](https://github.com/volcengine/OpenViking/blob/main/integrations/frameworks/langchain/examples/langgraph/agent/live_app.py).
 
 ## See also
 
 - [Capability Reference](./16-capability-reference.md)
-- [examples/langchain-langgraph/](https://github.com/volcengine/OpenViking/tree/main/examples/langchain-langgraph) — full source for all examples above
+- [integrations/frameworks/langchain/examples/](https://github.com/volcengine/OpenViking/tree/main/integrations/frameworks/langchain/examples) — full source for all examples above
 - [MCP Clients](./06-mcp-clients.md) — for non-SDK MCP integration
diff --git a/docs/en/guides/working-memory-default-off.md b/docs/en/guides/working-memory-default-off.md
@@ -86,7 +86,7 @@ that it depends on OV history. Middleware defaults to
 `include_session_context=False`. Put it before native summarization middleware
 so raw messages are captured before the framework replaces them. Message capture
 watermarks are persisted in graph state. See the runnable
-[native history example](https://github.com/volcengine/OpenViking/blob/main/examples/langchain-langgraph/langgraph/middleware/native_history.py)
+[native history example](https://github.com/volcengine/OpenViking/blob/main/integrations/frameworks/langchain/examples/langgraph/middleware/native_history.py)
 and its pinned requirements for LangChain summarization with a SQLite checkpointer.
 
 VikingBot is an exception to the host-history default: it still uses OV Working

diff --git a/docs/repository/CONTRIBUTING_CN.md b/docs/repository/CONTRIBUTING_CN.md
@@ -77,7 +77,7 @@ OpenViking 重视聚焦且经过充分理解的改动。无论是否使用 AI
 | Storage | RAGFS、PathLock、QueueFS 与加密 | `openviking/storage`、`openviking/pyagfs`、`openviking/crypto`、`crates/ragfs*` | `@baojun-zhang` |
 | Integration | Agent Plugin 与 MCP | `agent-plugins`、记忆插件示例、Server MCP | `@t0saki`、`@ZaynJarvis` |
 | Integration | VikingBot 与 Agent 编译 | `bot`、`ov compile` | `@yeshion23333`、`@fujiajie666` |
-| Client | SDK、CLI 与 LangChain | `sdk`、`crates/ov_cli`、`examples/langchain` | `@zhoujh01`、`@t0saki`、`@ehz0ah` |
+| Client | SDK、CLI 与 LangChain | `sdk`、`crates/ov_cli`、`integrations/frameworks/langchain` | `@zhoujh01`、`@t0saki`、`@ehz0ah` |
 | Product | Web Studio | `web-studio` | `@yufeng201`、`@ZaynJarvis` |
 | Project | 文档、CI 与 Plugin 发布 | `docs`、`.github/workflows` | `@yufeng201`、`@ZaynJarvis` |
 

diff --git a/docs/repository/CONTRIBUTING_JA.md b/docs/repository/CONTRIBUTING_JA.md
@@ -83,7 +83,7 @@ OpenVikingでは、焦点が絞られ、十分に理解された変更を重視
 | Storage | RAGFS、PathLock、QueueFS、暗号化 | `openviking/storage`、`openviking/pyagfs`、`openviking/crypto`、`crates/ragfs*` | `@baojun-zhang` |
 | Integration | Agent PluginとMCP | `agent-plugins`、メモリPluginの例、Server MCP | `@t0saki`、`@ZaynJarvis` |
 | Integration | VikingBotとAgentコンパイル | `bot`、`ov compile` | `@yeshion23333`、`@fujiajie666` |
-| Client | SDK、CLI、LangChain | `sdk`、`crates/ov_cli`、`examples/langchain` | `@zhoujh01`、`@t0saki`、`@ehz0ah` |
+| Client | SDK、CLI、LangChain | `sdk`、`crates/ov_cli`、`integrations/frameworks/langchain` | `@zhoujh01`、`@t0saki`、`@ehz0ah` |
 | Product | Web Studio | `web-studio` | `@yufeng201`、`@ZaynJarvis` |
 | Project | ドキュメント、CI、Pluginリリース | `docs`、`.github/workflows` | `@yufeng201`、`@ZaynJarvis` |
 

diff --git a/docs/repository/README_CN.md b/docs/repository/README_CN.md
@@ -311,6 +311,8 @@ Codex 首次启动会停在 `Hooks need review`，选 `Trust all and continue`
 
 详细接入方式请参考 [Integrations](https://openviking.ai/integrations)。
 
+框架应用请参考 [LangChain/LangGraph 和 Microsoft Agent Framework 集成包](../../integrations/frameworks/README.md)，其中也介绍了如何添加其他框架适配器。
+
 ## 桌面客户端（Beta）
 
 桌面客户端是面向 macOS 和 Windows x64 的控制台（Beta），用于配置支持的本地 Agent 接入、查看会话中的召回与捕获事件，并将本地记忆和技能同步到 OpenViking。
@@ -417,4 +419,5 @@ OpenViking 各组件采用不同的许可证：
 - **主项目**：AGPLv3——详见 [LICENSE](../../LICENSE)
 - **crates/ov\_cli**：Apache 2.0——详见 [LICENSE](../../crates/LICENSE)
 - **examples**：Apache 2.0——详见 [LICENSE](../../examples/LICENSE)。`examples/hermes-plugin` 中的 Hermes 插件保留其 [MIT 许可证](../../examples/hermes-plugin/LICENSE)。
+- **integrations/frameworks**：适配器的包元数据和源码声明 AGPLv3，详见各包的 `LICENSE`；可运行示例保留 Apache 2.0，详见各包的 `examples/LICENSE`。
 - **third\_party**：各三方项目保留其原有协议