Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""Unified context class for OpenViking."""
from datetime import datetime, timezone
from enum import Enum
from typing import Any, Dict, List, Optional
from uuid import uuid4
from openviking.core.namespace import context_type_for_uri, owner_fields_for_uri
from openviking.utils.time_utils import format_iso8601, parse_iso_datetime
from openviking_cli.session.user_id import UserIdentifier
from openviking_cli.utils.uri import VikingURI
class ResourceContentType(str, Enum):
"""Resource content type"""
TEXT = "text"
IMAGE = "image"
VIDEO = "video"
AUDIO = "audio"
BINARY = "binary"
class ContextType(str, Enum):
"""Context type"""
SKILL = "skill"
MEMORY = "memory"
RESOURCE = "resource"
class ContextLevel(int, Enum):
"""Context level (L0/L1/L2) for vector indexing"""
ABSTRACT = 0 # L0: abstract
OVERVIEW = 1 # L1: overview
DETAIL = 2 # L2: detail/content
class Vectorize:
text: str = ""
# images: list of image references (data URIs or URLs) for multimodal embedding
images: List[str] = []
# video: str = ""
# audio: str = ""
def __init__(
self,
text: str = "",
images: Optional[List[str]] = None,
):
self.text = text
self.images = list(images) if images else []
class Context:
"""
Unified context class for all context types in OpenViking.
"""
def __init__(
self,
uri: str,
parent_uri: Optional[str] = None,
temp_uri: Optional[str] = None,
is_leaf: bool = False,
abstract: str = "",
context_type: Optional[str] = None,
category: Optional[str] = None,
created_at: Optional[datetime] = None,
updated_at: Optional[datetime] = None,
active_count: int = 0,
related_uri: Optional[List[str]] = None,
meta: Optional[Dict[str, Any]] = None,
level: int | ContextLevel | None = None,
session_id: Optional[str] = None,
user: Optional[UserIdentifier] = None,
account_id: Optional[str] = None,
owner_user_id: Optional[str] = None,
owner_space: Optional[str] = None,
md5: Optional[str] = None,
id: Optional[str] = None,
):
"""
Initialize a Context object.
"""
self.id = id or str(uuid4())
self.uri = uri
self.parent_uri = parent_uri
self.temp_uri = temp_uri
self.is_leaf = is_leaf
self.abstract = abstract
self.context_type = context_type or context_type_for_uri(uri)
self.category = category or self._derive_category()
self.created_at = created_at or datetime.now(timezone.utc)
self.updated_at = updated_at or self.created_at
self.active_count = active_count
self.related_uri = related_uri or []
self.meta = meta or {}
try:
self.level = int(level) if level is not None else None
except (TypeError, ValueError):
self.level = None
self.session_id = session_id
self.user = user
self.account_id = account_id or (user.account_id if user else "default")
owner_fields = owner_fields_for_uri(uri)
self.owner_user_id = (
owner_user_id if owner_user_id is not None else owner_fields["owner_user_id"]
)
self.owner_space = owner_space or owner_fields["owner_user_id"] or ""
# md5 of the final stored bytes for this URI; None/"" means unknown (old
# records or non-file records), and incremental diff falls back to reading
# bytes rather than assuming equality.
self.md5 = md5 or ""
self.vector: Optional[List[float]] = None
self.vectorize = Vectorize(abstract)
def _derive_category(self) -> str:
"""Derive category from URI using substring matching."""
if "/patterns" in self.uri:
return "patterns"
elif "/cases" in self.uri:
return "cases"
elif "/profile" in self.uri:
return "profile"
elif "/preferences" in self.uri:
return "preferences"
elif "/entities" in self.uri:
return "entities"
elif "/events" in self.uri:
return "events"
return ""
def get_context_type(self) -> str:
"""Get the type of this context (alias for context_type)."""
return self.context_type
def set_vectorize(self, vectorize: Vectorize):
self.vectorize = vectorize
def get_vectorization_text(self) -> str:
"""Get text for vectorization."""
return self.vectorize.text
def get_vectorization_images(self) -> List[str]:
"""Get image references (data URIs or URLs) for multimodal vectorization."""
return self.vectorize.images
def to_dict(self) -> Dict[str, Any]:
"""Convert context to dictionary format for storage."""
created_at_str = format_iso8601(self.created_at) if self.created_at else None
updated_at_str = format_iso8601(self.updated_at) if self.updated_at else None
data = {
"id": self.id,
"uri": self.uri,
"parent_uri": self.parent_uri,
"temp_uri": self.temp_uri,
"is_leaf": self.is_leaf,
"abstract": self.abstract,
"context_type": self.context_type,
"category": self.category,
"created_at": created_at_str,
"updated_at": updated_at_str,
"active_count": self.active_count,
"vector": self.vector,
"meta": self.meta,
"related_uri": self.related_uri,
"session_id": self.session_id,
"account_id": self.account_id,
"owner_user_id": self.owner_user_id,
"owner_space": self.owner_space,
}
if self.level is not None:
data["level"] = int(self.level)
# Only emit md5 when known so we never overwrite an existing fingerprint
# with an empty string via partial update.
if self.md5:
data["md5"] = self.md5
if self.user:
data["user"] = self.user.to_dict()
# Add skill-specific fields from meta
if self.context_type == "skill":
data["name"] = self.meta.get("name", "")
data["description"] = self.meta.get("description", "")
return data
@staticmethod
def _derive_parent_uri(uri: str) -> Optional[str]:
"""Best-effort parent URI derivation for records persisted without parent_uri."""
try:
parent = VikingURI(uri).parent
except Exception:
return None
return parent.uri if parent else None
@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "Context":
"""Create a context object from dictionary."""
user_data = data.get("user")
user_obj = UserIdentifier.from_dict(user_data) if isinstance(user_data, dict) else user_data
obj = cls(
uri=data["uri"],
parent_uri=data.get("parent_uri") or cls._derive_parent_uri(data["uri"]),
temp_uri=data.get("temp_uri"),
is_leaf=data.get("is_leaf", False),
abstract=data.get("abstract", ""),
context_type=data.get("context_type"),
category=data.get("category"),
created_at=(
parse_iso_datetime(data["created_at"])
if isinstance(data.get("created_at"), str)
else data.get("created_at")
),
updated_at=(
parse_iso_datetime(data["updated_at"])
if isinstance(data.get("updated_at"), str)
else data.get("updated_at")
),
active_count=data.get("active_count", 0),
related_uri=data.get("related_uri", []),
meta=data.get("meta", {}),
level=(
data.get("level")
if data.get("level") is not None
else data.get("meta", {}).get("level")
if isinstance(data.get("meta"), dict)
else None
),
session_id=data.get("session_id"),
user=user_obj,
account_id=data.get("account_id"),
owner_user_id=data.get("owner_user_id"),
owner_space=data.get("owner_space"),
md5=data.get("md5"),
)
obj.id = data.get("id", obj.id)
obj.vector = data.get("vector")
return obj