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; temp and queue are internal)
• path: Resource path within the scope

Scopes

Scope	Description	Lifecycle	Visibility
resources	Independent resources	Long-term	Global
user	User-level data	Long-term	Global
agent	Agent-level data	Long-term	Global
session	Session-level data	Session lifetime	Current session
queue	Processing queue	Temporary	Internal
temp	Temporary files	During parsing	Internal

Public API and CLI filesystem/content operations accept only the public scopes: resources, user, agent, and session (plus the root URI viking://). temp and queue are internal implementation scopes and cannot be addressed directly through public API URI parameters.

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/{user_id}/
│   ├── profile.md                # User basic info
│   └── memories/
│       ├── preferences/          # By topic
│       ├── entities/             # Each independent
│       └── events/               # Each independent
│
├── agent/{agent_id}/             # Agent root when isolate_agent_scope_by_user = false
│   ├── skills/                   # Skill definitions
│   ├── memories/
│   │   ├── cases/
│   │   └── patterns/
│   ├── workspaces/
│   └── instructions/
│
├── agent/{agent_id}/user/{user_id}/   # Agent root when isolate_agent_scope_by_user = true
│   ├── skills/
│   ├── memories/
│   ├── workspaces/
│   └── instructions/
│
└── session/{user_space}/{session_id}/
    ├── messages/
    ├── tools/
    └── history/

Agent namespace shape is controlled by per-account namespace policy:

• isolate_agent_scope_by_user = false: viking://agent/{agent_id}/...
• isolate_agent_scope_by_user = true: viking://agent/{agent_id}/user/{user_id}/...

memory.agent_scope_mode is deprecated and ignored.

URI Operations

Parsing

from openviking_cli.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:

File	Purpose
.abstract.md	L0 abstract (~100 tokens)
.overview.md	L1 overview (~2k tokens)
.relations.json	Related resources
.meta.json	Metadata

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