CubeLabs

1. El problema del contexto en los agentes

Cuando construyes agentes de IA te topas con cinco dolores constantes:

OpenViking ataca exactamente estos puntos con un cambio de paradigma: en lugar de una base de datos plana, todo el contexto se organiza como un sistema de archivos virtual con URIs deterministas (viking://), capas de resumen L0/L1/L2 y recuperación por directorios que deja una trayectoria auditable.

2. Arquitectura: el contexto como filesystem

OpenViking es una base de datos de contexto: unifica memoria, recursos y skills bajo un mismo árbol viking://.

viking://
├── resources/              # Recursos: docs de proyecto, repos, webs
│   └── my_project/
├── user/
│   └── {user_id}/          # Contexto privado del usuario
│       ├── memories/       # Memorias del usuario
│       ├── resources/      # Recursos privados
│       ├── skills/         # Skills privadas
│       └── peers/
└── agent/
    └── skills/             # Skills compartidas de la cuenta

La arquitectura interna separa la lógica en módulos claros:

El flujo de escritura es Input → Parser → TreeBuilder → AGFS → SemanticQueue → Vector Index. El flujo de lectura es Query → Intent Analysis → Hierarchical Retrieval → Rerank → Results.

3. Instalación y configuración

Requisitos: Python 3.10+. Puedes instalarlo como paquete Python o levantarlo con Docker.

Opción A: paquete Python

pip install openviking --upgrade
# o con uv (recomendado)
uv tool install openviking --upgrade

Tras instalar, tienes dos comandos: ov (cliente) y openviking-server (servidor).

Opción B: Docker Compose

mkdir -p ~/.openviking && touch ~/.openviking/ov.conf
# docker-compose.yml
services:
  openviking:
    image: ghcr.io/volcengine/openviking:latest
    ports:
      - "1933:1933"
    volumes:
      - ~/.openviking:/app/.openviking
    restart: unless-stopped

Configuración con init y doctor

Necesitas dos capacidades de modelo: un VLM (para entender imágenes y contenido) y un embedding (para vectorización). El config mínimo es:

{
  "embedding": {
    "dense": {
      "provider": "volcengine",
      "model": "doubao-embedding-vision-251215",
      "api_base": "https://ark.cn-beijing.volces.com/api/v3",
      "api_key": "<tu-ark-api-key>",
      "dimension": 1024,
      "input": "multimodal"
    }
  },
  "vlm": {
    "provider": "volcengine",
    "model": "doubao-seed-2-0-code-preview-260215",
    "api_base": "https://ark.cn-beijing.volces.com/api/v3",
    "api_key": "<tu-ark-api-key>",
    "temperature": 0
  },
  "storage": { "workspace": "./data" },
  "server": { "host": "127.0.0.1", "port": 1933 }
}

4. La CLI ov en acción

Con el servidor corriendo, la CLI ov te da control total del contexto:

$ ov status
# servidor conectado, health OK
$ ov add-resource https://github.com/volcengine/OpenViking --wait
$ ov ls viking://resources/
$ ov tree viking://resources/volcengine -L 2
$ ov find "what is openviking"
$ ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/en

El árbol de comandos cubre todo el ciclo de vida:

add-resource acepta URLs, ficheros locales, directorios, repos Git, sitemaps y RSS. El parámetro --wait espera a que termine el procesamiento semántico antes de devolver el control.

5. Tipos de contexto: recursos, memoria y skills

OpenViking abstrae todo el contexto en tres tipos básicos:

Las memorias tienen tipos integrados que se escriben en el namespace del usuario:

Una skill se guarda como directorio con su SKILL.md:

viking://user/skills/search-web/
├── .abstract.md          # L0: descripción corta
├── .overview.md          # L1: resumen del directorio
├── SKILL.md              # L2: definición de la skill
└── scripts               # L2: implementación

6. Capas L0/L1/L2: contexto progresivo

Meter todo el contexto en el prompt es caro y ruidoso. OpenViking procesa cada directorio en tres niveles:

viking://resources/docs/auth/
├── .abstract.md          # L0: "Guía de autenticación: OAuth 2.0, JWT y API keys"
├── .overview.md          # L1: estructura y puntos clave del directorio
├── oauth.md              # L2: contenido completo
├── jwt.md                # L2: contenido completo
└── api-keys.md           # L2: contenido completo

L0 y L1 son sidecars de directorio (no por archivo). El generador semántico procesa de abajo arriba: resúmenes de archivos → L1 hoja → L0 hoja → directorios padre. El ls normal los oculta, pero los accessors los leen:

ov abstract viking://resources/docs/auth
ov overview viking://resources/docs/auth
ov read viking://resources/docs/auth/oauth.md

La estrategia recomendada: para comprobar relevancia usa L0; para entender el alcance de un directorio, L1; y solo cuando haga falta, carga L2. Así construyes el contexto inicial del LLM con L1 y profundizas bajo demanda.

7. Recuperación: find, search e intención

OpenViking usa recuperación en dos fases: análisis de intención + recuperación jerárquica + rerank. Tiene dos APIs principales:

El análisis de intención convierte la consulta en TypedQueries tipadas por contexto:

# Skill: verbo primero → "Crear documento RFC", "Extraer tablas de PDF"
# Resource: sintagma nominal → "Plantilla de documento RFC"
# Memory: "preferencias de X del usuario" → "Preferencias de estilo de código del usuario"

La recuperación jerárquica funciona con una cola de prioridad: primero localiza los directorios con mayor score, luego desciende recursivamente propagando el score del padre (parámetro score_propagation_alpha), y converge cuando el top-k no cambia en 3 rondas.

# find(): consulta simple
ov find "OAuth authentication" --uri viking://resources/

# search(): tarea compleja con contexto de sesión
ov search "Ayúdame a crear un documento RFC" --session-id chat_001

El rerank se activa en modo THINKING (por defecto en search()) cuando hay credenciales configuradas; si falla, cae a los scores vectoriales. La gran ventaja: cada consulta conserva su trayectoria de navegación, así que cuando un resultado es raro puedes ver exactamente qué camino lo produjo.

8. Sesiones: de la conversación a la memoria

El ciclo de vida de una sesión es Create → Interact → Commit. Al hacer commit, OpenViking comprime, archiva y extrae memoria a largo plazo en segundo plano.

from openviking_sdk import SyncHTTPClient, TextPart, ContextPart

client = SyncHTTPClient(url="http://localhost:1933")
client.initialize()

session = client.session(session_id="chat_001")
session.add_message("user", [TextPart("Prefiero el modo oscuro")])
session.add_message("assistant", [
    TextPart("Entendido, lo recordaré."),
    ContextPart(uri="viking://user/memories/profile.md"),
])
session.used(contexts=["viking://user/memories/profile.md"])

result = session.commit()          # devuelve task_id, archiva al momento
task = client.get_task(result["task_id"])  # poll hasta "completed"

El commit tiene dos fases:

El flujo de extracción de memoria es: Mensajes → LLM Extract → Candidatos → Pre-filtro vectorial → Decisión de deduplicación → Write AGFS + vectorizar. La deduplicación decide entre skip, create, merge o delete de memorias existentes, así que no se acumulan duplicados.

9. Integraciones: Claude Code, MCP y LangChain

OpenViking se conecta a casi cualquier agente. La vía más universal es su endpoint MCP integrado (/mcp), compatible con Cursor, Trae, Claude Desktop, ChatGPT y más:

{
  "mcpServers": {
    "openviking": {
      "url": "https://tu-servidor.com/mcp",
      "headers": { "Authorization": "Bearer tu-api-key" }
    }
  }
}

Para Claude Code, el plugin de memoria inyecta recuerdo automático en cada prompt y hace commit de la sesión antes de la compactación:

bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh)

