# 简介

**OpenViking** 是一个开源的、专为 AI Agent 设计的上下文数据库。OpenViking 通过**文件系统范式**统一管理Agent 所需要的上下文（记忆、资源和技能），并实现上下文的**分层供给**与**自我迭代**，最终目标是降低 Agent 开发门槛，让开发者更专注于业务创新而非底层上下文管理。

## 为什么需要 OpenViking

在 AI 时代，数据易得，但高质量的上下文却难求。构建 AI Agent 时，开发者经常遇到这些挑战：

- **上下文碎片化**：记忆在代码里，资源在向量库，技能散落各处，难以统一管理
- **所需上下文猛增**：Agent 的长程任务在每次执行时都会产出上下文，简单的截断或压缩会导致信息损失
- **检索效果不佳**：传统 RAG 是平铺式存储，缺乏全局视野，难以理解信息的完整语境
- **上下文不可观测**：传统 RAG 隐式的检索链路如同黑箱，出错时难以调试
- **记忆迭代有限**：目前记忆只是用户记忆的记录，缺乏 Agent 相关的任务记忆

OpenViking 正是为解决这些痛点而设计的上下文数据库。

## 核心特性

### 1. 文件系统管理范式

摒弃传统的扁平化数据库思维，将所有上下文组织为一套虚拟文件系统。Agent 不再仅是通过向量搜索来找数据，而是可以通过确定性的路径和标准文件系统指令来定位和浏览数据。

**统一 URI 标识**：每个上下文分配唯一的 `viking://` URI，让系统能精准定位并访问存储在不同位置的资源。

```
viking://
├── resources/              # 资源：项目文档、代码库、网页等
│   └── my_project/
├── user/                   # 用户：个人偏好、习惯等
│   └── memories/
└── agent/                  # Agent：技能、指令、任务记忆等
    ├── skills/
    └── memories/
```

**三种上下文类型**：

| 类型 | 用途 | 生命周期 |
|------|------|----------|
| **Resource** | 知识和规则（文档、代码、FAQ） | 长期，相对静态 |
| **Memory** | Agent 的认知（用户偏好、学习经验） | 长期，动态更新 |
| **Skill** | 可调用的能力（工具、MCP） | 长期，静态 |

**类 Unix API**：熟悉的命令式操作

```python
client.find("用户认证")              # 语义搜索
client.ls("viking://resources/")     # 列出目录
client.read("viking://resources/doc") # 读取内容
client.abstract("viking://...")       # 获取 L0 摘要
client.overview("viking://...")       # 获取 L1 概览
```

### 2. 分层上下文按需加载

将海量上下文一次性塞入提示词，不仅成本高昂，更容易超出模型窗口并引入噪声。OpenViking 在上下文写入时便自动将其处理为三个层级：

| 层级 | 名称 | Token 限制 | 用途 |
|------|------|-----------|------|
| **L0** | 摘要 | ~100 tokens | 向量搜索、快速过滤 |
| **L1** | 概览 | ~2k tokens | Rerank 精排、内容导航 |
| **L2** | 详情 | 无限制 | 完整内容、按需加载 |

```
viking://resources/my_project/
├── .abstract.md               # L0 层：摘要
├── .overview.md               # L1 层：概览
├── docs/
│   ├── .abstract.md          # 每个目录都有对应的 L0/L1 层
│   ├── .overview.md
│   └── api.md                # L2 层：完整内容
└── src/
```

### 3. 目录递归检索

单一的向量检索难以应对复杂的查询意图。OpenViking 设计了一套创新的**目录递归检索策略**：

1. **意图分析**：通过意图分析生成多个检索条件
2. **初始定位**：利用向量检索快速定位初始切片所在的高分目录
3. **精细探索**：在该目录下进行二次检索，并将高分结果更新至候选集合
4. **递归下探**：若目录下仍存在子目录，则逐层递归重复上述二次检索步骤
5. **结果汇总**：最终拿到最相关上下文返回

这种"先锁定高分目录、再精细探索内容"的策略，不仅能找到语义最匹配的片段，更能理解信息所在的完整语境。

### 4. 可视化检索轨迹

OpenViking 的组织方式采用层次化虚拟文件系统结构，所有上下文均以统一格式整合且每个条目对应唯一 URI，打破传统扁平黑箱式管理模式。

检索过程采用目录递归策略，每次检索的目录浏览、文件定位轨迹均被完整留存，能够清晰观测问题根源并指导检索逻辑优化。

### 5. 会话自动管理

OpenViking 内置了记忆自迭代闭环。在每次会话结束时，开发者可以主动触发记忆提取机制，系统会异步分析任务执行结果与用户反馈，并自动更新至 User 和 Agent 的记忆目录下。

**6 种记忆分类**：

| 分类 | 归属 | 说明 |
|------|------|------|
| **profile** | user | 用户基本信息 |
| **preferences** | user | 按主题的用户偏好 |
| **entities** | user | 实体记忆（人物、项目） |
| **events** | user | 事件记录（决策、里程碑） |
| **cases** | agent | 学习的案例 |
| **patterns** | agent | 学习的模式 |

让 Agent 在与世界的交互中"越用越聪明"，实现自我进化。

## 下一步

- [快速开始](./02-quickstart.md) - 5 分钟上手
- [架构详解](../concepts/01-architecture.md) - 理解系统设计
- [上下文类型](../concepts/02-context-types.md) - 深入了解三种上下文
- [检索机制](../concepts/07-retrieval.md) - 了解检索流程