Viking URI

Viking URI 是 OpenViking 中所有内容的统一资源标识符。

格式

viking://{scope}/{path}

scheme: 始终为 viking
scope: 顶级命名空间（resources、user、agent、session；temp 和 queue 为内部作用域）
path: 作用域内的资源路径

作用域

作用域	说明	生命周期	可见性
resources	独立资源	长期	全局
user	用户级数据	长期	全局
agent	Agent 级数据	长期	全局
session	会话级数据	会话生命周期	当前会话
queue	处理队列	临时	内部
temp	临时文件	解析期间	内部

公开 API 和 CLI 的文件系统/内容操作只接受公开作用域： resources、user、agent、session，以及根 URI viking://。 temp 和 queue 是内部实现作用域，不能通过公开 API 的 URI 参数直接访问。

初始目录

摒弃传统的扁平化数据库思维，将所有上下文组织为一套文件系统。Agent 不再仅是通过向量搜索来找数据，而是可以通过确定性的路径和标准文件系统指令来定位和浏览数据。每个上下文或目录分配唯一的 URI 标识字符串，格式为 viking://{scope}/{path}，让系统能精准定位并访问存储在不同位置的资源。

viking://
├── session/{session_id}/
│   ├── .abstract.md          # L0: 会话一句话摘要
│   ├── .overview.md          # L1: 会话概览
│   ├── .meta.json            # 会话元数据
│   ├── messages.json         # 结构化消息存储
│   ├── checkpoints/          # 版本快照
│   ├── summaries/            # 压缩摘要历史
│   └── .relations.json       # 关联表
│
├── user/
│   ├── .abstract.md          # L0: 内容摘要
│   ├── .overview.md          # 用户画像
│   └── memories/             # 用户记忆存储
│       ├── .overview.md      # 记忆概览
│       ├── preferences/      # 用户偏好
│       ├── entities/         # 实体记忆
│       └── events/           # 事件记录
│
├── agent/
│   ├── .abstract.md          # L0: 内容摘要
│   ├── .overview.md          # Agent概览
│   ├── memories/             # Agent学习记忆
│   │   ├── .overview.md
│   │   ├── cases/            # 案例
│   │   └── patterns/         # 模式
│   ├── instructions/         # Agent指令
│   └── skills/               # 技能目录
│
└── resources/{project}/      # 资源工作区

URI 示例

资源

viking://resources/                           # 所有资源
viking://resources/my-project/                # 项目根目录
viking://resources/my-project/docs/           # 文档目录
viking://resources/my-project/docs/api.md     # 具体文件

用户数据

viking://user/                                # 用户根目录
viking://user/memories/                       # 所有用户记忆
viking://user/memories/preferences/           # 用户偏好
viking://user/memories/preferences/coding     # 具体偏好
viking://user/memories/entities/              # 实体记忆
viking://user/memories/events/                # 事件记忆

Agent 数据

viking://agent/                               # Agent 根目录
viking://agent/skills/                        # 所有技能
viking://agent/skills/search-web              # 具体技能
viking://agent/memories/                      # Agent 记忆
viking://agent/memories/cases/                # 学习的案例
viking://agent/memories/patterns/             # 学习的模式
viking://agent/instructions/                  # Agent 指令

会话数据

viking://session/{session_id}/                # 会话根目录
viking://session/{session_id}/messages/       # 会话消息
viking://session/{session_id}/tools/          # 工具执行
viking://session/{session_id}/history/        # 归档历史

目录结构

viking://
├── resources/                    # 独立资源
│   └── {project}/
│       ├── .abstract.md          # 摘要
│       ├── .overview.md          # 概述
│       └── {files...}
│
├── user/
│   ├── profile.md              	# 用户基本信息
│   └── memories/
│       ├── preferences/          # 按主题
│       ├── entities/             # 每条独立
│       └── events/               # 每条独立
│
├── agent/{agent_id}/             # isolate_agent_scope_by_user = false 时的 agent 根目录
│   ├── skills/                   # 技能定义
│   ├── memories/
│   │   ├── cases/
│   │   └── patterns/
│   └── instructions/
│
├── agent/{agent_id}/user/{user_id}/   # isolate_agent_scope_by_user = true 时的 agent 根目录
│   ├── skills/
│   ├── memories/
│   └── instructions/
│
└── session/{session_id}/
    ├── messages/
    ├── tools/
    └── history/

其中 agent 命名空间形状由 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 已废弃且被忽略。

URI 操作

解析

python

from openviking_cli.utils.uri import VikingURI

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

构建

python

# 拼接路径
base = "viking://resources/docs/"
full = VikingURI(base).join("api.md").uri  # viking://resources/docs/api.md

# 父目录
uri = "viking://resources/docs/api.md"
parent = VikingURI(uri).parent.uri  # viking://resources/docs

API 使用

指定作用域搜索

python

# 仅在资源中搜索
results = client.find(
    "认证",
    target_uri="viking://resources/"
)

# 仅在用户记忆中搜索
results = client.find(
    "编码偏好",
    target_uri="viking://user/memories/"
)

# 仅在技能中搜索
results = client.find(
    "网络搜索",
    target_uri="viking://agent/skills/"
)

文件系统操作

python

# 列出目录
entries = await client.ls("viking://resources/")

# 读取文件
content = await client.read("viking://resources/docs/api.md")

# 获取摘要
abstract = await client.abstract("viking://resources/docs/")

# 获取概览
overview = await client.overview("viking://resources/docs/")

特殊文件

每个目录可能包含特殊文件：

文件	用途
`.abstract.md`	L0 摘要（~100 tokens）
`.overview.md`	L1 概览（~2k tokens）
`.relations.json`	相关资源
`.meta.json`	元数据

最佳实践

目录使用尾部斜杠

python

# 目录
"viking://resources/docs/"

# 文件
"viking://resources/docs/api.md"

作用域特定操作

python

# 资源只添加到 resources 作用域
await client.add_resource(url, target="viking://resources/project/")

# 技能添加到 agent 作用域
await client.add_skill(skill)  # 自动到 viking://agent/skills/

Viking URI ​

格式 ​

作用域 ​

初始目录 ​

URI 示例 ​

资源 ​

用户数据 ​

Agent 数据 ​

会话数据 ​

目录结构 ​

URI 操作 ​

解析 ​

构建 ​

API 使用 ​

指定作用域搜索 ​

文件系统操作 ​

特殊文件 ​

最佳实践 ​

目录使用尾部斜杠 ​

作用域特定操作 ​

相关文档 ​

Viking URI

格式

作用域

初始目录

URI 示例

资源

用户数据

Agent 数据

会话数据

目录结构

URI 操作

解析

构建

API 使用

指定作用域搜索

文件系统操作

特殊文件

最佳实践

目录使用尾部斜杠

作用域特定操作

相关文档