El plugin conecta además el /mcp de OpenViking, exponiendo herramientas como find, search, read y remember. Con LangChain/LangGraph, usa el paquete independiente:

pip install langchain-openviking                 # adaptadores LangChain
pip install "langchain-openviking[langgraph]"    # middleware LangGraph

from langchain_openviking import create_openviking_tools, OpenVikingRetriever, with_openviking_context

# Herramientas explícitas para el agente
tools = create_openviking_tools(url="http://localhost:1933", profile="agent")
# viking_find, viking_search, viking_browse, viking_read, viking_grep, viking_store...

# Retriever RAG
retriever = OpenVikingRetriever(url="http://localhost:1933")
docs = retriever.invoke("¿Qué decidió el usuario sobre el despliegue?")

# Backend de contexto con ciclo de vida completo
with with_openviking_context(runnable, url="http://localhost:1933") as chain:
    result = chain.invoke({"messages": [...]})

Otras integraciones nativas: Hermes Agent (hermes memory setup openviking), Codex (plugin de memoria con hooks), OpenClaw, Cursor, OpenCode y TRAE.

10. VikingBot y despliegue en producción

VikingBot es un framework de agente construido sobre OpenViking. Con un comando tienes un agente que chatea con memoria persistente:

pip install "openviking[bot]"
openviking-server --with-bot
# en otro terminal
ov chat

La imagen Docker oficial incluye VikingBot y arranca el servidor + consola por defecto (desactívalo con command: ["--without-bot"] si no lo necesitas).

Despliegue en producción

La edición open-source no está limitada: AGPLv3 sin feature gates, sin cuenta y sin claves de activación. Los benchmarks oficiales (LoCoMo y tau2-bench) muestran que con OpenViking la precisión de memoria de agentes como OpenClaw, Hermes o Claude Code sube de 24–57% a 80–83%, con menos tokens.