# volcengine/openviking architecture

> Architecture diagram of the GitHub repository volcengine/openviking, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/volcengine/openviking
- Repository: https://github.com/volcengine/openviking
- Video tour (about a minute): https://gitdiagram.com/volcengine/openviking/video

## Overview

OpenViking is a context database for AI agents, organizing knowledge, memories, and skills as browsable `viking://` filesystem resources. The principal workflow is to ingest or add context, store it with semantic summaries, then let an agent search within a scope and read relevant tiers through the service. Sessions can preserve conversations and extract memories; with VikingBot, source material can also be compiled into a wiki, knowledge graph, or report. The README documents these capabilities, but sampled code is incomplete, so unverified subsystem links are omitted.

Main entry points: [`openviking/retrieve/context_assembler/pipeline.py`](https://github.com/volcengine/openviking/blob/main/openviking/retrieve/context_assembler/pipeline.py) (Context assembly), [`openviking/service/session_service.py`](https://github.com/volcengine/openviking/blob/main/openviking/service/session_service.py) (Session service), [`bot/vikingbot/agent/loop.py`](https://github.com/volcengine/openviking/blob/main/bot/vikingbot/agent/loop.py) (VikingBot agent), [`openviking/core/namespace.py`](https://github.com/volcengine/openviking/blob/main/openviking/core/namespace.py) (Context namespace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and service"]
  node_sdk["Client SDKs"]
  node_server["HTTP server<br/>[app.py]"]
  node_search_service["Search service<br/>[search_service.py]"]
  node_config["Runtime config<br/>[manager.py]"]
end

subgraph group_context["Context lifecycle"]
  node_ingest["Ingest orchestration<br/>[orchestrator.py]"]
  node_parsing["Parsing and import<br/>[parser_router.py]"]
  node_context_namespace["Context namespace<br/>[namespace.py]"]
  node_session_service["Session service<br/>[session_service.py]"]
  node_session_training["Session training<br/>[pipeline.py]"]
end

subgraph group_retrieval["Retrieval and models"]
  node_retrieval_pipeline["Context assembly<br/>[pipeline.py]"]
  node_embedder["Embedding providers<br/>[base.py]"]
  node_vlm["VLM providers<br/>[volcengine_vlm.py]"]
end

subgraph group_persistence["Storage and identity"]
  node_vector_collection[("Vector collections<br/>[collection.py]")]
  node_volc_collection[("Volcengine collection")]
  node_vector_project[("Vector project")]
  node_namespace_identity["Namespace identity<br/>[namespace.py]"]
end

subgraph group_agent["Agent workflows"]
  node_vikingbot["VikingBot agent<br/>[loop.py]"]
  node_bot_session["Bot sessions<br/>[manager.py]"]
  node_bot_channels["Messaging channels<br/>[manager.py]"]
  node_bot_compile["Context compilation<br/>[service.py]"]
end

node_agent_user(("AI agent"))

node_agent_user -.->|"uses"| node_sdk
node_sdk -.->|"requests context"| node_server
node_server -.->|"routes search"| node_search_service
node_agent_user -.->|"browses context"| node_context_namespace
node_ingest -.->|"imports sources"| node_parsing
node_ingest -.->|"adds resources"| node_context_namespace
node_search_service -.->|"assembles context"| node_retrieval_pipeline
node_retrieval_pipeline -->|"embeds queries"| node_embedder
node_retrieval_pipeline -->|"loads session"| node_session_service
node_retrieval_pipeline -.->|"retrieves candidates"| node_vector_collection
node_vector_collection -.->|"delegates operations"| node_volc_collection
node_vector_project -.->|"constructs collection"| node_volc_collection
node_session_service -->|"resolves namespace"| node_namespace_identity
node_session_service -->|"uses identifiers"| node_context_namespace
node_session_training -.->|"trains with models"| node_vlm
node_agent_user -.->|"sends messages"| node_bot_channels
node_bot_channels -.->|"dispatches messages"| node_vikingbot
node_vikingbot -->|"uses sessions"| node_bot_session
node_vikingbot -.->|"invokes compilation"| node_bot_compile

click node_sdk "https://github.com/volcengine/openviking/tree/main/sdk"
click node_server "https://github.com/volcengine/openviking/blob/main/openviking/server/app.py"
click node_search_service "https://github.com/volcengine/openviking/blob/main/openviking/service/search_service.py"
click node_config "https://github.com/volcengine/openviking/blob/main/openviking/config/manager.py"
click node_ingest "https://github.com/volcengine/openviking/blob/main/openviking/ingest/orchestrator.py"
click node_parsing "https://github.com/volcengine/openviking/blob/main/openviking/parse/parser_router.py"
click node_context_namespace "https://github.com/volcengine/openviking/blob/main/openviking/core/namespace.py"
click node_session_service "https://github.com/volcengine/openviking/blob/main/openviking/service/session_service.py"
click node_session_training "https://github.com/volcengine/openviking/blob/main/openviking/session/train/pipeline.py"
click node_retrieval_pipeline "https://github.com/volcengine/openviking/blob/main/openviking/retrieve/context_assembler/pipeline.py"
click node_embedder "https://github.com/volcengine/openviking/blob/main/openviking/models/embedder/base.py"
click node_vlm "https://github.com/volcengine/openviking/blob/main/openviking/models/vlm/backends/volcengine_vlm.py"
click node_vector_collection "https://github.com/volcengine/openviking/blob/main/openviking/storage/vectordb/collection/collection.py"
click node_volc_collection "https://github.com/volcengine/openviking/blob/main/openviking/storage/vectordb/collection/volcengine_collection.py"
click node_vector_project "https://github.com/volcengine/openviking/blob/main/openviking/storage/vectordb/project/volcengine_project.py"
click node_namespace_identity "https://github.com/volcengine/openviking/blob/main/openviking/core/namespace.py"
click node_vikingbot "https://github.com/volcengine/openviking/blob/main/bot/vikingbot/agent/loop.py"
click node_bot_session "https://github.com/volcengine/openviking/blob/main/bot/vikingbot/session/manager.py"
click node_bot_channels "https://github.com/volcengine/openviking/blob/main/bot/vikingbot/channels/manager.py"
click node_bot_compile "https://github.com/volcengine/openviking/blob/main/bot/vikingbot/compile/service.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sdk,node_server,node_search_service,node_config toneBlue
class node_ingest,node_parsing,node_context_namespace,node_session_service,node_session_training toneAmber
class node_retrieval_pipeline,node_embedder,node_vlm toneMint
class node_vector_collection,node_volc_collection,node_vector_project,node_namespace_identity toneRose
class node_vikingbot,node_bot_session,node_bot_channels,node_bot_compile,node_agent_user toneIndigo
```

## Components

### Access and service

- [Client SDKs](https://github.com/volcengine/openviking/tree/main/sdk): `sdk`
- [HTTP server](https://github.com/volcengine/openviking/blob/main/openviking/server/app.py): `openviking/server/app.py`
- [Search service](https://github.com/volcengine/openviking/blob/main/openviking/service/search_service.py): `openviking/service/search_service.py`
- [Runtime config](https://github.com/volcengine/openviking/blob/main/openviking/config/manager.py): `openviking/config/manager.py`

### Context lifecycle

- [Ingest orchestration](https://github.com/volcengine/openviking/blob/main/openviking/ingest/orchestrator.py): `openviking/ingest/orchestrator.py`
- [Parsing and import](https://github.com/volcengine/openviking/blob/main/openviking/parse/parser_router.py): `openviking/parse/parser_router.py`
- [Context namespace](https://github.com/volcengine/openviking/blob/main/openviking/core/namespace.py): `openviking/core/namespace.py`
- [Session service](https://github.com/volcengine/openviking/blob/main/openviking/service/session_service.py): `openviking/service/session_service.py`
- [Session training](https://github.com/volcengine/openviking/blob/main/openviking/session/train/pipeline.py): `openviking/session/train/pipeline.py`

### Retrieval and models

- [Context assembly](https://github.com/volcengine/openviking/blob/main/openviking/retrieve/context_assembler/pipeline.py): `openviking/retrieve/context_assembler/pipeline.py`
- [Embedding providers](https://github.com/volcengine/openviking/blob/main/openviking/models/embedder/base.py): `openviking/models/embedder/base.py`
- [VLM providers](https://github.com/volcengine/openviking/blob/main/openviking/models/vlm/backends/volcengine_vlm.py): `openviking/models/vlm/backends/volcengine_vlm.py`

### Storage and identity

- [Vector collections](https://github.com/volcengine/openviking/blob/main/openviking/storage/vectordb/collection/collection.py): `openviking/storage/vectordb/collection/collection.py`
- [Volcengine collection](https://github.com/volcengine/openviking/blob/main/openviking/storage/vectordb/collection/volcengine_collection.py): `openviking/storage/vectordb/collection/volcengine_collection.py`
- [Vector project](https://github.com/volcengine/openviking/blob/main/openviking/storage/vectordb/project/volcengine_project.py): `openviking/storage/vectordb/project/volcengine_project.py`
- [Namespace identity](https://github.com/volcengine/openviking/blob/main/openviking/core/namespace.py): `openviking/core/namespace.py`

### Agent workflows

- [VikingBot agent](https://github.com/volcengine/openviking/blob/main/bot/vikingbot/agent/loop.py): `bot/vikingbot/agent/loop.py`
- [Bot sessions](https://github.com/volcengine/openviking/blob/main/bot/vikingbot/session/manager.py): `bot/vikingbot/session/manager.py`
- [Messaging channels](https://github.com/volcengine/openviking/blob/main/bot/vikingbot/channels/manager.py): `bot/vikingbot/channels/manager.py`
- [Context compilation](https://github.com/volcengine/openviking/blob/main/bot/vikingbot/compile/service.py): `bot/vikingbot/compile/service.py`

### Other components

- **AI agent**

## Connections

- AI agent → Client SDKs: uses
- Client SDKs → HTTP server: requests context
- HTTP server → Search service: routes search
- AI agent → Context namespace: browses context (evidence: `README.md`)
- Ingest orchestration → Parsing and import: imports sources
- Ingest orchestration → Context namespace: adds resources
- Search service → Context assembly: assembles context (evidence: `README.md`)
- Context assembly → Embedding providers: embeds queries (evidence: `openviking/retrieve/context_assembler/pipeline.py`)
- Context assembly → Session service: loads session (evidence: `openviking/retrieve/context_assembler/pipeline.py`)
- Context assembly → Vector collections: retrieves candidates
- Vector collections → Volcengine collection: delegates operations (evidence: `openviking/storage/vectordb/collection/collection.py`)
- Vector project → Volcengine collection: constructs collection (evidence: `openviking/storage/vectordb/project/volcengine_project.py`)
- Session service → Namespace identity: resolves namespace (evidence: `openviking/service/session_service.py`)
- Session service → Context namespace: uses identifiers (evidence: `openviking/service/session_service.py`)
- Session training → VLM providers: trains with models
- AI agent → Messaging channels: sends messages
- Messaging channels → VikingBot agent: dispatches messages
- VikingBot agent → Bot sessions: uses sessions (evidence: `bot/vikingbot/session/manager.py`)
- VikingBot agent → Context compilation: invokes compilation (evidence: `README.md`)
