viking://{scope}/{path}

viking://
├── resources/                    # 独立资源（客观知识）
│   └── {project}/
│       ├── .abstract.md          # L0 摘要
│       ├── .overview.md          # L1 概览
│       └── {files...}
│
├── user/{user_id}/               # 当前用户的数据
│   ├── profile.md                # 用户画像
│   ├── memories/                 # 记忆空间
│   │   ├── preferences/          # 按主题
│   │   ├── entities/             # 每条独立
│   │   └── events/               # 每条独立
│   ├── resources/                # 用户私有资源
│   ├── skills/                   # 用户技能
│   ├── peers/{peer_id}/          # 关于某个交互对象的隔离空间
│   │   ├── memories/
│   │   └── resources/
│   └── sessions/{session_id}/    # 会话
│
└── agent/                        # Agent 能力与配置（全局共享）
    ├── skills/
    ├── endpoints/                # 通信端点（规划中）
    ├── tools/                    # 工具配置（规划中）
    └── payments/                 # 支付配置（规划中）

{namespace:key}

# 写法（模板原样传，服务端渲染）
viking://resources/emails/{calendar:today}/inbox
# 渲染为：viking://resources/emails/2026/05/07/inbox

# CLI 中也一样（--parent-auto-create 可简写为 -p）
ov add-resource -p "viking://resources/emails/{calendar:today}/inbox" ./emails/*.eml
ov read "viking://resources/logs/{calendar:yesterday}/app.log"

# 添加资源（支持 URL / 本地文件 / 目录）
client.add_resource("https://docs.example.com/api.pdf", reason="API 文档")

# 在资源范围内检索
results = client.find("认证方法", target_uri="viking://resources/")

session = client.session()
await session.add_message("user", [{"type": "text", "text": "我喜欢深色模式"}])
commit = await session.commit()           # 启动后台记忆提取
task = await client.get_task(job_id)      # 轮询直到 status == "completed"

# 搜索记忆
results = await client.find("用户界面偏好", target_uri="viking://user/memories/")

viking://user/skills/search-web/
├── .abstract.md   # L0: 简短描述
├── SKILL.md       # L1: 详细概览
└── scripts        # L2: 完整定义

await client.add_skill({
    "name": "search-web",
    "description": "搜索网络获取信息",
    "content": "# search-web\n..."
})
# 全局共享：ov skills add search-web -p viking://agent/skills

results = await client.find("用户认证")   # 不指定 target_uri，全量搜
for ctx in results.memories:   print(f"记忆: {ctx.uri}")
for ctx in results.resources:  print(f"资源: {ctx.uri}")
for ctx in results.skills:     print(f"技能: {ctx.uri}")

API 认证指南，涵盖 OAuth 2.0、JWT 令牌和 API 密钥的安全访问方式。

# 认证指南概览
本指南涵盖 API 的三种认证方式：
## 章节
- **OAuth 2.0** (L2: oauth.md): 完整 OAuth 流程和代码示例
- **JWT 令牌** (L2: jwt.md): 令牌生成和验证
- **API 密钥** (L2: api-keys.md): 简单的密钥认证
## 要点
- OAuth 2.0 推荐用于面向用户的应用
- JWT 用于服务间通信
## 访问
使用 read("viking://resources/docs/auth/oauth.md") 获取完整文档。

viking://resources/docs/auth/
├── .abstract.md      # L0: ~100 tokens
├── .overview.md      # L1: ~1k tokens
├── .relations.json   # 相关资源
├── oauth.md          # L2: 完整内容
├── jwt.md            # L2
└── api-keys.md       # L2

# 先用 L1 概览判断，只在确实不够时才读 L2
overview = client.overview(uri)
if needs_more_detail(overview):
    content = client.read(uri)

session = client.session(session_id="chat_001")
session.add_message("user", [TextPart("怎么配置 embedding？")])
session.commit()

session.used(contexts=["viking://user/memories/profile.md"])
session.used(skill={"uri": "viking://user/skills/code-search",
                    "input": "search config", "output": "found 3 files", "success": True})

result = session.commit()
# {"status": "accepted", "task_id": "uuid-xxx", "archive_uri": "...", "archived": True}
task = client.get_task(result["task_id"])
# task["status"]: pending | running | completed | failed

消息 → LLM 提取 → 候选记忆
   → 向量预过滤（找相似旧记忆）
   → LLM 去重决策（candidate: skip/create/none + item: merge/delete）
   → 写入 AGFS → 向量化

{
  "archive_uri": "viking://user/{user_id}/sessions/{sid}/history/archive_001",
  "extracted_at": "2026-04-21T10:00:00Z",
  "operations": {
    "adds":    [{"uri": ".../identity.md", "memory_type": "identity", "after": "..."}],
    "updates": [{"uri": ".../project.md",  "memory_type": "context", "before": "...", "after": "..."}],
    "deletes": [{"uri": ".../old.md",      "memory_type": "context", "deleted_content": "..."}]
  },
  "summary": {"total_adds": 1, "total_updates": 1, "total_deletes": 1}
}

viking://user/{user_id}/peers/{peer_id}/memories/
viking://user/{user_id}/peers/{peer_id}/resources/

viking://user/{user_id}/sessions/{session_id}/
├── messages.jsonl        # 当前消息
├── .abstract.md          # 当前摘要
├── .overview.md          # 当前概览
├── history/
│   └── archive_001/
│       ├── messages.jsonl
│       ├── .abstract.md
│       ├── .overview.md
│       ├── memory_diff.json   # 记忆变更审计
│       └── .done
└── tools/{tool_id}/tool.json

viking://user/memories/   # 11 类记忆目录
├── profile.md  identity.md  soul.md
├── preferences/ entities/ events/
├── cases/ trajectories/ experiences/ tools/ skills/

┌──────────────────────────────────────────────────────────────┐
│                          Client 层                            │
│   AsyncOpenViking / SyncOpenViking / HTTPClient / ov CLI / Go │
└───────────────────────────────┬──────────────────────────────┘
                                 │ 委托
┌───────────────────────────────▼──────────────────────────────┐
│                       Service 层（业务逻辑）                   │
│  FSService / SearchService / SessionService / ResourceService │
│  RelationService / PackService / DebugService                 │
└───────────────────────────────┬──────────────────────────────┘
            ┌────────────────────┼────────────────────┐
            ▼                    ▼                    ▼
     ┌─────────────┐     ┌─────────────┐      ┌─────────────┐
     │  Retrieve   │     │   Session   │      │    Parse    │
     │ (上下文检索) │     │ (会话管理)   │      │ (上下文提取) │
     │ search/find │     │ add/used    │      │ 文档解析     │
     │ 意图分析    │     │ commit      │      │ L0/L1/L2    │
     │ Rerank      │     │ 压缩/去重    │      │ 树构建       │
     └──────┬──────┘     └──────┬──────┘      └──────┬──────┘
            │                   │ 记忆提取            │
            │                   ▼                     │
            │            ┌─────────────┐              │
            │            │ Compressor  │              │
            │            │ 压缩/去重     │              │
            │            └──────┬──────┘              │
            └───────────────────┼────────────────────┘
                                ▼
                    ┌───────────────────────────┐
                    │       Storage 层           │
                    │   AGFS(内容) + 向量库(索引) │
                    └───────────────────────────┘

输入 → Parser → TreeBuilder → AGFS → SemanticQueue → 向量库

查询 → 意图分析 → 层级检索 → Rerank → 结果

消息 → 压缩 → 归档 → 记忆提取 → 存储

┌─────────────────────────────────────────┐
│            VikingFS (URI 抽象层)         │
│    URI 映射 · 层级访问 · 关联管理        │
└────────────────┬────────────────────────┘
        ┌────────┴────────┐
        │                 │
┌───────▼────────┐  ┌─────▼───────────┐
│   向量库索引    │  │      AGFS       │
│   (语义搜索)    │  │   (内容存储)    │
└────────────────┘  └─────────────────┘

viking_fs.rm("viking://resources/docs/auth", recursive=True)
# 自动递归删除向量库中 uri 以此开头的所有记录

viking_fs.mv("viking://resources/docs/auth",
             "viking://resources/docs/authentication")
# 自动更新向量库中的 uri 和 parent_uri

viking://resources/docs/auth  →  /local/{account_id}/resources/docs/auth
viking://user/memories        →  /local/{account_id}/user/{user_id}/memories

viking_fs.link(from_uri="viking://resources/docs/auth",
               uris=["viking://resources/docs/security"], reason="相关安全文档")
relations = viking_fs.relations("viking://resources/docs/auth")

输入文件 → Parser → TreeBuilder → SemanticQueue → 向量库
           ↓           ↓              ↓
         解析转换    文件移动     L0/L1 生成
         (无 LLM)   入队语义      (LLM 异步)

if document_tokens <= 1024:   → 保存为单文件
else:
    → 按标题分割
    → 小节 < 512 tokens 合并
    → 大节 > 1024 tokens 创建子目录

查询 → 意图分析 → 层级检索 → Rerank → 结果
         ↓           ↓          ↓
     TypedQuery  目录递归    精排评分

# 简单查询
results = await client.find("OAuth 认证", target_uri="viking://resources/")

# 复杂任务（需要会话上下文）
results = await client.search("帮我创建一个 RFC 文档", session_info=session)

@dataclass
class TypedQuery:
    query: str               # 重写后的查询
    context_type: ContextType  # MEMORY/RESOURCE/SKILL
    intent: str              # 查询目的
    priority: int            # 1-5 优先级

Step1: 按 context_type 确定根目录
Step2: 全局向量搜索定位起始目录
Step3: 合并起始点 + Rerank 评分
Step4: 递归搜索（优先队列）
Step5: 转为 MatchedContext

while dir_queue:
    current_uri, parent_score = heapq.heappop(dir_queue)

    results = await search(parent_uri=current_uri)
    for r in results:
        # 分数传播：子节点分数 = α*自身 + (1-α)*父分数
        final_score = alpha * embedding_score + (1-alpha) * parent_score

        if final_score > threshold:
            collected.append(r)
            if not r.is_leaf:                # 目录则继续递归
                heapq.heappush(dir_queue, (r.uri, final_score))

    if topk_unchanged_for_3_rounds:          # 收敛检测，提前停止
        break

@dataclass
class MatchedContext:
    uri: str; context_type; is_leaf; abstract  # L0 摘要
    score: float; relations: List[RelatedContext]

@dataclass
class FindResult:
    memories; resources; skills; query_plan; query_results; total

对话消息
  → SessionCompressorV2 压缩（保留最近 N 轮，旧消息归档 + 生成 L0/L1）
  → ExtractLoop 用 LLM 抽取候选记忆
  → 向量预过滤找相似旧记忆
  → LLM 去重决策（skip/create/merge/delete）
  → MemoryUpdater 写 AGFS + 向量化
  → 写 memory_diff.json 审计

client = OpenViking(path="./data")

client = SyncHTTPClient(url="http://localhost:1933", api_key="xxx")

curl http://localhost:1933/api/v1/search/find \
  -H "X-API-Key: xxx" -d '{"query": "how to use openviking"}'

# 推荐 uv
uv tool install openviking --upgrade
# 或 pip
pip install openviking --upgrade --force-reinstall
# 或 pipx
pipx install openviking && pipx upgrade openviking

openviking-server init
openviking-server doctor

{
  "embedding": {
    "dense": {"api_base": "<endpoint>", "api_key": "<key>",
              "provider": "<provider>", "dimension": 1024, "model": "<model>"}
  },
  "vlm": {
    "api_base": "<endpoint>", "api_key": "<key>",
    "provider": "<provider>", "model": "<model>"
  }
}

import openviking as ov

client = ov.OpenViking(path="./data")     # 1. 创建嵌入式客户端，数据存 ./data

try:
    client.initialize()                    # 2. 初始化（启动 AGFS 子进程）

    # 3. 添加资源：支持 URL / 文件 / 目录；本地目录默认遵循 .gitignore
    #    wait=True 会阻塞到语义处理（L0/L1 生成）完成
    print("Wait for semantic processing...")
    add_result = client.add_resource(
        path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md",
        wait=True,
    )
    root_uri = add_result['root_uri']

    # 4. 像用文件系统一样探索结构
    ls_result = client.ls(root_uri)
    print(f"Directory structure:\n{ls_result}\n")

    # 5. glob 找所有 markdown 文件，read 读取第一个的前 200 字
    glob_result = client.glob(pattern="**/*.md", uri=root_uri)
    if glob_result['matches']:
        content = client.read(glob_result['matches'][0])
        print(f"Content preview: {content[:200]}...\n")

    # 6. 获取 L0 摘要和 L1 概览（省 Token 的关键）
    abstract = client.abstract(root_uri)
    overview = client.overview(root_uri)
    print(f"Abstract:\n{abstract}\n\nOverview:\n{overview}\n")

    # 7. 语义检索
    results = client.find("what is openviking", target_uri=root_uri)
    print("Search results:")
    for r in results.resources:
        print(f"  {r.uri} (score: {r.score:.4f})")

    client.close()                        # 8. 关闭
except Exception as e:
    print(f"Error: {e}")