DEV Community

Cover image for OpenViking: Was ist das? Die ultimative Erklärung
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

OpenViking: Was ist das? Die ultimative Erklärung

TL;DR

OpenViking ist eine Open-Source-Kontextdatenbank für KI-Agenten, die das flache Vektorspeichern durch ein Dateisystem-Paradigma ersetzt. Kontext (Erinnerungen, Ressourcen, Fähigkeiten) wird hierarchisch unter viking://-URIs organisiert: L0 (~100 Tokens), L1 (~2k Tokens), L2 (vollständiger Inhalt). Benchmarks zeigen 91 % weniger Token-Kosten und 43 % bessere Aufgabenerfüllung als klassisches RAG.

Probiere Apidog noch heute aus

Einführung

Ihr KI-Agent vergisst ständig Dinge: Doppelte API-Requests, ignorierte Präferenzen, verlorene Testergebnisse. Das ist Standard bei heutigen Agenten. Die meisten Teams basteln RAG-Pipelines, Vektordatenbanken und eigene Speicherlösungen zusammen – mit fragmentiertem Kontext, explodierenden Token-Kosten und fehleranfälligem Retrieval als Resultat.

Daten aus LoCoMo10-Benchmarks bestätigen: Traditionelle RAG-Systeme erreichen nur 35–44 % Aufgabenabschluss und verbrauchen 24–51 Millionen Tokens.

OpenViking verfolgt einen anderen Ansatz: Statt flacher Vektorspeicherung wird der gesamte Kontext als hierarchisches Dateisystem unter viking:// (L0/L1/L2) abgelegt. Das Ergebnis: 52 % Aufgabenabschluss bei 91 % weniger Tokens.

💡 Apidog-User, die API-Testagenten entwickeln, können OpenViking zur Kontextpersistenz, Speicherung von Umgebungseinstellungen und semantischen Suche in API-Dokumentationen nutzen.

In diesem Leitfaden lernst du praxisnah, wie OpenViking Kontextfragmentierung löst, das L0/L1/L2-Modell funktioniert und wie du deinen ersten Server in 15 Minuten startest.

Das Agenten-Kontextproblem

KI-Agenten kämpfen mit Kontextproblemen, die klassische Software nicht kennt.

Praxisbeispiel: Ein Agent unterstützt API-Tests und muss dauerhaft verfolgen:

  • Benutzereinstellungen („Staging-Umgebung“, „curl statt Python“)
  • Projektkontext (Endpunkte, Authentifizierungsmethoden, Testergebnisse)
  • Tool-Muster (häufige Fehler, fehlerhafte Endpunkte)
  • Aufgabenhistorie (getestete Fälle, Fehler, Zeitpunkte)

Klassisches RAG speichert das als flache Chunks in einer Vektordatenbank und liefert Top-K ähnliche Fragmente – aber ohne Struktur, Hierarchie oder Nachvollziehbarkeit.

Fünf Kernherausforderungen

OpenViking adressiert diese Probleme systematisch:

Herausforderung Traditionelles RAG OpenViking-Lösung
Fragmentierter Kontext Erinnerungen, Ressourcen, Fähigkeiten getrennt Vereinheitlichtes Dateisystem viking://
Steigende Nachfrage Lange Aufgaben erzeugen massiven Kontext Hierarchisches L0/L1/L2, 91 % weniger Tokens
Schlechte Retrieval Flache Vektorsuche, keine Übersicht Rekursive Retrieval mit Intent-Analyse
Nicht beobachtbar Black-Box Retrieval Visualisierte Suchverläufe/Spuren
Begrenzte Iteration Nur Interaktionshistorie Automatisierte Sitzungsverwaltung, 6 Kategorien

Fokuswechsel: Von „alles speichern, vage abrufen“ hin zu „strukturiert speichern, präzise abrufen“.

Was ist OpenViking?

OpenViking ist eine Open-Source-Kontextdatenbank für KI-Agenten (Apache 2.0).

OpenViking Architektur

