Context Types

OpenViking manages three types of context: resources provide reference material, memories retain information from interactions, and skills describe how to carry out tasks.

Overview

Type	Purpose	Lifecycle	Initiative
Resource	Knowledge and rules	Retained until updated or deleted	User adds
Memory	Preferences, facts, and task experience	Long-term, dynamically updated	Extracted from sessions or recorded explicitly
Skill	Task instructions and supporting resources	Long-term, updatable	User or system adds

Example Setup

The examples below use the synchronous Python SDK and an existing server. add_resource and add_skill take wait=True to block until processing finishes. Session commits return before memory extraction finishes and have no built-in wait, so this helper polls the commit task before dependent searches. A polling timeout does not cancel the server task.

import time
from openviking_sdk import SyncHTTPClient

client = SyncHTTPClient(url="http://localhost:1933", api_key="your-key")


def wait_for_task(task_id):
    deadline = time.monotonic() + 300
    while time.monotonic() < deadline:
        task = client.get_task(task_id)
        if task is None:
            raise RuntimeError(f"Task {task_id} not found")
        if task["status"] == "completed":
            return task
        if task["status"] in {"failed", "cancelled"}:
            raise RuntimeError(task)
        time.sleep(1)
    raise TimeoutError(f"Task {task_id} is still running")

Resource

Resources are external knowledge that Agents can reference.

Characteristics

• User-driven: Resource information actively added by users to supplement LLM knowledge, such as product manuals and code repositories
• Explicit updates: Re-import changed content, or use a Watch to refresh supported remote sources
• Structured storage: Organized by project or topic in directory hierarchy, with multi-layer information extraction

Examples

• API docs, product manuals
• FAQ databases, code repositories
• Research papers, technical specs

Usage

# Add resource
client.add_resource(
    path="https://docs.example.com/api.pdf",
    options={"reason": "API documentation"},
    wait=True,
    timeout=300,
)

# Search resources
results = client.find(
    query="authentication methods",
    target_uri="viking://resources/",
)

Memory

Memories are durable knowledge learned from interactions and task execution. They are stored in the current User or Peer namespace, not in a separate viking://agent/memories directory.

Characteristics

• Agent-driven: Memory information actively extracted and recorded by Agent
• Dynamic updates: Continuously updated from interactions by Agent
• Personalized: Learned for specific users and stable peers

Built-in Memory Types

Type	Default location	Description
profile	~/memories/profile.md	Basic user information
preferences	~/memories/preferences/	User preferences organized by topic
entities	~/memories/entities/	Knowledge about people, projects, organizations, and other entities
events	~/memories/events/	Decisions, milestones, and other event records
identity	~/memories/identity.md	Assistant name, persona, temperament, and self-introduction
soul	~/memories/soul.md	Assistant principles, boundaries, style, and continuity
cases	~/memories/cases/	Task cases used for training and evaluation
trajectories	~/memories/trajectories/	Reusable task-execution trajectories
experiences	~/memories/experiences/	Reusable experience distilled from execution outcomes

The ~/... entries above use the home alias viking://~, which the server expands to viking://user/{user_id}/... for the authenticated caller. When the memory policy permits Peer memory, supported types may instead be written under viking://user/{user_id}/peers/{peer_id}/memories/.... Applications can extend or adjust memory types with custom templates.

The schema-defined memories/tools/ and memories/skills/ types are disabled. They are separate from standalone Skills stored under viking://user/{user_id}/skills/{skill_name}/SKILL.md, which remain supported.

Usage

from openviking_sdk import TextPart

# Memories are auto-extracted from sessions
session_info = client.create_session()
session = client.session(session_id=session_info["session_id"])
session.add_message(
    role="user",
    parts=[TextPart(text="I prefer dark mode")],
)
commit = session.commit()  # Starts background memory extraction
if commit.get("task_id"):
    wait_for_task(commit["task_id"])

# Search memories
results = client.find(
    query="UI preferences",
    target_uri="viking://~/memories/"
)

Skill (Capabilities / AgentDefinedContextType)

A Skill uses SKILL.md and supporting files to describe a task’s steps, constraints, and resources. An agent reads the Skill and carries out the task using its own tools. Execution experience can be stored separately as memory.

Characteristics

• Task instructions: Steps and constraints for completing a type of work
• Maintainable: Skill content can be updated; execution experience is stored separately
• Read on demand: The agent selects skills for its current task

Storage Location

viking://~/skills/{skill-name}/     # Default storage path
├── .abstract.md          # L0: Short description
├── .overview.md          # L1: Directory overview (after generation)
├── SKILL.md              # L2: Skill definition
└── scripts               # L2: Supporting implementation

viking://agent/skills/{skill-name}/    # Override via -p/--parent-auto-create, public/shared (account global)
├── .abstract.md          # L0: Short description
├── .overview.md          # L1: Directory overview (after generation)
├── SKILL.md              # L2: Skill definition
└── scripts               # L2: Supporting implementation

AgentDefinedContextType Subtypes

The table below lists the design categories for shared capabilities. Skills are supported and installed in the user-private directory by default, with an option to use viking://agent/skills/. The other categories are planned and do not imply available APIs:

Subtype	Location	Description
Skill	agent/skills/	Traditional workflow definitions, such as search and code generation
Endpoint	agent/endpoints/	Communication endpoint configuration (a2a, anp, etc.) (planned)
Tool	agent/tools/	Tool configuration (mcp, etc.) (planned)
Payment	agent/payments/	Payment capability configuration (ap2, etc.) (planned)

Usage

# Add skill (defaults to viking://~/skills/)
client.add_skill(
    data={
        "name": "search-web",
        "description": "Search the web for information",
        "content": "# search-web\n...",
    },
    wait=True,
    timeout=300,
)

# Search user skills
results = client.find(
    query="web search",
    target_uri="viking://~/skills/"
)

# Search global agent skills
results = client.find(
    query="web search",
    target_uri="viking://agent/skills/",
)

Install into the account-shared skills directory with the CLI (requires write access to that path):

ov skills add ./skills/search-web -p viking://agent/skills

Unified Search

A single retrieval can return resources, memories, and skills within its search scope. The default includes the current user's space and shared resources; add viking://agent/skills explicitly to include shared Skills:

# Search across all context types
results = client.find(
    query="user authentication",
    target_uri=["viking://~", "viking://resources", "viking://agent/skills"],
)

for context in results.get("memories", []):
    print(f"Memory: {context['uri']}")
for context in results.get("resources", []):
    print(f"Resource: {context['uri']}")
for context in results.get("skills", []):
    print(f"Skill: {context['uri']}")

Close the client when these operations are finished:

client.close()

Related Documents

• Architecture Overview - System architecture
• Context Layers - L0/L1/L2 model
• Viking URI - URI specification
• Session Management - Memory extraction mechanism