Viking URI

Viking URI

Viking URI is the unified resource identifier for all content in OpenViking.

Format

viking://{scope}/{path}

• scheme: Always viking
• scope: Top-level namespace (resources, user, agent, session, queue)
• path: Resource path within the scope

Scopes

Initial Directory Structure

Moving away from traditional flat database thinking, all context is organized as a filesystem. Agents no longer just find data through vector search, but can locate and browse data through deterministic paths and standard filesystem commands. Each context or directory is assigned a unique URI identifier string in the format viking://{scope}/{path}, allowing the system to precisely locate and access resources stored in different locations.

viking://
├── session/{session_id}/
│   ├── .abstract.md          # L0: One-line session summary
│   ├── .overview.md          # L1: Session overview
│   ├── .meta.json            # Session metadata
│   ├── messages.json         # Structured message storage
│   ├── checkpoints/          # Version snapshots
│   ├── summaries/            # Compression summary history
│   └── .relations.json       # Relations table
│
├── user/
│   ├── .abstract.md          # L0: Content summary
│   ├── .overview.md          # User profile
│   └── memories/             # User memory storage
│       ├── .overview.md      # Memory overview
│       ├── preferences/      # User preferences
│       ├── entities/         # Entity memories
│       └── events/           # Event records
│
├── agent/
│   ├── .abstract.md          # L0: Content summary
│   ├── .overview.md          # Agent overview
│   ├── memories/             # Agent learning memories
│   │   ├── .overview.md
│   │   ├── cases/            # Cases
│   │   └── patterns/         # Patterns
│   ├── instructions/         # Agent instructions
│   └── skills/               # Skills directory
│
└── resources/{project}/      # Resource workspace

URI Examples

Resources

viking://resources/                           # All resources
viking://resources/my-project/                # Project root
viking://resources/my-project/docs/           # Docs directory
viking://resources/my-project/docs/api.md     # Specific file

User Data

viking://user/                                # User root
viking://user/memories/                       # All user memories
viking://user/memories/preferences/           # User preferences
viking://user/memories/preferences/coding     # Specific preference
viking://user/memories/entities/              # Entity memories
viking://user/memories/events/                # Event memories

Agent Data

viking://agent/                               # Agent root
viking://agent/skills/                        # All skills
viking://agent/skills/search-web              # Specific skill
viking://agent/memories/                      # Agent memories
viking://agent/memories/cases/                # Learned cases
viking://agent/memories/patterns/             # Learned patterns
viking://agent/instructions/                  # Agent instructions

Session Data

viking://session/{session_id}/                # Session root
viking://session/{session_id}/messages/       # Session messages
viking://session/{session_id}/tools/          # Tool executions
viking://session/{session_id}/history/        # Archived history

Directory Structure

viking://
├── resources/                    # Independent resources
│   └── {project}/
│       ├── .abstract.md
│       ├── .overview.md
│       └── {files...}
│
├── user/
│   ├── profile.md              # User basic info
│   └── memories/
│       ├── preferences/          # By topic
│       ├── entities/             # Each independent
│       └── events/               # Each independent
│
├── agent/
│   ├── skills/                   # Skill definitions
│   ├── memories/
│   │   ├── cases/
│   │   └── patterns/
│   └── instructions/
│
└── session/{session_id}/
    ├── messages/
    ├── tools/
    └── history/

URI Operations

Parsing

from openviking.utils.uri import VikingURI

uri = VikingURI("viking://resources/docs/api")
print(uri.scope)      # "resources"
print(uri.full_path)  # "resources/docs/api"

Building

# Join paths
base = "viking://resources/docs/"
full = VikingURI(base).join("api.md").uri  # viking://resources/docs/api.md

# Parent directory
uri = "viking://resources/docs/api.md"
parent = VikingURI(uri).parent.uri  # viking://resources/docs

API Usage

Targeting Specific Scopes

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

# Search only in user memories
results = client.find(
    "coding preferences",
    target_uri="viking://user/memories/"
)

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

File System Operations

# List directory
entries = await client.ls("viking://resources/")

# Read file
content = await client.read("viking://resources/docs/api.md")

# Get abstract
abstract = await client.abstract("viking://resources/docs/")

# Get overview
overview = await client.overview("viking://resources/docs/")

Special Files

Each directory may contain special files:

Best Practices

Use Trailing Slash for Directories

# Directory
"viking://resources/docs/"

# File
"viking://resources/docs/api.md"

Scope-Specific Operations

# Add resources only to resources scope
await client.add_resource(url, target="viking://resources/project/")

# Skills go to agent scope
await client.add_skill(skill)  # Automatically to viking://agent/skills/

Related Documents

• Architecture Overview - System architecture
• Context Types - Three types of context
• Context Layers - L0/L1/L2 model
• Storage Architecture - VikingFS and AGFS
• Session Management - Session storage structure