OpenViking vereint Kontext in einem virtuellen Dateisystem. Erinnerungen, Ressourcen, Fähigkeiten sind als Verzeichnisse unter viking://-URIs organisiert:

viking://
├── resources/            # Wissen: Doku, Code, Webseiten
│   ├── my_project/
│   │   ├── docs/
│   │   │   ├── api/
│   │   │   └── tutorials/
│   │   └── src/
│   └── ...
├── user/                 # Benutzereinstellungen, Erinnerungen
│   └── memories/
│       ├── preferences/
│       │   ├── writing_style
│       │   └── coding_habits
│       └── ...
└── agent/                # Agentenfähigkeiten, Skills
    ├── skills/
    │   ├── search_code
    │   ├── analyze_data
    │   └── ...
    ├── memories/
    └── instructions/
Enter fullscreen mode Exit fullscreen mode

API-Funktionen für Agenten:

  • Verzeichnisse navigieren: ls viking://resources/my_project/docs/
  • Semantisch suchen: find "authentication methods"
  • Vollständigen Inhalt lesen: read viking://resources/docs/auth.md
  • Zusammenfassungen holen: abstract viking://resources/docs/

Analogie: Nicht mehr „Festplatte blind durchsuchen“, sondern zielgenau navigieren.

Kernfunktion 1: Dateisystem-Management-Paradigma

Alle Kontexttypen werden im selben Modell gespeichert.

Drei Kontexttypen

Typ Zweck Lebenszyklus Initiative
Ressource Externes Wissen (Doku, Code, FAQ) Langfristig, statisch Benutzer fügt hinzu
Erinnerung Kognition/Präferenzen Langfristig, dynamisch Agent extrahiert
Fähigkeit Tools/Skills Langfristig, statisch Agent ruft auf

Verzeichnisstruktur:

  • viking://resources/ – Produkthandbücher, Code, Doku
  • viking://user/memories/ – Einstellungen, Entitäten, Events
  • viking://agent/skills/ – Tool-Definitionen, Konfigurationen
  • viking://agent/memories/ – Gelernte Muster, Cases

Unix-ähnliche API 

from openviking import OpenViking

client = OpenViking(path="./data")

# Semantische Suche
results = client.find("user authentication")

# Verzeichnisinhalt listen
contents = client.ls("viking://resources/")

# Datei lesen
doc = client.read("viking://resources/docs/auth.md")

# L0-Zusammenfassung
abstract = client.abstract("viking://resources/docs/")

# L1-Übersicht
overview = client.overview("viking://resources/docs/")
Enter fullscreen mode Exit fullscreen mode

API ist per Python SDK oder HTTP nutzbar und mit allen Agenten-Frameworks kompatibel.

Kernfunktion 2: Hierarchisches L0/L1/L2-Laden von Kontext

Großer Kontext in Prompts ist teuer. OpenViking verarbeitet alles automatisch in drei Ebenen:

Ebene Name Datei Token-Limit Zweck
L0 Abstrakt .abstract.md ~100 Vektorsuche, Filterung
L1 Übersicht .overview.md ~2k Navigation, Abschnittsübersicht
L2 Detail Originaldateien unbegrenzt Voller Inhalt, On-Demand

Funktionsweise

Beim Hinzufügen z.B. einer PDF:

  1. Text extrahieren (noch kein LLM-Call)
  2. Verzeichnisstruktur im AGFS anlegen
  3. Semantische Verarbeitung in Queue einreihen
  4. L0/L1 Bottom-up generieren

Beispielstruktur:

viking://resources/my_project/
├── .abstract.md         # L0: Kurzbeschreibung
├── .overview.md         # L1: Übersicht
├── docs/
│   ├── .abstract.md
│   ├── .overview.md
│   ├── auth.md          # L2: Volltext
│   └── ...
Enter fullscreen mode Exit fullscreen mode

Auswirkungen auf das Token-Budget 

# Klassisch: Alles laden (teuer)
full_docs = retrieve_all("authentication")  # 50k tokens

# OpenViking: L1 laden, nur bei Bedarf L2
overview = client.overview("viking://resources/docs/auth/")  # 2k tokens

if needs_more_detail(overview):
    content = client.read("viking://resources/docs/auth/oauth.md")
Enter fullscreen mode Exit fullscreen mode

In Benchmarks: 91 % Tokenersparnis & 43 % höhere Abschlussrate als klassisches RAG.

Kernfunktion 3: Verzeichnisrekursive Retrieval

Klassische Vektorsuche reicht bei komplexen Abfragen nicht aus. OpenViking nutzt einen rekursiven Retrieval-Prozess:

1. Intent-Analyse
   ↓
2. Initiales Positionieren (Verzeichnisse)
   ↓
3. Verfeinerte Suche innerhalb von Verzeichnissen
   ↓
4. Rekursiver Abstieg in Unterverzeichnisse
   ↓
5. Aggregation & Relevanzsortierung
Enter fullscreen mode Exit fullscreen mode

Beispiel: Abfrage „Wie authentifiziere ich Benutzer?“

  • Intent erkannt (How-to)
  • Hoch bewertete Verzeichnisse (viking://resources/docs/auth/)
  • Dateisuche: oauth.md, jwt.md
  • Tiefer gehen in auth/providers/
  • Aggregierte, sortierte Ergebnisse inkl. Retrieval-Trace

Vorteil: Höhere Genauigkeit, da Kontext im Ganzen verstanden wird.

Kernfunktion 4: Visualisierte Retrieval-Spuren

Klassisches RAG ist eine Black Box. OpenViking zeigt, wie Retrieval ablief:

Retrieval-Trace für "OAuth Token-Aktualisierung"

├── viking://resources/docs/
│   ├── [0.45] .abstract.md: übersprungen
│   └── [0.89] auth/: ausgewählt
│       ├── [0.92] oauth.md: ZURÜCKGEGEBEN
│       ├── [0.34] jwt.md: übersprungen
│       └── [0.85] providers/google.md: ZURÜCKGEGEBEN
Enter fullscreen mode Exit fullscreen mode

Nutzen: Sie sehen, was wie ausgewählt/übersprungen wurde – essentiell fürs Debugging.

Kernfunktion 5: Automatische Sitzungsverwaltung

OpenViking hat eine eingebaute Iterationsschleife für Erinnerungen: Nach jeder Sitzung werden automatisch relevante Erinnerungen extrahiert und abgelegt.

Sechs Erinnerungskategorien

Kategorie Eigentümer Ort Beschreibung Aktualisierung
Profil Benutzer user/memories/.overview.md Basisinfos Anhängbar
Präferenzen Benutzer user/memories/preferences/ User-Settings Anhängbar
Entitäten Benutzer user/memories/entities/ Personen, Projekte Anhängbar
Ereignisse Benutzer user/memories/events/ Entscheidungen, Milestones Keine
Fälle Agent agent/memories/cases/ Gelernte Fälle Keine
Muster Agent agent/memories/patterns/ Gelernte Patterns Keine

Erinnerungsextraktion in der Praxis 

# Sitzung starten
session = client.session()

# Nachrichten hinzufügen
await session.add_message("user", [{"type": "text", "text": "Ich bevorzuge Dunkelmodus in der UI"}])
await session.add_message("assistant", [{"type": "text", "text": "Okay, ich nutze Dunkelmodus in Screenshots."}])

# Tool-Nutzung aufzeichnen
await session.add_usage({
    "tool": "screenshot",
    "parameters": {"theme": "dark"},
    "result": "success"
})

# Commit löst Erinnerungsextraktion aus
await session.commit()
Enter fullscreen mode Exit fullscreen mode

Beim Commit werden Sitzungen komprimiert, Erinnerungen per LLM extrahiert und in die passenden Verzeichnisse einsortiert.

Architekturübersicht

OpenViking trennt Inhalt und Index:

Architektur

Ebene Technologie Speichert
AGFS Benutzerdefiniertes FS L0/L1/L2, Multimedia, Relationen
Vektorindex Vektor-DB URIs, Embeddings, Metadaten

Vorteil: Nur Referenzen im Vektorindex, keine doppelten Textblobs.

Schnellstart: OpenViking-Server deployen

Voraussetzungen

  • Python 3.10+
  • Go 1.22+ (für AGFS)
  • C++ Compiler (GCC 9+/Clang 11+)
  • OS: Linux, macOS, Windows

Schritt 1: OpenViking installieren 

pip install openviking --upgrade --force-reinstall
Enter fullscreen mode Exit fullscreen mode

Optional: Rust CLI

curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash
Enter fullscreen mode Exit fullscreen mode

Schritt 2: Modelle konfigurieren

Lege ~/.openviking/ov.conf an:

{
  "storage": {
    "workspace": "/home/your-name/openviking_workspace"
  },
  "log": {
    "level": "INFO",
    "output": "stdout"
  },
  "embedding": {
    "dense": {
      "api_base": "https://api.openai.com/v1",
      "api_key": "your-openai-api-key",
      "provider": "openai",
      "dimension": 3072,
      "model": "text-embedding-3-large"
    },
    "max_concurrent": 10
  },
  "vlm": {
    "api_base": "https://api.openai.com/v1",
    "api_key": "your-openai-api-key",
    "provider": "openai",
    "model": "gpt-4o",
    "max_concurrent": 100
  }
}
Enter fullscreen mode Exit fullscreen mode

Unterstützte Anbieter:

Anbieter Embedding-Modelle VLM-Modelle
volcengine doubao-embedding-vision doubao-seed-2.0-pro
openai text-embedding-3-large gpt-4o, gpt-4-vision
litellm LiteLLM-Proxy Claude, Gemini, DeepSeek, Qwen...

Schritt 3: Server starten 

openviking-server
# oder im Hintergrund
nohup openviking-server > /data/log/openviking.log 2>&1 &
Enter fullscreen mode Exit fullscreen mode

Schritt 4: Erste Ressource hinzufügen 

# Rust CLI
ov add-resource https://docs.example.com/api-guide.pdf

# Python SDK
from openviking import OpenViking
client = OpenViking(path="./data")
client.add_resource("https://docs.example.com/api-guide.pdf")
Enter fullscreen mode Exit fullscreen mode

Schritt 5: Suchen & Abrufen 

# Nach Verarbeitung suchen
ov find "authentication methods"

# Verzeichnisinhalt listen
ov ls viking://resources/

# Verzeichnisbaum anzeigen
ov tree viking://resources/docs -L 2

# Grep-ähnliche Suche
ov grep "OAuth" --uri viking://resources/docs/
Enter fullscreen mode Exit fullscreen mode

Schritt 6: VikingBot aktivieren (optional) 

pip install "openviking[bot]"
openviking-server --with-bot
# In neuem Terminal:
ov chat
Enter fullscreen mode Exit fullscreen mode

Leistungs-Benchmarks

OpenViking wurde mit klassischen RAG-Ansätzen (LanceDB) und nativen Systemen anhand von LoCoMo10 (1.540 Dialogfälle) verglichen.

Aufgabenabschlussraten

System Abschlussrate Eingabe-Tokens
OpenClaw (nativ) 35.65% 24.6M
OpenClaw + LanceDB 44.55% 51.6M
OpenClaw + OpenViking 52.08% 4.3M

Schlüsselergebnisse

  • 43 % mehr Aufgabenabschluss bei 91 % Token-Einsparung ggü. nativ
  • 17 % mehr Abschluss bei 92 % Token-Reduktion ggü. LanceDB
  • Hierarchische Retrieval fand relevantere Kontexte bei geringerem Aufwand

OpenViking mit Apidog integrieren

Apidog-User können OpenViking für persistente Kontexte, Speicherung von API-Dokumentationen und Benutzereinstellungen einsetzen.

Apidog + OpenViking

Schritt 1: OpenViking-Server einrichten

Folge dem Schnellstart weiter oben.

Schritt 2: Apidog API-Doku importieren 

ov add-resource https://docs.apidog.com/overview?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation
ov add-resource https://docs.apidog.com/api-testing?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation
Enter fullscreen mode Exit fullscreen mode

Schritt 3: Benutzereinstellungen speichern 

from openviking import OpenViking

client = OpenViking(path="./apidog-agent-data")
session = client.session()

await session.add_message("user", [{
    "type": "text",
    "text": "Immer die Staging-Umgebung für API-Tests verwenden"
}])
await session.commit()
Enter fullscreen mode Exit fullscreen mode

Schritt 4: Kontext während des Testens abfragen 

# Relevante Endpunkte suchen
results = client.find("authentication endpoints")
for ctx in results.resources:
    print(f"Gefunden: {ctx.uri}")

# Benutzereinstellungen abrufen
prefs = client.find("staging environment preference", target_uri="viking://user/memories/")
Enter fullscreen mode Exit fullscreen mode

Schritt 5: Mit Agenten-Framework verbinden 

# Python SDK
from openviking import OpenViking
client = OpenViking(path="./data")

# HTTP API
import httpx
response = httpx.post(
    "http://localhost:1933/api/v1/search/find",
    json={"query": "authentication endpoints"},
    headers={"X-API-Key": "your-api-key"}
)
Enter fullscreen mode Exit fullscreen mode

Fortgeschrittene Techniken & Best Practices

Profi-Tipps für Produktion

1. Kontext vorwärmen

ov add-resource https://docs.example.com --wait
Enter fullscreen mode Exit fullscreen mode

2. Kontextablauf automatisieren

await session.archive(max_age_days=7)
Enter fullscreen mode Exit fullscreen mode

3. Vektorindex überwachen

ov debug stats
Enter fullscreen mode Exit fullscreen mode

Fehler, die du vermeiden solltest

  1. L2-Inhalte frühzeitig laden: Immer mit L0/L1 starten
  2. Sitzungs-Commits überspringen: Erinnerungen werden nur beim Commit extrahiert
  3. Einzelne Verzeichnisse überladen: Große Ressourcen aufteilen
  4. Retrieval-Spuren ignorieren: Nutze sie aktiv fürs Debugging

Leistungsoptimierung

Szenario Empfehlung
Hohes Abfragevolumen OpenViking als HTTP-Server mit Pooling betreiben
Große Dokumente Vorab in thematische Chunks splitten
Niedrige Latenz L0/L1 für wichtige Inhalte vorab generieren
Multi-Tenant Separate Workspaces pro Tenant

Sicherheit

  • API-Schlüssel als Umgebungsvariable/Secret, nie in Klartext
  • HTTPS für HTTP-Server aktivieren
  • Ratenbegrenzung für Endpunkte
  • Unterschiedliche Keys für Dev/Prod

Praxisbeispiele

1. KI-Codierungsassistenten

  • Navigation über viking://resources/my_project/src/
  • Erinnerung an Coding-Präferenzen
  • Kontextsensitive API-Doku beim Generieren

Effekt: 67 % weniger „Vergesslichkeitsfehler“, 43 % Token-Ersparnis

2. Kundensupport-Agenten

  • Produktdoku unter viking://resources/product/
  • Kundenhistorien unter viking://user/memories/past_issues/
  • Support-Playbooks als Skills

Effekt: Erstkontakt-Lösungsrate von 52 % auf 71 %

3. Forschungsassistenten

  • Papers nach Thema (viking://resources/papers/nlp/)
  • Methoden als Skills
  • Automatische Schlüsselergebnis-Extraktion

Effekt: 3x schnellere Paper-Suche mit Semantik

Alternativen & Vergleiche

OpenViking vs. klassische Vektordatenbanken

Aspekt Traditionelles RAG OpenViking
Speichermodell Flache Vektor-Chunks Hierarchisches Dateisystem
Retrieval Top-K-Ähnlichkeit Verzeichnisrekursiv + Intent
Beobachtbarkeit Black Box Visualisierte Retrieval-Spuren
Token-Effizienz Alles laden/kürzen Progressives L0/L1/L2-Laden
Speicher-Iteration Manuell/keine Automatische Sitzungsverwaltung
Kontexttypen Nur Dokumente Ressourcen, Erinnerungen, Skills
Debugging Raten Verzeichnis-Durchlaufprotokolle

OpenViking vs. LangChain Speicher

Aspekt LangChain Speicher OpenViking
Persistenz Nur Konversationspuffer Komplette FS-Struktur mit L0/L1/L2
Skalierbarkeit Kontextfenster-Limit Hierarchisches Laden, keine harte Grenze
Retrieval Linear Rekursiv, semantisch
Speichertypen Ein Puffer 6 Kategorien (Profil, Präferenzen, ...)

Wann klassische Alternativen sinnvoll sind

Klassische Vektor-DBs verwenden, wenn:

  • Latenz < 100 ms gefordert
  • Simple Keyword-Suche genügt
  • Bestehende RAG-Pipeline funktioniert ohne Probleme

OpenViking verwenden, wenn:

  • Lange, speicherintensive Agenten-Interaktionen
  • Multi-Typ-Kontext nötig (Doku, Präferenzen, Tools)
  • Token-Kosten entscheidend sind
  • Debugbare, nachvollziehbare Retrieval nötig

Produktionsbereitstellung

Empfohlene Infrastruktur:

  • Cloud: Volcengine ECS o. Ä.
  • OS: veLinux oder Ubuntu 22.04+
  • Speicher: SSD-Volume für AGFS
  • Netzwerk: Latenzarm zu Modell-APIs

Sicherheitsüberlegungen:

  • API-Keys als ENV/Secret Manager
  • Auth für HTTP-Endpunkte aktivieren
  • HTTPS für Kommunikation
  • Ratenbegrenzung gegen Missbrauch

Überwachung:

{
  "log": {
    "level": "INFO",
    "output": "file",
    "path": "/var/log/openviking/server.log"
  }
}
Enter fullscreen mode Exit fullscreen mode

Überwache:

  • Queue-Tiefe für semantische Verarbeitung
  • Vektorsuch-Latenz
  • AGFS IO
  • Erfolgsrate Erinnerungsextraktion

Einschränkungen & Überlegungen

Aktuelle Einschränkungen

  • Fokus auf Python (andere Sprachen via HTTP)
  • Abhängigkeit von externen VLM-/Embedding-Modellen
  • Lernkurve wegen Dateisystem-Paradigma
  • APIs in Entwicklung, Änderungen möglich

Wann OpenViking nutzen?

Geeignet für:

  • Lang laufende Agenten-Konversationen mit Speicherbedarf
  • Multi-Typ-Kontext (Doku, Präferenzen, Tools)
  • Debugbare Retrieval erforderlich
  • Token-Kostenoptimierung

Alternativen besser bei:

  • Simpler One-Shot-Q&A
  • Funktionierende RAG-Pipeline ohne Pain Points
  • Retrieval-Latenz < 100 ms zwingend

Der Weg nach vorn

OpenViking ist noch jung (v0.1.x, Anfang 2025). Geplante Features:

  • Multi-Tenant: Isolierte Workspaces
  • Analysen: Retrieval-Metriken, Nutzungs-Dashboards
  • Plugin-Ökosystem: Integrationen mit Agenten-Frameworks
  • Edge-Betrieb: Lightweight-Modus
  • MCP-Support: Model Context Protocol nativ

Community-Contributions sind willkommen. Open Source: Projektseite.

Fazit

OpenViking ist ein Paradigmenwechsel für Agenten-Kontextmanagement. Informationsorganisation als Dateisystem beseitigt Fragmentierung, Token-Verschwendung und Black-Box-Retrieval klassischer RAG-Systeme.

Wichtigste Learnings

  • Dateisystem-Paradigma: Kontext unter viking://-URIs für Erinnerungen, Ressourcen, Skills
  • L0/L1/L2: 91 % Token-Einsparung durch progressives Laden
  • Verzeichnisrekursive Retrieval: Genauigkeit steigt durch strukturierte Suche
  • Visualisierte Spuren: Debugging und Nachvollziehbarkeit
  • Automatische Sitzungsverwaltung: Agent lernt aus jeder Interaktion

Top comments (0)