Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

docs: correct context paths and refine navigation (#3385)

yufeng085aaf832d3a
diff --git a/README.md b/README.md
index 40da934aa..4ab383006 100644
--- a/README.md
+++ b/README.md
@@ -795,7 +795,7 @@ The retrieval process adopts a directory recursive strategy. The trajectory of d
### 5. Automatic Session Management → Context Self-Iteration
-OpenViking has a built-in memory self-iteration loop. At the end of each session, developers can actively trigger the memory extraction mechanism. The system will asynchronously analyze task execution results and user feedback, and automatically update them to the User and Agent memory directories.
+OpenViking has a built-in memory self-iteration loop. After a session is committed, the system asynchronously analyzes task outcomes and user feedback, then updates memory in the current User or Peer namespace according to the active memory policy.
- **User Memory Update**: Update memories related to user preferences, making Agent responses better fit user needs.
- **Agent Experience Accumulation**: Extract core content such as operational tips and tool usage experience from task execution experience, aiding efficient decision-making in subsequent tasks.
diff --git a/README_CN.md b/README_CN.md
index 4792858a4..7a849c4e2 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -836,7 +836,7 @@ OpenViking 的组织采用分层虚拟文件系统结构。所有上下文以统
### 5. 自动会话管理 → 上下文自迭代
-OpenViking 内置了记忆自迭代循环。在每个会话结束时,开发者可以主动触发记忆提取机制。系统将异步分析任务执行结果和用户反馈,并自动更新到用户和智能体记忆目录。
+OpenViking 内置了记忆自迭代循环。提交会话后,系统会异步分析任务执行结果和用户反馈,并根据记忆策略更新当前用户或 Peer 命名空间中的记忆。
- **用户记忆更新**:更新与用户偏好相关的记忆,使智能体响应更好地适应用户需求。
- **智能体经验积累**:从任务执行经验中提取操作技巧和工具使用经验等核心内容,辅助后续任务的高效决策。
diff --git a/README_JA.md b/README_JA.md
index ca06b1350..ed336c2f6 100644
--- a/README_JA.md
+++ b/README_JA.md
@@ -470,18 +470,23 @@ viking://
│ │ └── src/
│ └── ...
├── user/ # ユーザー: 個人の好み、習慣など
-│ └── memories/
-│ ├── preferences/
-│ │ ├── writing_style
-│ │ └── coding_habits
-│ └── ...
-└── agent/ # エージェント: スキル、インストラクション、タスクメモリなど
- ├── skills/
- │ ├── search_code
- │ ├── analyze_data
- │ └── ...
- ├── memories/
- └── instructions/
+│ └── {user_id}/
+│ ├── memories/
+│ │ ├── preferences/
+│ │ │ ├── writing_style
+│ │ │ └── coding_habits
+│ │ └── ...
+│ ├── resources/
+│ │ └── private_project/
+│ ├── skills/
+│ │ ├── search_code
+│ │ └── analyze_data
+│ └── peers/
+│ └── web-visitor-alice/
+│ ├── memories/
+│ └── resources/
+└── agent/
+ └── skills/ # 任意のアカウント全体の共有スキル
```
### 2. 階層型コンテキストローディング → トークン消費の削減
@@ -530,7 +535,7 @@ OpenVikingの組織は階層的な仮想ファイルシステム構造を使用
### 5. 自動セッション管理 → コンテキストの自己反復
-OpenVikingにはメモリ自己反復ループが組み込まれています。各セッションの終了時に、開発者はメモリ抽出メカニズムを能動的にトリガーできます。システムはタスク実行結果とユーザーフィードバックを非同期的に分析し、ユーザーとエージェントのメモリディレクトリに自動的に更新します。
+OpenVikingにはメモリの自己反復ループが組み込まれています。セッションをコミットすると、システムはタスクの実行結果とユーザーフィードバックを非同期に分析し、メモリポリシーに従って現在のユーザーまたは Peer 名前空間のメモリを更新します。
- **ユーザーメモリの更新**: ユーザーの好みに関するメモリを更新し、エージェントの応答がユーザーのニーズにより適合するように。
- **エージェントの経験蓄積**: タスク実行経験から操作のヒントやツールの使用経験などのコアコンテンツを抽出し、後続タスクでの効率的な意思決定を支援。
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index e648cbebc..09a0bcbbc 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -100,29 +100,482 @@ function sidebarSection(dir: string, title: string, collapsed = true): DefaultTh
return { text: title, collapsed, items }
}
+const agentIntegrationSidebar = {
+ en: {
+ overview: 'Integration Overview',
+ groups: [
+ {
+ text: 'Developer Tools',
+ items: [
+ ['02-claude-code.md', 'Claude Code'],
+ ['04-codex.md', 'Codex'],
+ ['10-opencode.md', 'OpenCode'],
+ ['12-cursor.md', 'Cursor'],
+ ['13-trae.md', 'TRAE / TRAE CN']
+ ]
+ },
+ {
+ text: 'Agents & Frameworks',
+ items: [
+ ['03-openclaw.md', 'OpenClaw'],
+ ['05-hermes.md', 'Hermes'],
+ ['07-langchain-langgraph.md', 'LangChain / LangGraph'],
+ ['11-pi.md', 'pi']
+ ]
+ },
+ {
+ text: 'General Integration',
+ items: [
+ ['06-mcp-clients.md', 'MCP Clients'],
+ ['09-log-ingestion.md', 'Local Log Import'],
+ ['08-community-plugins.md', 'Community Integrations']
+ ]
+ }
+ ]
+ },
+ zh: {
+ overview: '集成概览',
+ groups: [
+ {
+ text: '开发工具',
+ items: [
+ ['02-claude-code.md', 'Claude Code'],
+ ['04-codex.md', 'Codex'],
+ ['10-opencode.md', 'OpenCode'],
+ ['12-cursor.md', 'Cursor'],
+ ['13-trae.md', 'TRAE / TRAE CN']
+ ]
+ },
+ {
+ text: 'Agent 与框架',
+ items: [
+ ['03-openclaw.md', 'OpenClaw'],
+ ['05-hermes.md', 'Hermes'],
+ ['07-langchain-langgraph.md', 'LangChain / LangGraph'],
+ ['11-pi.md', 'pi']
+ ]
+ },
+ {
+ text: '通用接入',
+ items: [
+ ['06-mcp-clients.md', 'MCP 客户端'],
+ ['09-log-ingestion.md', '本地日志导入'],
+ ['08-community-plugins.md', '社区集成']
+ ]
+ }
+ ]
+ }
+} as const
+
+const apiReferenceSidebar = {
+ en: {
+ overview: 'Overview',
+ groups: [
+ {
+ text: 'Core Capabilities',
+ items: [
+ ['02-resources.md', 'Resources'],
+ ['03-filesystem.md', 'File System'],
+ ['04-skills.md', 'Skills'],
+ ['05-sessions.md', 'Sessions & Memory'],
+ ['06-retrieval.md', 'Retrieval']
+ ]
+ },
+ {
+ text: 'Operations & Governance',
+ items: [
+ ['07-system.md', 'System'],
+ ['08-admin.md', 'Multi-Tenancy'],
+ ['09-metrics.md', 'Metrics'],
+ ['10-privacy.md', 'Privacy'],
+ ['11-snapshot.md', 'Snapshots']
+ ]
+ },
+ {
+ text: 'Contributing',
+ items: [['99-api-doc-writing-guide.md', 'API Docs Guide']]
+ }
+ ]
+ },
+ zh: {
+ overview: '概览',
+ groups: [
+ {
+ text: '核心能力',
+ items: [
+ ['02-resources.md', '资源'],
+ ['03-filesystem.md', '文件系统'],
+ ['04-skills.md', '技能'],
+ ['05-sessions.md', '会话与记忆'],
+ ['06-retrieval.md', '检索']
+ ]
+ },
+ {
+ text: '运维与治理',
+ items: [
+ ['07-system.md', '系统管理'],
+ ['08-admin.md', '多租户'],
+ ['09-metrics.md', '监控指标'],
+ ['10-privacy.md', '隐私配置'],
+ ['11-snapshot.md', '快照管理']
+ ]
+ },
+ {
+ text: '文档贡献',
+ items: [['99-api-doc-writing-guide.md', 'API 文档规范']]
+ }
+ ]
+ }
+} as const
+
+const conceptsSidebar = {
+ en: {
+ overview: 'Overview',
+ groups: [
+ {
+ text: 'Core Model',
+ items: [
+ ['02-context-types.md', 'Context Types'],
+ ['03-context-layers.md', 'Context Layers'],
+ ['04-viking-uri.md', 'Viking URI']
+ ]
+ },
+ {
+ text: 'Storage & Processing',
+ items: [
+ ['05-storage.md', 'Storage'],
+ ['06-extraction.md', 'Extraction'],
+ ['07-retrieval.md', 'Retrieval'],
+ ['08-session.md', 'Sessions']
+ ]
+ },
+ {
+ text: 'Reliability & Governance',
+ items: [
+ ['09-transaction.md', 'Transactions & Recovery'],
+ ['10-encryption.md', 'Encryption'],
+ ['11-multi-tenant.md', 'Multi-Tenancy'],
+ ['12-metrics.md', 'Metrics'],
+ ['13-privacy.md', 'Privacy'],
+ ['14-multi-write-storage.md', 'Multi-Write Storage']
+ ]
+ },
+ {
+ text: 'Example',
+ items: [['15-vikingbot.md', 'VikingBot']]
+ }
+ ]
+ },
+ zh: {
+ overview: '概览',
+ groups: [
+ {
+ text: '核心模型',
+ items: [
+ ['02-context-types.md', '上下文类型'],
+ ['03-context-layers.md', '上下文层级'],
+ ['04-viking-uri.md', 'Viking URI']
+ ]
+ },
+ {
+ text: '存储与处理',
+ items: [
+ ['05-storage.md', '存储架构'],
+ ['06-extraction.md', '上下文提取'],
+ ['07-retrieval.md', '检索机制'],
+ ['08-session.md', '会话管理']
+ ]
+ },
+ {
+ text: '可靠性与治理',
+ items: [
+ ['09-transaction.md', '事务与恢复'],
+ ['10-encryption.md', '数据加密'],
+ ['11-multi-tenant.md', '多租户'],
+ ['12-metrics.md', '监控指标'],
+ ['13-privacy.md', '隐私配置'],
+ ['14-multi-write-storage.md', '多写存储']
+ ]
+ },
+ {
+ text: '应用案例',
+ items: [['15-vikingbot.md', 'VikingBot']]
+ }
+ ]
+ }
+} as const
+
+const guidesSidebar = {
+ en: {
+ groups: [
+ {
+ text: 'Configuration & Deployment',
+ items: [
+ ['01-configuration.md', 'Configuration'],
+ ['02-volcengine-purchase-guide.md', 'Model Purchase'],
+ ['03-deployment.md', 'Server Deployment'],
+ ['04-authentication.md', 'Authentication'],
+ ['08-encryption.md', 'Encryption'],
+ ['11-oauth.md', 'OAuth 2.1'],
+ ['12-public-access.md', 'Public Access']
+ ]
+ },
+ {
+ text: 'Integration & Extension',
+ items: [
+ ['06-mcp-integration.md', 'MCP Integration'],
+ ['09-ovpack.md', 'OVPack'],
+ ['10-prompt-guide.md', 'Prompt Customization'],
+ ['17-vikingbot.md', 'VikingBot']
+ ]
+ },
+ {
+ text: 'Observability',
+ items: [
+ ['05-observability.md', 'Observability & Diagnostics'],
+ ['07-operation-telemetry.md', 'Operation Telemetry'],
+ ['11-grafana-prometheus.md', 'Prometheus / Grafana']
+ ]
+ },
+ {
+ text: 'Storage & Performance',
+ items: [
+ ['13-multi-write-storage.md', 'Multi-Write Storage'],
+ ['14-ragfs-cache.md', 'RAGFS Cache'],
+ ['15-snapshot.md', 'Snapshots'],
+ ['16-cuvs.md', 'cuVS Vector Search']
+ ]
+ }
+ ]
+ },
+ zh: {
+ groups: [
+ {
+ text: '配置与部署',
+ items: [
+ ['01-configuration.md', '基础配置'],
+ ['02-volcengine-purchase-guide.md', '模型购买'],
+ ['03-deployment.md', '服务端部署'],
+ ['04-authentication.md', '身份认证'],
+ ['08-encryption.md', '数据加密'],
+ ['11-oauth.md', 'OAuth 2.1'],
+ ['12-public-access.md', '公网访问']
+ ]
+ },
+ {
+ text: '集成与扩展',
+ items: [
+ ['06-mcp-integration.md', 'MCP 集成'],
+ ['09-ovpack.md', 'OVPack'],
+ ['10-prompt-guide.md', 'Prompt 自定义'],
+ ['17-vikingbot.md', 'VikingBot']
+ ]
+ },
+ {
+ text: '可观测性',
+ items: [
+ ['05-observability.md', '可观测性与排障'],
+ ['07-operation-telemetry.md', '操作遥测'],
+ ['11-grafana-prometheus.md', 'Prometheus / Grafana'],
+ ['12-vikingbot-metrics-validation.md', 'VikingBot 指标验证']
+ ]
+ },
+ {
+ text: '存储与性能',
+ items: [
+ ['13-multi-write-storage.md', '多写存储'],
+ ['14-ragfs-cache.md', 'RAGFS 缓存'],
+ ['15-snapshot.md', '快照管理'],
+ ['16-cuvs.md', 'cuVS 向量检索']
+ ]
+ }
+ ]
+ }
+} as const
+
+type StructuredSidebarCopy = {
+ readonly overview: string
+ readonly groups: ReadonlyArray<{
+ readonly text: string
+ readonly items: ReadonlyArray<readonly [string, string]>
+ }>
+}
+
+type GroupedSidebarCopy = Pick<StructuredSidebarCopy, 'groups'>
+
+function configuredSidebarItem(
+ locale: 'en' | 'zh',
+ section: string,
+ [file, text]: readonly [string, string]
+): DefaultTheme.SidebarItem {
+ return {
+ text,
+ link: linkFor(path.join(docsRoot, locale, section, file))
+ }
+}
+
+function configuredSidebarGroups(
+ locale: 'en' | 'zh',
+ section: string,
+ groups: GroupedSidebarCopy['groups']
+): DefaultTheme.SidebarItem[] {
+ return groups.map((group) => ({
+ text: group.text,
+ collapsed: false,
+ items: group.items.map((item) => configuredSidebarItem(locale, section, item))
+ }))
+}
+
+function groupedSidebarSection(
+ locale: 'en' | 'zh',
+ section: string,
+ title: string,
+ copy: GroupedSidebarCopy,
+ collapsed = true
+): DefaultTheme.SidebarItem {
+ return {
+ text: title,
+ collapsed,
+ items: configuredSidebarGroups(locale, section, copy.groups)
+ }
+}
+
+function structuredSidebarSection(
+ locale: 'en' | 'zh',
+ section: string,
+ title: string,
+ copy: StructuredSidebarCopy,
+ collapsed = true,
+ overviewFile = '01-overview.md'
+): DefaultTheme.SidebarItem {
+ return {
+ text: title,
+ collapsed,
+ items: [
+ configuredSidebarItem(locale, section, [overviewFile, copy.overview]),
+ ...configuredSidebarGroups(locale, section, copy.groups)
+ ]
+ }
+}
+
+function agentIntegrationSection(
+ locale: 'en' | 'zh',
+ title: string,
+ collapsed = true
+): DefaultTheme.SidebarItem {
+ return structuredSidebarSection(
+ locale,
+ 'agent-integrations',
+ title,
+ agentIntegrationSidebar[locale],
+ collapsed
+ )
+}
+
+function apiReferenceSection(
+ locale: 'en' | 'zh',
+ title: string,
+ collapsed = true
+): DefaultTheme.SidebarItem {
+ return structuredSidebarSection(locale, 'api', title, apiReferenceSidebar[locale], collapsed)
+}
+
+function conceptsSection(
+ locale: 'en' | 'zh',
+ title: string,
+ collapsed = true
+): DefaultTheme.SidebarItem {
+ return structuredSidebarSection(
+ locale,
+ 'concepts',
+ title,
+ conceptsSidebar[locale],
+ collapsed,
+ '01-architecture.md'
+ )
+}
+
+function guidesSection(
+ locale: 'en' | 'zh',
+ title: string,
+ collapsed = true
+): DefaultTheme.SidebarItem {
+ return groupedSidebarSection(locale, 'guides', title, guidesSidebar[locale], collapsed)
+}
+
+function migrationSection(
+ locale: 'en' | 'zh',
+ title: string,
+ collapsed = true
+): DefaultTheme.SidebarItem {
+ return {
+ text: title,
+ collapsed,
+ items: [
+ {
+ text: '0.3.x → 0.4.0',
+ link: linkFor(path.join(docsRoot, locale, 'migration', '01-user-peer-model.md'))
+ }
+ ]
+ }
+}
+
+type LocalizedSidebarSection =
+ | 'getting-started'
+ | 'concepts'
+ | 'guides'
+ | 'agent-integrations'
+ | 'migration'
+
+type LocalizedSidebarSectionBuilder = (
+ locale: 'en' | 'zh',
+ title: string,
+ collapsed?: boolean
+) => DefaultTheme.SidebarItem
+
+const localizedSidebarSectionBuilders: Record<
+ LocalizedSidebarSection,
+ LocalizedSidebarSectionBuilder
+> = {
+ 'getting-started': (locale, title, collapsed = true) =>
+ sidebarSection(`${locale}/getting-started`, title, collapsed),
+ concepts: conceptsSection,
+ guides: guidesSection,
+ 'agent-integrations': agentIntegrationSection,
+ migration: migrationSection
+}
+
+function localizedSidebarSection(
+ locale: 'en' | 'zh',
+ section: LocalizedSidebarSection,
+ title: string,
+ collapsed = true
+): DefaultTheme.SidebarItem {
+ return localizedSidebarSectionBuilders[section](locale, title, collapsed)
+}
+
function localizedSectionSidebarItems(
locale: 'en' | 'zh',
- section: 'getting-started' | 'concepts' | 'guides' | 'agent-integrations' | 'migration'
+ section: LocalizedSidebarSection
): DefaultTheme.SidebarItem[] {
const labels = locale === 'zh' ? zhSectionNames : sectionNames
- return [sidebarSection(`${locale}/${section}`, labels[section], false)]
+ return [localizedSidebarSection(locale, section, labels[section], false)]
}
function localizedGroupedSidebarItems(
locale: 'en' | 'zh',
- sections: ReadonlyArray<'getting-started' | 'guides' | 'agent-integrations' | 'migration'>,
- activeSection: 'getting-started' | 'guides' | 'agent-integrations' | 'migration'
+ sections: ReadonlyArray<Exclude<LocalizedSidebarSection, 'concepts'>>
): DefaultTheme.SidebarItem[] {
const labels = locale === 'zh' ? zhSectionNames : sectionNames
return sections.map((section) =>
- sidebarSection(`${locale}/${section}`, labels[section], section !== activeSection)
+ localizedSidebarSection(locale, section, labels[section], false)
)
}
function localizedReferenceSidebarItems(locale: 'en' | 'zh'): DefaultTheme.SidebarItem[] {
const labels = locale === 'zh' ? zhSectionNames : sectionNames
- return [sidebarSection(`${locale}/api`, labels.api, false)]
+ return [apiReferenceSection(locale, labels.api, false)]
}
function localizedAboutSidebarItems(locale: 'en' | 'zh'): DefaultTheme.SidebarItem[] {
@@ -372,11 +825,11 @@ export default defineConfig({
level: [2, 3]
},
sidebar: {
- '/en/getting-started/': localizedGroupedSidebarItems('en', ['getting-started', 'agent-integrations'], 'getting-started'),
+ '/en/getting-started/': localizedGroupedSidebarItems('en', ['getting-started', 'agent-integrations']),
'/en/concepts/': localizedSectionSidebarItems('en', 'concepts'),
- '/en/guides/': localizedGroupedSidebarItems('en', ['guides', 'migration'], 'guides'),
- '/en/agent-integrations/': localizedGroupedSidebarItems('en', ['getting-started', 'agent-integrations'], 'agent-integrations'),
- '/en/migration/': localizedGroupedSidebarItems('en', ['guides', 'migration'], 'migration'),
+ '/en/guides/': localizedGroupedSidebarItems('en', ['guides', 'migration']),
+ '/en/agent-integrations/': localizedGroupedSidebarItems('en', ['getting-started', 'agent-integrations']),
+ '/en/migration/': localizedGroupedSidebarItems('en', ['guides', 'migration']),
'/en/api/': localizedReferenceSidebarItems('en'),
'/en/about/': localizedAboutSidebarItems('en'),
'/design/': designSidebar
@@ -392,11 +845,11 @@ export default defineConfig({
themeConfig: {
nav: zhNav,
sidebar: {
- '/zh/getting-started/': localizedGroupedSidebarItems('zh', ['getting-started', 'agent-integrations'], 'getting-started'),
+ '/zh/getting-started/': localizedGroupedSidebarItems('zh', ['getting-started', 'agent-integrations']),
'/zh/concepts/': localizedSectionSidebarItems('zh', 'concepts'),
- '/zh/guides/': localizedGroupedSidebarItems('zh', ['guides', 'migration'], 'guides'),
- '/zh/agent-integrations/': localizedGroupedSidebarItems('zh', ['getting-started', 'agent-integrations'], 'agent-integrations'),
- '/zh/migration/': localizedGroupedSidebarItems('zh', ['guides', 'migration'], 'migration'),
+ '/zh/guides/': localizedGroupedSidebarItems('zh', ['guides', 'migration']),
+ '/zh/agent-integrations/': localizedGroupedSidebarItems('zh', ['getting-started', 'agent-integrations']),
+ '/zh/migration/': localizedGroupedSidebarItems('zh', ['guides', 'migration']),
'/zh/api/': localizedReferenceSidebarItems('zh'),
'/zh/about/': localizedAboutSidebarItems('zh')
},
diff --git a/docs/.vitepress/theme/LlmsTxtLink.vue b/docs/.vitepress/theme/LlmsTxtLink.vue
index 7a8950e38..a8d66a109 100644
--- a/docs/.vitepress/theme/LlmsTxtLink.vue
+++ b/docs/.vitepress/theme/LlmsTxtLink.vue
@@ -1,13 +1,12 @@
<script setup lang="ts">
import { useData, withBase } from 'vitepress'
import { computed, ref } from 'vue'
-import { hasPageLlmsTxt } from './llms-txt'
+import { absoluteLlmsTxtUrl, hasPageLlmsTxt, pageLlmsTxtPath } from './llms-txt'
const { page } = useData()
const llmsUrl = computed(() => {
- const pagePath = page.value.relativePath.replace(/\.md$/, '')
- return withBase(`/${pagePath}/llms.txt`)
+ return withBase(pageLlmsTxtPath(page.value.relativePath))
})
const isDoc = computed(() => hasPageLlmsTxt(page.value.relativePath))
@@ -17,9 +16,9 @@ let resetTimer: ReturnType<typeof window.setTimeout> | undefined
const isZh = computed(() => page.value.relativePath.startsWith('zh/'))
const copyLabel = computed(() => {
- if (copyFailed.value) return isZh.value ? '复制失败' : 'Copy failed'
- if (copied.value) return isZh.value ? '已复制' : 'Copied'
- return isZh.value ? '复制' : 'Copy'
+ if (copyFailed.value) return isZh.value ? '链接复制失败' : 'Copy failed'
+ if (copied.value) return isZh.value ? '链接已复制' : 'Link copied'
+ return isZh.value ? '复制链接' : 'Copy link'
})
async function writeClipboard(text: string) {
@@ -40,15 +39,13 @@ async function writeClipboard(text: string) {
}
}
-async function copyLlmsTxt() {
+async function copyLlmsLink() {
window.clearTimeout(resetTimer)
copied.value = false
copyFailed.value = false
try {
- const response = await fetch(llmsUrl.value)
- if (!response.ok) throw new Error(`Failed to load llms.txt: ${response.status}`)
- await writeClipboard(await response.text())
+ await writeClipboard(absoluteLlmsTxtUrl(llmsUrl.value, window.location.origin))
copied.value = true
} catch {
copyFailed.value = true
@@ -80,7 +77,12 @@ async function copyLlmsTxt() {
</svg>
llms.txt
</a>
- <button type="button" class="llms-copy" :class="{ 'is-copied': copied }" @click="copyLlmsTxt">
+ <button
+ type="button"
+ class="llms-copy"
+ :class="{ 'is-copied': copied, 'is-failed': copyFailed }"
+ @click="copyLlmsLink"
+ >
<svg
xmlns="http://www.w3.org/2000/svg"
width="14"
@@ -129,7 +131,19 @@ async function copyLlmsTxt() {
background: transparent;
cursor: pointer;
font-family: inherit;
- transition: color 0.2s;
+ opacity: 0;
+ pointer-events: none;
+ transform: translateX(-4px);
+ transition: color 0.2s, opacity 0.2s, transform 0.2s;
+}
+
+.llms-link-wrap:hover .llms-copy,
+.llms-link-wrap:focus-within .llms-copy,
+.llms-copy.is-copied,
+.llms-copy.is-failed {
+ opacity: 1;
+ pointer-events: auto;
+ transform: translateX(0);
}
.llms-link:hover,
@@ -137,4 +151,12 @@ async function copyLlmsTxt() {
.llms-copy.is-copied {
color: var(--vp-c-brand-1);
}
+
+@media (hover: none) {
+ .llms-copy {
+ opacity: 1;
+ pointer-events: auto;
+ transform: translateX(0);
+ }
+}
</style>
diff --git a/docs/.vitepress/theme/api-example-tabs.test.ts b/docs/.vitepress/theme/api-example-tabs.test.ts
index 2c674609e..952999ad2 100644
--- a/docs/.vitepress/theme/api-example-tabs.test.ts
+++ b/docs/.vitepress/theme/api-example-tabs.test.ts
@@ -9,7 +9,7 @@ import {
preferredLanguage,
shouldSynchronizeExampleTabs
} from './api-example-tabs.ts'
-import { hasPageLlmsTxt } from './llms-txt.ts'
+import { absoluteLlmsTxtUrl, hasPageLlmsTxt, pageLlmsTxtPath } from './llms-txt.ts'
test('hides llms.txt actions on index pages without generated artifacts', () => {
assert.equal(hasPageLlmsTxt('index.md'), false)
@@ -18,6 +18,15 @@ test('hides llms.txt actions on index pages without generated artifacts', () =>
assert.equal(hasPageLlmsTxt('en/api/01-overview.md'), true)
})
+test('builds the absolute per-page llms.txt link copied by the page action', () => {
+ const path = pageLlmsTxtPath('zh/guides/03-cli-config.md')
+ assert.equal(path, '/zh/guides/03-cli-config/llms.txt')
+ assert.equal(
+ absoluteLlmsTxtUrl(`/OpenViking${path}`, 'https://docs.openviking.net'),
+ 'https://docs.openviking.net/OpenViking/zh/guides/03-cli-config/llms.txt'
+ )
+})
+
test('recognizes language headings with punctuation and qualifiers', () => {
assert.equal(exampleLanguage('HTTP API:')?.key, 'http')
assert.equal(exampleLanguage('CLI (subcommands of resources)')?.key, 'cli')
diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
index 993f993db..96d32f196 100644
--- a/docs/.vitepress/theme/custom.css
+++ b/docs/.vitepress/theme/custom.css
@@ -223,17 +223,18 @@ html.vikingbot-assistant-resizing * {
.vikingbot-identity > span:last-child {
display: flex;
flex-direction: column;
- gap: 2px;
}
.vikingbot-identity strong {
color: var(--vp-c-text-1);
font-size: 15px;
+ line-height: 20px;
}
.vikingbot-identity small {
color: var(--vp-c-text-3);
font-size: 11px;
+ line-height: 16px;
}
.vikingbot-avatar,
diff --git a/docs/.vitepress/theme/llms-txt.ts b/docs/.vitepress/theme/llms-txt.ts
index f5da15a08..ca3626b0f 100644
--- a/docs/.vitepress/theme/llms-txt.ts
+++ b/docs/.vitepress/theme/llms-txt.ts
@@ -1,3 +1,11 @@
export function hasPageLlmsTxt(relativePath: string): boolean {
return relativePath !== 'index.md' && !relativePath.endsWith('/index.md')
}
+
+export function pageLlmsTxtPath(relativePath: string): string {
+ return `/${relativePath.replace(/\.md$/, '')}/llms.txt`
+}
+
+export function absoluteLlmsTxtUrl(path: string, origin: string): string {
+ return new URL(path, origin).href
+}
diff --git a/docs/en/api/05-sessions.md b/docs/en/api/05-sessions.md
index aaecb6349..f9402d56b 100644
--- a/docs/en/api/05-sessions.md
+++ b/docs/en/api/05-sessions.md
@@ -322,11 +322,14 @@ ov session get a1b2c3d4
"preferences": 2,
"entities": 3,
"events": 1,
+ "identity": 1,
+ "soul": 1,
"cases": 2,
- "patterns": 1,
+ "trajectories": 1,
+ "experiences": 2,
"tools": 0,
"skills": 0,
- "total": 10
+ "total": 14
},
"last_commit_at": "2026-03-23T11:00:00+08:00",
"llm_token_usage": {
@@ -1528,7 +1531,7 @@ An empty `memory_diff.json` (all counts zero) is written when long-term memory e
---
-## Memory Categories
+## Built-in Memory Types
| Category | Location | Description |
|----------|----------|-------------|
@@ -1536,11 +1539,16 @@ An empty `memory_diff.json` (all counts zero) is written when long-term memory e
| preferences | `user/memories/preferences/` | User preferences by topic |
| entities | `user/memories/entities/` | Important entities (people, projects) |
| events | `user/memories/events/` | Significant events |
+| identity | `user/memories/identity.md` | Assistant identity and self-introduction |
+| soul | `user/memories/soul.md` | Assistant principles, boundaries, style, and continuity |
+| cases | `user/memories/cases/` | Trainable and evaluable task cases |
| trajectories | `user/memories/trajectories/` | Reusable operation contracts |
| experiences | `user/memories/experiences/` | Reusable execution insights |
| tools | `user/memories/tools/` | Tool usage knowledge and best practices |
| skills | `user/memories/skills/` | Skill execution knowledge and workflow strategies |
+These are the enabled built-in types. Deployments can extend or override them with custom memory templates.
+
---
## Full Example
diff --git a/docs/en/concepts/01-architecture.md b/docs/en/concepts/01-architecture.md
index ad8ff884d..0e777d352 100644
--- a/docs/en/concepts/01-architecture.md
+++ b/docs/en/concepts/01-architecture.md
@@ -58,7 +58,7 @@ OpenViking is a context database designed for AI Agents, unifying all context ty
| **Retrieve** | Context retrieval | Intent analysis (IntentAnalyzer), hierarchical retrieval (HierarchicalRetriever), Rerank |
| **Session** | Session management | Message recording, usage tracking, session compression, memory commit |
| **Parse** | Context extraction | Document parsing (PDF/MD/HTML), tree building (TreeBuilder), async semantic generation |
-| **Compressor** | Memory compression | 8-category memory extraction, LLM deduplication decisions |
+| **Compressor** | Memory compression | Schema-driven memory extraction and LLM deduplication decisions |
| **Storage** | Storage layer | VikingFS virtual filesystem, vector index, AGFS integration |
## Service Layer
@@ -117,7 +117,7 @@ Messages → Compress → Archive → Memory Extraction → Storage
1. **Messages**: Accumulate conversation messages and usage records
2. **Compress**: Keep recent N rounds, archive older messages
3. **Archive**: Generate L0/L1 for history segments
-4. **Memory Extraction**: Extract 8-category memories from messages
+4. **Memory Extraction**: Extract memories from messages according to the memory policy and MemoryType schemas
5. **Storage**: Write to AGFS + vector index
## Deployment Modes
diff --git a/docs/en/concepts/02-context-types.md b/docs/en/concepts/02-context-types.md
index 9001a880a..a7efd9ba7 100644
--- a/docs/en/concepts/02-context-types.md
+++ b/docs/en/concepts/02-context-types.md
@@ -44,7 +44,7 @@ results = client.find(
## Memory
-Memories are divided into user memories and Agent memories, representing learned knowledge about users and the world.
+Memories are durable knowledge learned from interactions and task execution. They are stored in the current User or Peer namespace, not in a separate `viking://agent/memories` directory.
### Characteristics
@@ -52,18 +52,23 @@ Memories are divided into user memories and Agent memories, representing learned
- **Dynamic updates**: Continuously updated from interactions by Agent
- **Personalized**: Learned for specific users and stable peers
-### 8 Categories
-
-| Category | Location | Description | Update Strategy |
-|----------|----------|-------------|-----------------|
-| **profile** | `user/memories/profile.md` | User basic info | ✅ Merge into one file |
-| **preferences** | `user/memories/preferences/` | User preferences by topic | ✅ Appendable |
-| **entities** | `user/memories/entities/` | Entity memories (people, projects) | ✅ Appendable |
-| **events** | `user/memories/events/` | Event records (decisions, milestones) | ❌ No update |
-| **trajectories** | `user/memories/trajectories/` | Reusable operation contracts | ❌ No update |
-| **experiences** | `user/memories/experiences/` | Reusable execution insights | ✅ Mergeable |
-| **tools** | `user/memories/tools/` | Tool usage knowledge and best practices | ✅ Mergeable |
-| **skills** | `user/memories/skills/` | Skill execution knowledge and workflow strategies | ✅ Mergeable |
+### Built-in Memory Types
+
+| Type | Default location | Description |
+|------|------------------|-------------|
+| **profile** | `user/memories/profile.md` | Basic user information |
+| **preferences** | `user/memories/preferences/` | User preferences organized by topic |
+| **entities** | `user/memories/entities/` | Knowledge about people, projects, organizations, and other entities |
+| **events** | `user/memories/events/` | Decisions, milestones, and other event records |
+| **identity** | `user/memories/identity.md` | Assistant name, persona, temperament, and self-introduction |
+| **soul** | `user/memories/soul.md` | Assistant principles, boundaries, style, and continuity |
+| **cases** | `user/memories/cases/` | Task cases used for training and evaluation |
+| **trajectories** | `user/memories/trajectories/` | Reusable task-execution trajectories |
+| **experiences** | `user/memories/experiences/` | Reusable experience distilled from execution outcomes |
+| **tools** | `user/memories/tools/` | Tool usage knowledge and best practices |
+| **skills** | `user/memories/skills/` | Skill-execution knowledge and workflow strategies |
+
+The `user/...` entries above are current-user short paths. The server resolves them to `viking://user/{user_id}/...`. When the memory policy permits Peer memory, supported types may instead be written under `viking://user/{user_id}/peers/{peer_id}/memories/...`. Applications can extend or adjust memory types with custom templates.
### Usage
diff --git a/docs/en/concepts/04-viking-uri.md b/docs/en/concepts/04-viking-uri.md
index 0e9e0057d..9d8b8d518 100644
--- a/docs/en/concepts/04-viking-uri.md
+++ b/docs/en/concepts/04-viking-uri.md
@@ -94,8 +94,9 @@ viking://user/resources/docs/ # Current user's resource director
viking://user/skills/ # Current user's skills
viking://user/skills/search-web # Specific skill
viking://user/memories/ # Current user's memories
-viking://user/memories/cases/ # Learned cases
-viking://user/memories/patterns/ # Learned patterns
+viking://user/memories/cases/ # Task cases used for training and evaluation
+viking://user/memories/trajectories/ # Reusable task-execution trajectories
+viking://user/memories/experiences/ # Experience distilled from execution outcomes
viking://user/{user_id}/peers/{peer_id}/memories/
viking://user/{user_id}/peers/{peer_id}/resources/
```
diff --git a/docs/en/concepts/08-session.md b/docs/en/concepts/08-session.md
index bfac42c20..0b7d673e9 100644
--- a/docs/en/concepts/08-session.md
+++ b/docs/en/concepts/08-session.md
@@ -143,18 +143,11 @@ Unfinished tasks
## Memory Extraction
-### 8 Categories
-
-| Category | Belongs to | Description | Mergeable |
-|----------|------------|-------------|-----------|
-| **profile** | user | User identity/attributes | ✅ |
-| **preferences** | user | User preferences | ✅ |
-| **entities** | user | Entities (people/projects) | ✅ |
-| **events** | user | Events/decisions | ❌ |
-| **cases** | agent | Problem + solution | ❌ |
-| **patterns** | agent | Reusable patterns | ✅ |
-| **tools** | agent | Tool usage knowledge and best practices | ✅ |
-| **skills** | agent | Skill execution knowledge and workflow strategies | ✅ |
+### Memory Types
+
+After a session is committed, OpenViking uses the conversation and active memory policy to extract information that can improve future interactions. It stores the result in the current user's memory space. When a conversation involves a stable Peer, relevant memories can also be stored in that Peer's space.
+
+OpenViking includes memory types such as `profile`, `preferences`, `entities`, `events`, `identity`, `soul`, `cases`, `trajectories`, `experiences`, `tools`, and `skills`, and supports custom types for application-specific needs. See [Context Types](./02-context-types.md) for the complete purpose and path mapping.
### Extraction Flow
@@ -248,14 +241,15 @@ viking://user/{user_id}/sessions/{session_id}/
└── {tool_id}/tool.json
viking://user/memories/
-├── profile.md # Append-only user profile
+├── profile.md
+├── identity.md
+├── soul.md
├── preferences/
├── entities/
-└── events/
-
-viking://user/memories/
+├── events/
├── cases/
-├── patterns/
+├── trajectories/
+├── experiences/
├── tools/
└── skills/
```
diff --git a/docs/en/faq/faq.md b/docs/en/faq/faq.md
index 8a748f251..ce63d4dc0 100644
--- a/docs/en/faq/faq.md
+++ b/docs/en/faq/faq.md
@@ -20,7 +20,7 @@ OpenViking unifies all context management through a filesystem paradigm, enablin
| **Storage Model** | Flat vector storage | Hierarchical filesystem (AGFS) |
| **Retrieval Method** | Single vector similarity search | Directory recursive retrieval + Intent analysis + Rerank |
| **Output Format** | Raw chunks | Structured context (L0 Abstract/L1 Overview/L2 Details) |
-| **Memory Capability** | Not supported | Built-in 6 memory categories with auto-extraction and iteration |
+| **Memory Capability** | Not supported | Multiple extensible memory types with automatic extraction and continuous iteration |
| **Observability** | Black box | Fully traceable retrieval trajectory |
| **Context Types** | Documents only | Resource + Memory + Skill three types |
@@ -44,11 +44,16 @@ Viking URI is OpenViking's unified resource identifier, formatted as `viking://{
viking://
├── resources/ # Knowledge base: documents, code, web pages, etc.
│ └── my_project/
-├── user/ # User context
-│ └── memories/ # User memories (preferences, entities, events)
-└── agent/ # Agent context
- ├── skills/ # Callable skills
- └── memories/ # Agent memories (cases, patterns)
+├── user/
+│ └── {user_id}/ # Private context for a user
+│ ├── memories/ # User memories
+│ ├── resources/ # Private user resources
+│ ├── skills/ # Private user skills (default)
+│ └── peers/{peer_id}/
+│ ├── memories/ # Memories scoped to a peer
+│ └── resources/ # Resources scoped to a peer
+└── agent/ # Optional account-wide Agent capabilities
+ └── skills/ # Shared skills
```
## Installation & Configuration
@@ -232,16 +237,9 @@ await session.commit()
### What memory types does OpenViking support?
-OpenViking has 6 built-in memory categories, automatically extracted during session commit:
+OpenViking includes memory types such as `profile`, `preferences`, `entities`, `events`, `identity`, `soul`, `cases`, `trajectories`, `experiences`, `tools`, and `skills`. After a session is committed, the active memory policy determines which useful information to extract. Applications can also extend or adjust the memory types for their own needs.
-| Category | Belongs To | Description |
-|----------|------------|-------------|
-| **profile** | user | User basic info (name, role, etc.) |
-| **preferences** | user | User preferences (code style, tool choices, etc.) |
-| **entities** | user | Entity memories (people, projects, organizations, etc.) |
-| **events** | user | Event records (decisions, milestones, etc.) |
-| **cases** | agent | Cases learned by Agent |
-| **patterns** | agent | Patterns learned by Agent |
+Memories are stored in the current User or Peer namespace; there is no current writable `viking://agent/memories` directory. See [Context Types](../concepts/02-context-types.md) for the complete type and path mapping.
### How do I use Unix-like filesystem APIs?
diff --git a/docs/en/getting-started/01-introduction.md b/docs/en/getting-started/01-introduction.md
index 357075a00..c334f8f70 100644
--- a/docs/en/getting-started/01-introduction.md
+++ b/docs/en/getting-started/01-introduction.md
@@ -26,11 +26,18 @@ Moving away from traditional flat database thinking, all context is organized as
viking://
├── resources/ # Resources: project docs, code repos, web pages
│ └── my_project/
-├── user/ # User: preferences, habits
-│ └── memories/
-└── agent/ # Agent: skills, instructions, task memories
- ├── skills/
- └── memories/
+├── user/
+│ └── {user_id}/ # Private context for the current user
+│ ├── memories/ # User memories
+│ ├── resources/ # Private user resources
+│ ├── skills/ # Private user skills (default)
+│ ├── peers/
+│ │ └── {peer_id}/
+│ │ ├── memories/
+│ │ └── resources/
+│ └── sessions/
+└── agent/
+ └── skills/ # Optional account-wide shared skills
```
**Three Context Types**:
@@ -92,18 +99,17 @@ The retrieval process uses directory recursive strategy, with complete traces of
### 5. Automatic Session Management
-OpenViking has built-in memory self-iteration loops. At the end of each session, developers can trigger memory extraction, and the system asynchronously analyzes task execution results and user feedback, automatically updating User and Agent memory directories.
+OpenViking includes a memory self-iteration loop. After a session is committed, the system asynchronously analyzes task outcomes and user feedback, then updates memory for the current user or Peer according to the active memory policy.
-**6 Memory Categories**:
+**Built-in memory types**:
-| Category | Owner | Description |
-|----------|-------|-------------|
-| **profile** | user | User basic information |
-| **preferences** | user | User preferences by topic |
-| **entities** | user | Entity memories (people, projects) |
-| **events** | user | Event records (decisions, milestones) |
-| **cases** | agent | Learned cases |
-| **patterns** | agent | Learned patterns |
+| Purpose | Built-in types | Description |
+|---------|----------------|-------------|
+| **User and environment understanding** | `profile`, `preferences`, `entities`, `events` | User profile, preferences, entities, and events |
+| **Assistant identity and continuity** | `identity`, `soul` | Assistant identity, boundaries, style, and continuity |
+| **Task execution and learning** | `cases`, `trajectories`, `experiences`, `tools`, `skills` | Trainable cases, execution traces, reusable experience, and tool/skill usage knowledge |
+
+OpenViking lets applications extend or adjust memory types for their own needs.
Enabling Agents to become "smarter with use" through world interaction, achieving self-evolution.
diff --git a/docs/en/guides/10-prompt-guide.md b/docs/en/guides/10-prompt-guide.md
index cacef59fd..cddc9a0c1 100644
--- a/docs/en/guides/10-prompt-guide.md
+++ b/docs/en/guides/10-prompt-guide.md
@@ -196,9 +196,9 @@ These YAML files define the structure of different memory types. They are not si
- `cases`
- Effective stage: case-memory persistence and update stage
- - Affects: reusable problem-to-solution case accumulation
- - Purpose: defines case memory for "what problem happened and how it was solved"
- - Key fields: `case_name`, `problem`, `solution`, `content`
+ - Affects: trainable and evaluable task-case accumulation
+ - Purpose: defines concrete task inputs, evaluation rubrics, and supporting evidence
+ - Key fields: `case_name`, `task_signature`, `input`, `rubric`, `evidence`
- `entities`
- Effective stage: entity-memory persistence and update stage
@@ -212,17 +212,17 @@ These YAML files define the structure of different memory types. They are not si
- Purpose: defines structured event memory such as summaries, goals, and time ranges
- Key fields: `event_name`, `goal`, `summary`, `ranges`
+- `experiences`
+ - Effective stage: experience-memory persistence and update stage
+ - Affects: reusable guidance distilled from task outcomes
+ - Purpose: records durable execution experience and the memories it supersedes
+ - Key fields: `experience_name`, `content`, `supersedes`
+
- `identity`
- Effective stage: agent identity memory persistence stage
- Affects: long-term consistency of the agent's identity settings
- Purpose: defines the agent's name, persona, vibe, avatar, and self-introduction fields
- - Key fields: `name`, `creature`, `vibe`, `emoji`, `avatar`
-
-- `patterns`
- - Effective stage: pattern-memory persistence and update stage
- - Affects: long-term accumulation of reusable workflows and methods
- - Purpose: defines pattern memory for "under what circumstances to follow what process"
- - Key fields: `pattern_name`, `pattern_type`, `content`
+ - Key fields: `name`, `creature`, `vibe`, `emoji`, `avatar`, `introduction`
- `preferences`
- Effective stage: preference-memory persistence and update stage
diff --git a/docs/zh/api/05-sessions.md b/docs/zh/api/05-sessions.md
index b04709468..d0ada4ff7 100644
--- a/docs/zh/api/05-sessions.md
+++ b/docs/zh/api/05-sessions.md
@@ -322,11 +322,14 @@ ov session get a1b2c3d4
"preferences": 2,
"entities": 3,
"events": 1,
+ "identity": 1,
+ "soul": 1,
"cases": 2,
- "patterns": 1,
+ "trajectories": 1,
+ "experiences": 2,
"tools": 0,
"skills": 0,
- "total": 10
+ "total": 14
},
"last_commit_at": "2026-03-23T11:00:00+08:00",
"llm_token_usage": {
@@ -1500,7 +1503,7 @@ viking://user/{user_id}/sessions/{session_id}/
---
-## 记忆分类
+## 内置记忆类型
| 分类 | 位置 | 说明 |
|------|------|------|
@@ -1508,11 +1511,16 @@ viking://user/{user_id}/sessions/{session_id}/
| preferences | `user/memories/preferences/` | 按主题分类的用户偏好 |
| entities | `user/memories/entities/` | 重要实体(人物、项目等) |
| events | `user/memories/events/` | 重要事件 |
+| identity | `user/memories/identity.md` | 助手身份与自我介绍 |
+| soul | `user/memories/soul.md` | 助手原则、边界、风格和连续性 |
+| cases | `user/memories/cases/` | 可训练、可评估的任务案例 |
| trajectories | `user/memories/trajectories/` | 可复用的操作契约 |
| experiences | `user/memories/experiences/` | 可复用的执行经验 |
| tools | `user/memories/tools/` | 工具使用经验与最佳实践 |
| skills | `user/memories/skills/` | 技能执行经验与工作流策略 |
+以上是当前启用的内置类型;部署可以通过自定义记忆模板扩展或覆盖。
+
---
## 完整示例
diff --git a/docs/zh/concepts/01-architecture.md b/docs/zh/concepts/01-architecture.md
index ea569c8d5..cb5be0289 100644
--- a/docs/zh/concepts/01-architecture.md
+++ b/docs/zh/concepts/01-architecture.md
@@ -57,7 +57,7 @@ OpenViking 是为 AI Agent 设计的上下文数据库,将所有上下文(Me
| **Retrieve** | 上下文检索 | 意图分析(IntentAnalyzer)、层级检索(HierarchicalRetriever)、Rerank 精排 |
| **Session** | 会话管理 | 消息记录、使用追踪、会话压缩、记忆提交 |
| **Parse** | 上下文提取 | 文档解析(PDF/MD/HTML)、树构建(TreeBuilder)、异步语义生成 |
-| **Compressor** | 记忆压缩 | 8 种记忆分类提取、LLM 去重决策 |
+| **Compressor** | 记忆压缩 | Schema 驱动的记忆提取、LLM 去重决策 |
| **Storage** | 存储层 | VikingFS 虚拟文件系统、向量索引、AGFS 集成 |
## Service 层
@@ -116,7 +116,7 @@ OpenViking 采用双层存储架构,实现内容与索引分离(详见 [存
1. **消息**:累积对话消息和使用记录
2. **压缩**:保留最近 N 轮,旧消息归档
3. **归档**:生成历史片段的 L0/L1
-4. **记忆提取**:从消息中提取 8 种分类记忆
+4. **记忆提取**:根据记忆策略和 MemoryType Schema 从消息中提取记忆
5. **存储**:写入 AGFS + 向量库
## 部署模式
diff --git a/docs/zh/concepts/02-context-types.md b/docs/zh/concepts/02-context-types.md
index ae29df623..0f073eb82 100644
--- a/docs/zh/concepts/02-context-types.md
+++ b/docs/zh/concepts/02-context-types.md
@@ -44,7 +44,7 @@ results = client.find(
## Memory(记忆)
-记忆分为用户记忆和Agent记忆,是 Agent 关于用户和世界的学习知识。
+记忆是 Agent 从交互和任务执行中学到的持久化知识。记忆存储在当前用户或 Peer 命名空间,不使用独立的 `viking://agent/memories` 目录。
### 特点
@@ -52,18 +52,23 @@ results = client.find(
- **动态更新:**由 Agent 从交互中持续更新
- **个性化:**针对特定用户和稳定 peer 学习记录
-### 8 种分类
-
-| 分类 | 位置 | 说明 | 更新策略 |
-|------|------|------|----------|
-| **profile** | `user/memories/profile.md` | 用户基本信息 | ✅ 合并到单文件 |
-| **preferences** | `user/memories/preferences/` | 按主题的用户偏好 | ✅ 可追加 |
-| **entities** | `user/memories/entities/` | 实体记忆(人物、项目) | ✅ 可追加 |
-| **events** | `user/memories/events/` | 事件记录(决策、里程碑) | ❌ 不更新 |
-| **trajectories** | `user/memories/trajectories/` | 可复用的操作契约 | ❌ 不更新 |
-| **experiences** | `user/memories/experiences/` | 可复用的执行经验 | ✅ 可合并 |
-| **tools** | `user/memories/tools/` | 工具使用经验与最佳实践 | ✅ 可合并 |
-| **skills** | `user/memories/skills/` | 技能执行经验与工作流策略 | ✅ 可合并 |
+### 内置记忆类型
+
+| 类型 | 默认位置 | 说明 |
+|------|----------|------|
+| **profile** | `user/memories/profile.md` | 用户基本信息 |
+| **preferences** | `user/memories/preferences/` | 按主题组织的用户偏好 |
+| **entities** | `user/memories/entities/` | 人物、项目、组织等实体知识 |
+| **events** | `user/memories/events/` | 决策、里程碑等事件记录 |
+| **identity** | `user/memories/identity.md` | 助手的名称、形象、气质和自我介绍 |
+| **soul** | `user/memories/soul.md` | 助手的核心原则、边界、风格和连续性 |
+| **cases** | `user/memories/cases/` | 用于训练和评估的任务案例 |
+| **trajectories** | `user/memories/trajectories/` | 可复用的任务执行轨迹 |
+| **experiences** | `user/memories/experiences/` | 从执行结果中提炼的可复用经验 |
+| **tools** | `user/memories/tools/` | 工具使用经验与最佳实践 |
+| **skills** | `user/memories/skills/` | 技能执行经验与工作流策略 |
+
+表中的 `user/...` 是当前用户短路径,服务端会将其解析为 `viking://user/{user_id}/...`。当记忆策略允许 Peer 记忆时,支持 Peer 的类型会写入 `viking://user/{user_id}/peers/{peer_id}/memories/...`。记忆类型可通过自定义模板扩展或调整。
### 使用
diff --git a/docs/zh/concepts/04-viking-uri.md b/docs/zh/concepts/04-viking-uri.md
index 5994e65cb..c0b61fa34 100644
--- a/docs/zh/concepts/04-viking-uri.md
+++ b/docs/zh/concepts/04-viking-uri.md
@@ -92,8 +92,9 @@ viking://user/resources/docs/ # 当前用户资源目录
viking://user/skills/ # 当前用户的技能
viking://user/skills/search-web # 某个技能
viking://user/memories/ # 当前用户的记忆
-viking://user/memories/cases/ # 学习的案例
-viking://user/memories/patterns/ # 学习的模式
+viking://user/memories/cases/ # 用于训练和评估的任务案例
+viking://user/memories/trajectories/ # 可复用的任务执行轨迹
+viking://user/memories/experiences/ # 从执行结果中提炼的经验
viking://user/{user_id}/peers/{peer_id}/memories/
viking://user/{user_id}/peers/{peer_id}/resources/
```
diff --git a/docs/zh/concepts/08-session.md b/docs/zh/concepts/08-session.md
index 848edb4e9..d35e9b8b5 100644
--- a/docs/zh/concepts/08-session.md
+++ b/docs/zh/concepts/08-session.md
@@ -143,18 +143,11 @@ commit() 分两阶段执行:
## 记忆提取
-### 8 种分类
-
-| 分类 | 归属 | 说明 | 可合并 |
-|------|------|------|--------|
-| **profile** | user | 用户身份/属性 | ✅ |
-| **preferences** | user | 用户偏好 | ✅ |
-| **entities** | user | 实体(人/项目) | ✅ |
-| **events** | user | 事件/决策 | ❌ |
-| **cases** | agent | 问题+解决方案 | ❌ |
-| **patterns** | agent | 可复用流程 | ✅ |
-| **tools** | agent | 工具使用经验与最佳实践 | ✅ |
-| **skills** | agent | 技能执行经验与工作流策略 | ✅ |
+### 记忆类型
+
+提交会话后,OpenViking 会根据对话内容和当前记忆策略,提取对后续交互有价值的信息,并保存到当前用户的记忆空间。当对话涉及稳定的 Peer 时,相关记忆也可以保存到对应的 Peer 空间。
+
+OpenViking 内置 `profile`、`preferences`、`entities`、`events`、`identity`、`soul`、`cases`、`trajectories`、`experiences`、`tools` 和 `skills` 等记忆类型,也支持根据业务需要自定义。完整用途与路径见 [上下文类型](./02-context-types.md)。
### 提取流程
@@ -248,14 +241,15 @@ viking://user/{user_id}/sessions/{session_id}/
└── {tool_id}/tool.json
viking://user/memories/
-├── profile.md # 追加式用户画像
+├── profile.md
+├── identity.md
+├── soul.md
├── preferences/
├── entities/
-└── events/
-
-viking://user/memories/
+├── events/
├── cases/
-├── patterns/
+├── trajectories/
+├── experiences/
├── tools/
└── skills/
```
diff --git a/docs/zh/faq/faq.md b/docs/zh/faq/faq.md
index 604875feb..740e977c8 100644
--- a/docs/zh/faq/faq.md
+++ b/docs/zh/faq/faq.md
@@ -20,7 +20,7 @@ OpenViking 通过文件系统范式统一管理所有上下文,实现分层供
| **存储模型** | 扁平化向量存储 | 层级化文件系统(AGFS) |
| **检索方式** | 单一向量相似度搜索 | 目录递归检索 + 意图分析 + Rerank |
| **输出形式** | 原始分块 | 结构化上下文(L0 摘要/L1 概览/L2 详情) |
-| **记忆能力** | 不支持 | 内置 6 种记忆分类,支持自动提取和迭代 |
+| **记忆能力** | 不支持 | 内置多种可扩展的记忆类型,支持自动提取和持续迭代 |
| **可观测性** | 黑箱 | 检索轨迹完整可追溯 |
| **上下文类型** | 仅文档 | Resource + Memory + Skill 三种类型 |
@@ -44,11 +44,17 @@ Viking URI 是 OpenViking 的统一资源标识符,格式为 `viking://{scope}
viking://
├── resources/ # 知识库:文档、代码、网页等
│ └── my_project/
-├── user/ # 用户上下文
-│ ├── skills/ # 可调用技能
-│ ├── memories/ # 用户记忆(偏好、实体、事件)
-│ └── peers/ # 针对稳定 peer 的一对多记忆
-└── session/ # 会话与历史归档
+├── user/
+│ └── {user_id}/ # 用户私有上下文
+│ ├── memories/ # 用户记忆
+│ ├── resources/ # 用户私有资源
+│ ├── skills/ # 用户私有技能(默认)
+│ ├── peers/{peer_id}/
+│ │ ├── memories/ # Peer 记忆
+│ │ └── resources/ # Peer 资源
+│ └── sessions/ # 会话与历史归档
+└── agent/ # 可选的 account 全局能力
+ └── skills/ # 共享技能
```
## 安装与配置
@@ -224,16 +230,9 @@ await session.commit()
### OpenViking 支持哪些记忆类型?
-OpenViking 内置 6 种记忆分类,在会话提交时自动提取:
+OpenViking 内置 `profile`、`preferences`、`entities`、`events`、`identity`、`soul`、`cases`、`trajectories`、`experiences`、`tools` 和 `skills` 等记忆类型。提交会话后,系统会按当前记忆策略提取适用内容;也可以根据业务需要扩展或调整记忆类型。
-| 分类 | 归属 | 说明 |
-|------|------|------|
-| **profile** | user | 用户基本信息(姓名、角色等) |
-| **preferences** | user | 用户偏好(代码风格、工具选择等) |
-| **entities** | user | 实体记忆(人物、项目、组织等) |
-| **events** | user | 事件记录(决策、里程碑等) |
-| **cases** | agent | Agent 学习的案例 |
-| **patterns** | agent | Agent 学习的模式 |
+记忆存储在当前用户或 Peer 命名空间,不存在当前可写的 `viking://agent/memories` 目录。完整类型与路径见 [上下文类型](../concepts/02-context-types.md)。
### 如何使用类 Unix 的文件系统 API?
diff --git a/docs/zh/getting-started/01-introduction.md b/docs/zh/getting-started/01-introduction.md
index 21f79cb70..50d3a1ee7 100644
--- a/docs/zh/getting-started/01-introduction.md
+++ b/docs/zh/getting-started/01-introduction.md
@@ -26,11 +26,18 @@ OpenViking 正是为解决这些痛点而设计的上下文数据库。
viking://
├── resources/ # 资源:项目文档、代码库、网页等
│ └── my_project/
-├── user/ # 用户:个人偏好、习惯等
-│ └── memories/
-└── agent/ # Agent:技能、指令、任务记忆等
- ├── skills/
- └── memories/
+├── user/
+│ └── {user_id}/ # 当前用户的私有上下文
+│ ├── memories/ # 用户记忆
+│ ├── resources/ # 用户私有资源
+│ ├── skills/ # 用户私有技能(默认)
+│ ├── peers/
+│ │ └── {peer_id}/
+│ │ ├── memories/
+│ │ └── resources/
+│ └── sessions/
+└── agent/
+ └── skills/ # account 全局共享技能(可选)
```
**三种上下文类型**:
@@ -92,18 +99,17 @@ OpenViking 的组织方式采用层次化虚拟文件系统结构,所有上下
### 5. 会话自动管理
-OpenViking 内置了记忆自迭代闭环。在每次会话结束时,开发者可以主动触发记忆提取机制,系统会异步分析任务执行结果与用户反馈,并自动更新至 User 和 Agent 的记忆目录下。
+OpenViking 内置记忆自迭代闭环。提交会话后,系统会异步分析任务执行结果与用户反馈,并根据记忆策略更新当前用户或 Peer 的记忆。
-**6 种记忆分类**:
+**内置记忆类型**:
-| 分类 | 归属 | 说明 |
-|------|------|------|
-| **profile** | user | 用户基本信息 |
-| **preferences** | user | 按主题的用户偏好 |
-| **entities** | user | 实体记忆(人物、项目) |
-| **events** | user | 事件记录(决策、里程碑) |
-| **cases** | agent | 学习的案例 |
-| **patterns** | agent | 学习的模式 |
+| 用途 | 内置类型 | 说明 |
+|------|----------|------|
+| **用户与环境理解** | `profile`、`preferences`、`entities`、`events` | 记录用户画像、偏好、实体和事件 |
+| **助手身份与连续性** | `identity`、`soul` | 记录助手身份、边界、风格和连续性 |
+| **任务执行与学习** | `cases`、`trajectories`、`experiences`、`tools`、`skills` | 沉淀可训练案例、执行轨迹、经验和工具/技能使用知识 |
+
+OpenViking 支持根据业务需要扩展或调整记忆类型。
让 Agent 在与世界的交互中"越用越聪明",实现自我进化。
diff --git a/docs/zh/guides/10-prompt-guide.md b/docs/zh/guides/10-prompt-guide.md
index b0f25454c..a23c31e61 100644
--- a/docs/zh/guides/10-prompt-guide.md
+++ b/docs/zh/guides/10-prompt-guide.md
@@ -192,13 +192,13 @@ peer_enabled: true
### Memory
-这一类 YAML 定义不同记忆类型的结构,不是单次推理 prompt。它们共同决定用户记忆和 agent 记忆如何落盘、如何更新、如何被后续检索使用。
+这一类 YAML 定义不同记忆类型的结构,不是单次推理 prompt。它们共同决定当前用户或 Peer 的记忆如何落盘、如何更新、如何被后续检索使用。
- `cases`
- 生效环节:案例型记忆落盘与更新阶段
- - 影响能力:问题到解决方案的案例沉淀与复用
- - 作用:定义“遇到了什么问题、如何解决”的案例型记忆
- - 关键字段:`case_name`、`problem`、`solution`、`content`
+ - 影响能力:可训练、可评估的任务案例沉淀
+ - 作用:定义具体任务输入、评估标准和支撑证据
+ - 关键字段:`case_name`、`task_signature`、`input`、`rubric`、`evidence`
- `entities`
- 生效环节:实体型记忆落盘与更新阶段
@@ -212,17 +212,17 @@ peer_enabled: true
- 作用:定义事件摘要、目标、时间范围等结构化事件记忆
- 关键字段:`event_name`、`goal`、`summary`、`ranges`
+- `experiences`
+ - 生效环节:经验型记忆落盘与更新阶段
+ - 影响能力:从任务结果中沉淀可复用指导
+ - 作用:记录持久的执行经验及其替代的旧记忆
+ - 关键字段:`experience_name`、`content`、`supersedes`
+
- `identity`
- 生效环节:agent identity 记忆落盘阶段
- 影响能力:agent 身份设定的长期一致性
- 作用:定义 agent 的名字、形象、风格、自我介绍等身份字段
- - 关键字段:`name`、`creature`、`vibe`、`emoji`、`avatar`
-
-- `patterns`
- - 生效环节:模式型记忆落盘与更新阶段
- - 影响能力:可复用流程和方法的长期积累
- - 作用:定义“在什么情况下按什么流程处理”的模式记忆
- - 关键字段:`pattern_name`、`pattern_type`、`content`
+ - 关键字段:`name`、`creature`、`vibe`、`emoji`、`avatar`、`introduction`
- `preferences`
- 生效环节:偏好型记忆落盘与更新阶段
diff --git a/examples/pi-coding-agent-extension/DESIGN.md b/examples/pi-coding-agent-extension/DESIGN.md
index 76edfe505..3be878772 100644
--- a/examples/pi-coding-agent-extension/DESIGN.md
+++ b/examples/pi-coding-agent-extension/DESIGN.md
@@ -156,9 +156,9 @@ Without this index, the model is flying blind — it can only retrieve what it t
#### What goes into the index
-The index has two parts, both built from OV's filesystem API:
+The index has three parts, built from OV's filesystem and session APIs:
-1. **Directory listing**: `client.ls("viking://")` → top-level children (user/, agent/, resources/, session/), then one level deeper for each. Shows *what categories of knowledge exist*.
+1. **Directory listing**: `client.ls("viking://")` → visible resources, the current user's namespace, and optional account-shared skills. Shows *what categories of knowledge exist*.
2. **Abstract summaries**: For each leaf memory in `viking://user/memories/`, fetch L0 abstracts. These are ~100 tokens each and give the model a one-line summary of each stored memory.
3. **Archive overview**: If the current session has a previous archive, its L1 overview (~2k tokens) is included as `[Session History Summary]`.
@@ -189,7 +189,7 @@ The index is injected into the system prompt (via `before_agent_start`'s `system
- Project X architecture diagram (viking://resources/projx-arch)
- (1 more — use viking_browse to explore)
-### viking://session/archives/ (2 archives)
+### viking://user/sessions/{session_id}/history/ (2 archives)
- Archive 2026-05-25: 15-turn session about pi extension design
- (1 more — use viking_archive_expand for detail)
@@ -228,12 +228,11 @@ Synchronous recall that runs on every user prompt, injecting relevant OV context
1. Extract query text from the user's prompt (plain text, no tool calls/images)
2. **Short-circuit**: if query length < `recallMinQueryLength` (default 3), skip recall — queries like "y", "ok", "go" don't carry enough signal for useful retrieval (from Claude Code plugin)
-3. **Triple-scope parallel search**: three concurrent `client.find()` calls via `Promise.all` (from Claude Code plugin). All URIs are dynamically resolved via `client.resolveTargetUri()` to insert the correct user/agent namespace (see client.ts → URI space resolution):
+3. **Dual-scope parallel search**: two concurrent `client.find()` calls via `Promise.all`. Current-user shorthand URIs are resolved against the authenticated user:
- `viking://user/memories` → resolved to `viking://user/<space>/memories` → user's personal memories
- - `viking://agent/memories` → resolved to `viking://agent/<space>/memories` → agent's operational memories
- - `viking://agent/skills` → resolved to `viking://agent/<space>/skills` → stored skills and procedures
+ - `viking://user/skills` → resolved to `viking://user/<space>/skills` → user's installed Skill definitions
- Resources are explicitly excluded from automatic recall (cross-namespace leakage prevention — resources can be searched on demand via `viking_search` with `scope`). Per-source limit: `max(recallLimit * 2, 8)` = up to 12 candidates per source (36 total before filtering).
+ Resources are explicitly excluded from automatic recall (cross-namespace leakage prevention — resources can be searched on demand via `viking_search` with `scope`). Per-source limit: `max(recallLimit * 2, 8)` = up to 12 candidates per source (24 total before filtering).
4. **Query profiling**: analyze the query for intent signals before ranking (from Claude Code plugin):
```typescript
function buildQueryProfile(query: string): QueryProfile {
@@ -312,7 +311,7 @@ class RecallManager {
[System note: The following is recalled memory from OpenViking, NOT new user input. Treat as informational background data.]
- [memory 0.87] User prefers local/self-hosted solutions over cloud services
- [memory 0.82] Project uses SQLite for local dev, pool size 5
-- [skill 0.73] Use viking_read to expand: viking://agent/skills/deployment-checklist.md
+- [skill 0.73] Use viking_read to expand: viking://user/skills/deployment-checklist.md
</relevant-memories>
```
diff --git a/openviking/eval/datasets/local_doc_example_glm5.jsonl b/openviking/eval/datasets/local_doc_example_glm5.jsonl
index 3032461b7..ec42d4834 100644
--- a/openviking/eval/datasets/local_doc_example_glm5.jsonl
+++ b/openviking/eval/datasets/local_doc_example_glm5.jsonl
@@ -1,6 +1,6 @@
{"question": "OpenViking 的核心定位是什么?与传统向量数据库(如 Milvus、Pinecone)有何本质区别?", "files": ["OpenViking/README.md", "OpenViking/docs/en/concepts/01-architecture.md"], "answer": "OpenViking 是一个专门为 AI Agent 设计的开源上下文数据库(Context Database)。与传统向量数据库的本质区别在于:\n\n1. **设计范式不同**:OpenViking 采用\"文件系统范式\"统一管理记忆、资源和技能,而传统向量数据库仅提供扁平的向量存储。\n\n2. **解决的问题不同**:OpenViking 解决 Agent 开发中的五大挑战:上下文碎片化、上下文需求激增、检索效果差、上下文不可观察、记忆迭代受限。传统向量数据库主要解决向量检索问题。\n\n3. **功能特性不同**:\n - 分层上下文加载(L0/L1/L2三层结构)显著降低 Token 消耗\n - 目录递归检索结合目录定位与语义搜索\n - 可视化检索轨迹,支持调试\n - 自动会话管理,实现上下文自我迭代\n\n4. **架构层次**:OpenViking 包含 Client、Service、Retrieve、Session、Parse、Compressor、Storage 等多层架构,而传统向量数据库主要是存储和检索层。"}
{"question": "分层记忆设计(L0 抽象层、L1 概述层、L2 内容层)的设计初衷是什么?三层之间如何保持语义一致性?", "files": ["OpenViking/docs/en/concepts/03-context-layers.md"], "answer": "分层记忆设计的初衷是平衡检索效率与内容完整性。\n\n**三层结构说明**:\n- **L0(Abstract)**:最简洁的内容表示,约100 tokens,用于向量检索和快速过滤,存储在 `.abstract.md` 文件中。\n- **L1(Overview)**:约2k tokens的综合摘要,包含导航指引,用于重排序和理解访问方式,存储在 `.overview.md` 文件中。\n- **L2(Detail)**:完整原始内容,无 token 限制,仅在确认需要时加载。\n\n**语义一致性保证**:\n1. **生成机制**:SemanticProcessor 采用自底向上的方式遍历目录,为每个节点生成 L0/L1,确保层级间的语义关联。\n2. **统一来源**:所有层级都源自同一份原始内容,L0 是 L1 的精炼,L1 是 L2 的结构化摘要。\n3. **渐进式加载**:检索时先通过 L0 定位,再通过 L1 确认相关性,最后按需加载 L2,保证语义传递。\n\n**API 支持**:\n```python\nabstract = client.abstract(\"viking://resources/docs/auth\") # L0\noverview = client.overview(\"viking://resources/docs/auth\") # L1\ncontent = client.read(\"viking://resources/docs/auth/oauth.md\") # L2\n```"}
-{"question": "六种记忆类别(profile、preferences、entities、events、trajectories、experiences)的划分依据是什么?在实际应用中如何自动分类?", "files": ["OpenViking/docs/en/concepts/02-context-types.md", "OpenViking/openviking/session/compressor_v2.py"], "answer": "六种记忆类别基于人类认知模式的简化和工程考量进行划分。\n\n**划分依据**:\n\n**用户记忆**:\n- **profile**:用户基本信息,存储在 `user/memories/.overview.md`\n- **preferences**:用户偏好,按主题聚合,存储在 `user/memories/preferences/`\n- **entities**:实体记忆(人、项目、概念),存储在 `user/memories/entities/`\n- **events**:事件记录(决策、里程碑),存储在 `user/memories/events/`\n\n**执行记忆**:\n- **trajectories**:学习到的案例,存储在 `user/memories/trajectories/`\n- **experiences**:学习到的模式,存储在 `user/memories/experiences/`\n\n**自动分类机制**:\nSessionCompressorV2 通过 v2 memory schema 和 ExtractLoop 自动提取和更新记忆。流程如下:\n1. 格式化会话消息\n2. 调用 v2 memory schema templates 和 ExtractLoop\n3. LLM 返回结构化的 memory operations\n4. 根据 category 写入对应目录\n\n**更新策略**:\n- profile、preferences、entities:可追加更新\n- events、trajectories、experiences:不更新,作为历史记录"}
+{"question": "OpenViking 的内置记忆类型如何划分?在实际应用中如何自动提取?", "files": ["OpenViking/docs/en/concepts/02-context-types.md", "OpenViking/openviking/session/compressor_v2.py"], "answer": "OpenViking 的记忆类型由 MemoryType Schema 定义,并可通过自定义模板扩展或覆盖。当前内置类型按用途可理解为三组:\n\n**用户与环境理解**:\n- **profile**:用户基本信息,存储在 `user/memories/profile.md`\n- **preferences**:用户偏好,存储在 `user/memories/preferences/`\n- **entities**:人物、项目、组织等实体知识,存储在 `user/memories/entities/`\n- **events**:决策、里程碑等事件记录,存储在 `user/memories/events/`\n\n**助手身份与连续性**:\n- **identity**:助手身份与自我介绍,存储在 `user/memories/identity.md`\n- **soul**:助手原则、边界、风格和连续性,存储在 `user/memories/soul.md`\n\n**任务执行与学习**:\n- **cases**:可训练、可评估的任务案例\n- **trajectories**:可复用的任务执行轨迹\n- **experiences**:从执行结果提炼的可复用经验\n- **tools**:工具使用经验与最佳实践\n- **skills**:技能执行经验与工作流策略\n\n这些类型默认存储在 `user/memories/` 的对应文件或子目录中;短路径会按当前身份解析到 `viking://user/{user_id}/...`,支持的类型也可按记忆策略写入相关 Peer 空间。\n\n**自动提取机制**:\n1. 提交 Session 后格式化会话消息\n2. 根据当前记忆策略选择已启用的 MemoryType Schema\n3. 调用 LLM 生成结构化 memory operations\n4. 按各 Schema 的目录、文件名和合并规则写入并建立索引"}
{"question": "OpenViking 如何支持多 Agent 协作场景?不同 Agent 之间的记忆如何隔离与共享?", "files": ["OpenViking/docs/en/concepts/02-context-types.md", "OpenViking/docs/en/concepts/01-architecture.md"], "answer": "OpenViking 通过 URI 命名空间和作用域设计支持多 Agent 协作。\n\n**记忆隔离机制**:\n1. **URI 命名空间**:\n - `viking://user/memories/` - 用户级记忆\n - `viking://user/{user_id}/peers/{peer_id}/memories/` - Peer 级记忆\n - `viking://resources/` - 共享资源\n - `viking://user/skills/` - User 技能\n\n2. **作用域划分**:\n - **User Scope**:用户相关的 profile、preferences、entities、events\n - **Peer/Execution Scope**:Agent 学习到的 trajectories、experiences\n - **Resources Scope**:共享的知识库\n\n**记忆共享机制**:\n1. **资源层共享**:所有 Agent 可以访问 `viking://resources/` 下的共享知识库。\n2. **用户记忆共享**:同一用户的不同 Agent 可以共享 `viking://user/memories/` 下的用户偏好和实体记忆。\n3. **关系管理**:通过 `.relations.json` 建立资源间的关联关系,支持跨 Agent 的上下文关联。\n\n**实际应用**:\n```python\n# Agent A 添加资源\nclient.add_resource(\"./docs/api.pdf\", to=\"viking://resources/api\")\n\n# Agent B 可以检索到\nresults = client.find(\"API usage\", target_uri=\"viking://resources/\")\n```"}
{"question": "会话的生命周期是如何管理的?commit_session 后记忆如何被持久化和索引?", "files": ["OpenViking/docs/en/concepts/08-session.md"], "answer": "会话生命周期遵循:创建 → 交互 → 提交 的模式。\n\n**生命周期管理**:\n1. **创建**:`session = client.session(session_id=\"chat_001\")`\n2. **交互**:\n - `session.add_message(role, parts)` - 添加消息\n - `session.used(contexts, skill)` - 记录使用的上下文/技能\n3. **提交**:`session.commit()` - 归档并提取记忆\n\n**commit 后的持久化流程**:\n1. **归档流程**:\n - 增加 compression_index\n - 复制当前消息到归档目录\n - 生成结构化摘要(LLM)\n - 清空当前消息列表\n\n2. **记忆提取**:\n - SessionCompressorV2 从消息中提取和更新记忆\n - 生成 L0(abstract)和 L1(overview)\n - 写入对应的 VikingFS 目录\n\n3. **索引构建**:\n - 对新生成的记忆内容进行向量化\n - 写入 Vector Index 支持语义检索\n\n**消息结构**:\n- Message:id、role、parts、created_at\n- Part 类型:TextPart、ContextPart、ToolPart\n\n**返回结果**:\n```python\n{\n \"status\": \"committed\",\n \"memories_extracted\": 5,\n \"active_count_updated\": 2,\n \"archived\": True\n}\n```"}
{"question": "技能系统的设计理念是什么?与传统的 Function Calling 或 Tool Use 有何不同?", "files": ["OpenViking/docs/en/api/04-skills.md", "OpenViking/docs/en/concepts/02-context-types.md"], "answer": "技能系统的设计理念是将 Agent 可调用的能力统一管理,与 Function Calling 的区别在于存储和检索方式。\n\n**设计理念**:\n1. **统一存储**:技能作为上下文的一种类型,与记忆、资源采用相同的存储范式。\n2. **分层描述**:技能同样有 L0(简短描述)、L1(详细概述)、L2(完整定义)三层结构。\n3. **语义检索**:支持通过自然语言描述检索相关技能。\n\n**与传统 Function Calling 的区别**:\n| 维度 | OpenViking Skills | Function Calling |\n|------|-------------------|-----------------|\n| 存储方式 | 文件系统 + 向量索引 | 代码定义 |\n| 检索方式 | 语义检索 + 目录定位 | 精确匹配 |\n| 描述层次 | L0/L1/L2 三层 | 单层描述 |\n| 上下文关联 | 支持关系管理 | 无 |\n\n**存储位置**:\n```\nviking://user/skills/{skill-name}/\n├── .abstract.md # L0: 简短描述\n├── SKILL.md # L1: 详细概述\n└── scripts # L2: 完整定义\n```\n\n**支持的数据格式**:\n1. Dict(Skill 格式)\n2. Dict(MCP Tool 格式)- 自动检测并转换\n3. String(SKILL.md 内容)\n4. Path(文件或目录)"}
@@ -14,7 +14,7 @@
{"question": "配置文件 `ov.conf` 的必填项有哪些?如何配置不同的 VLM 后端(OpenAI、Volcengine 等)?", "files": ["OpenViking/docs/en/guides/01-configuration.md:1-150"], "answer": "配置文件 `ov.conf` 包含 embedding、vlm、rerank、storage 等配置项。\n\n**必填配置项**:\n\n```json\n{\n \"embedding\": {\n \"dense\": {\n \"provider\": \"volcengine\", // 必填:volcengine/openai/vikingdb\n \"api_key\": \"your-api-key\", // 必填\n \"model\": \"doubao-embedding-vision-251215\",\n \"dimension\": 1024\n }\n },\n \"vlm\": {\n \"provider\": \"volcengine\", // 必填\n \"api_key\": \"your-api-key\", // 必填\n \"model\": \"doubao-seed-2-0-pro-260215\"\n }\n}\n```\n\n**VLM 后端配置**:\n\n1. **Volcengine(豆包模型)**:\n```json\n{\n \"vlm\": {\n \"api_base\": \"https://ark.cn-beijing.volces.com/api/v3\",\n \"api_key\": \"your-volcengine-api-key\",\n \"provider\": \"volcengine\",\n \"model\": \"doubao-seed-2-0-pro-260215\"\n }\n}\n```\n\n2. **OpenAI**:\n```json\n{\n \"vlm\": {\n \"api_base\": \"https://api.openai.com/v1\",\n \"api_key\": \"your-openai-api-key\",\n \"provider\": \"openai\",\n \"model\": \"gpt-4-vision-preview\"\n }\n}\n```\n\n**Embedding 配置**:\n\n| 参数 | 说明 |\n|------|------|\n| `provider` | volcengine/openai/vikingdb |\n| `api_key` | API 密钥 |\n| `model` | 模型名称 |\n| `dimension` | 向量维度 |\n| `input` | 输入类型:text/multimodal |\n\n**可选配置**:\n- `rerank`:重排序模型配置\n- `storage`:存储后端配置"}
{"question": "`HierarchicalRetriever` 的检索流程是怎样的?如何实现从 L0 到 L2 的层级穿透检索?", "files": ["OpenViking/openviking/retrieve/hierarchical_retriever.py"], "answer": "HierarchicalRetriever 实现目录递归检索和层级穿透。\n\n**检索流程**:\n\n1. **初始化**:\n```python\nclass HierarchicalRetriever:\n MAX_CONVERGENCE_ROUNDS = 3 # 收敛轮次\n MAX_RELATIONS = 5 # 最大关联数\n SCORE_PROPAGATION_ALPHA = 0.5 # 分数传播系数\n DIRECTORY_DOMINANCE_RATIO = 1.2 # 目录分数阈值\n GLOBAL_SEARCH_TOPK = 3 # 全局检索数量\n```\n\n2. **检索模式**:\n - **THINKING**:深度思考模式\n - **QUICK**:快速检索模式\n\n3. **核心方法**:\n```python\nasync def retrieve(\n self,\n query: TypedQuery,\n limit: int = 5,\n mode: RetrieverMode = RetrieverMode.THINKING,\n score_threshold: Optional[float] = None,\n metadata_filter: Optional[Dict[str, Any]] = None,\n) -> QueryResult:\n```\n\n**层级穿透机制**:\n\n1. **L0 检索**:\n - 向量相似度搜索 `.abstract.md` 内容\n - 快速过滤不相关内容\n\n2. **L1 确认**:\n - 读取 `.overview.md` 进行重排序\n - 确认内容相关性\n\n3. **L2 加载**:\n - 按需读取完整内容\n - 仅在确认需要时加载\n\n**关键特性**:\n- 分数传播:目录分数向子节点传播\n- 目录优势:目录分数需超过最大子节点分数\n- 关联检索:自动检索关联上下文"}
{"question": "语义处理队列的工作机制是什么?如何监控和调试异步处理状态?", "files": ["OpenViking/docs/en/concepts/01-architecture.md", "OpenViking/openviking/service/resource_service.py:1-80"], "answer": "语义处理队列通过 SemanticQueue 异步生成 L0/L1 内容。\n\n**工作机制**:\n\n1. **处理流水线**:\n```\nInput → Parser → TreeBuilder → AGFS → SemanticQueue → Vector Index\n```\n\n2. **队列处理**:\n - TreeBuilder 将文件移动到 AGFS 后入队\n - SemanticQueue 异步处理队列项\n - 自底向上生成 L0/L1\n\n3. **异步处理优势**:\n - 不阻塞资源添加操作\n - 支持大规模文档处理\n - LLM 调用并行化\n\n**监控和调试**:\n\n1. **等待处理完成**:\n```python\nresult = client.add_resource(\"./docs\", wait=False)\nclient.wait_processed() # 等待队列处理完成\n```\n\n2. **超时控制**:\n```python\nresult = client.add_resource(\n \"./docs\",\n wait=True,\n timeout=300 # 超时时间(秒)\n)\n```\n\n3. **DebugService**:\n - 提供 ObserverService 用于调试\n - 可视化检索轨迹\n\n4. **日志监控**:\n - 通过 logger 获取处理状态\n - 监控队列长度和处理延迟\n\n**Service 层支持**:\n- ResourceService 管理 add_resource 操作\n- wait_processed() 方法等待语义处理完成"}
-{"question": "如何通过代码动态创建和管理 Session?Session 与 Memory 的关系是什么?", "files": ["OpenViking/docs/en/concepts/08-session.md", "OpenViking/openviking/session/compressor_v2.py"], "answer": "Session 通过 client API 动态创建,commit 后自动提取 Memory。\n\n**Session 创建和管理**:\n\n1. **创建 Session**:\n```python\n# 创建新会话\nsession = client.session(session_id=\"chat_001\")\n\n# 或使用 create_session\nresult = client.create_session()\n```\n\n2. **添加消息**:\n```python\nsession.add_message(\n \"user\",\n [TextPart(\"How to configure embedding?\")]\n)\n\nsession.add_message(\n \"assistant\",\n [\n TextPart(\"Here's how...\"),\n ContextPart(uri=\"viking://user/memories/profile.md\"),\n ]\n)\n```\n\n3. **记录使用**:\n```python\nsession.used(contexts=[\"viking://user/memories/profile.md\"])\nsession.used(skill={\n \"uri\": \"viking://user/skills/code-search\",\n \"input\": \"search config\",\n \"output\": \"found 3 files\",\n \"success\": True\n})\n```\n\n4. **提交会话**:\n```python\nresult = session.commit()\n# {\"status\": \"committed\", \"memories_extracted\": 5}\n```\n\n**Session 与 Memory 的关系**:\n\n1. **Memory 来源**:\n - Memory 从 Session 消息中提取\n - SessionCompressorV2 在 commit 时触发\n\n2. **提取流程**:\n - 格式化会话消息\n - 调用 LLM 提取 6 类记忆\n - 写入对应目录并索引\n\n3. **记忆类别映射**:\n - profile → `user/memories/profile.md`\n - preferences → `user/memories/preferences/`\n - entities → `user/memories/entities/`\n - events → `user/memories/events/`\n - trajectories → `user/memories/trajectories/`\n - experiences → `user/memories/experiences/`"}
+{"question": "如何通过代码动态创建和管理 Session?Session 与 Memory 的关系是什么?", "files": ["OpenViking/docs/en/concepts/08-session.md", "OpenViking/openviking/session/compressor_v2.py"], "answer": "Session 通过 client API 动态创建,commit 后自动提取 Memory。\n\n**Session 创建和管理**:\n\n1. **创建 Session**:\n```python\n# 创建新会话\nsession = client.session(session_id=\"chat_001\")\n\n# 或使用 create_session\nresult = client.create_session()\n```\n\n2. **添加消息**:\n```python\nsession.add_message(\n \"user\",\n [TextPart(\"How to configure embedding?\")]\n)\n\nsession.add_message(\n \"assistant\",\n [\n TextPart(\"Here's how...\"),\n ContextPart(uri=\"viking://user/memories/profile.md\"),\n ]\n)\n```\n\n3. **记录使用**:\n```python\nsession.used(contexts=[\"viking://user/memories/profile.md\"])\nsession.used(skill={\n \"uri\": \"viking://user/skills/code-search\",\n \"input\": \"search config\",\n \"output\": \"found 3 files\",\n \"success\": True\n})\n```\n\n4. **提交会话**:\n```python\nresult = session.commit()\n# {\"status\": \"committed\", \"memories_extracted\": 5}\n```\n\n**Session 与 Memory 的关系**:\n\n1. **Memory 来源**:\n - Memory 从 Session 消息中提取\n - SessionCompressorV2 在 commit 时触发\n\n2. **提取流程**:\n - 格式化会话消息\n - 根据当前记忆策略调用 LLM 提取已启用的记忆类型\n - 写入当前用户或相关 Peer 的记忆目录并索引\n\n3. **内置记忆类型与默认位置**:\n - profile → `user/memories/profile.md`\n - preferences → `user/memories/preferences/`\n - entities → `user/memories/entities/`\n - events → `user/memories/events/`\n - identity → `user/memories/identity.md`\n - soul → `user/memories/soul.md`\n - cases → `user/memories/cases/`\n - trajectories → `user/memories/trajectories/`\n - experiences → `user/memories/experiences/`\n - tools → `user/memories/tools/`\n - skills → `user/memories/skills/`\n\n这些 `user/...` 短路径会按当前身份解析为 `viking://user/{user_id}/...`,应用也可以通过自定义模板扩展或调整记忆类型。"}
{"question": "OpenViking Server 模式与本地模式的区别是什么?如何选择部署方式?", "files": ["OpenViking/openviking/server/bootstrap.py:1-61", "OpenViking/docs/en/concepts/01-architecture.md"], "answer": "Server 模式提供 HTTP API,本地模式直接嵌入应用。\n\n**模式对比**:\n\n| 维度 | 本地模式 | Server 模式 |\n|------|----------|-------------|\n| 访问方式 | Python SDK | HTTP API |\n| 部署复杂度 | 简单 | 需启动服务 |\n| 多客户端 | 不支持 | 支持 |\n| 资源共享 | 单进程 | 多进程共享 |\n| 适用场景 | 单机应用 | 生产环境 |\n\n**Server 模式启动**:\n\n1. **命令行启动**:\n```bash\nopenviking-server --host 0.0.0.0 --port 1933 --config ./ov.conf\n```\n\n2. **参数说明**:\n- `--host`:绑定地址\n- `--port`:端口号\n- `--config`:配置文件路径\n\n3. **HTTP API 示例**:\n```bash\ncurl -X POST http://localhost:1933/api/v1/resources \\\n -H \"Content-Type: application/json\" \\\n -H \"X-API-Key: your-key\" \\\n -d '{\"path\": \"./documents/guide.md\"}'\n```\n\n**部署方式选择**:\n\n1. **选择本地模式**:\n - 单机应用开发\n - 快速原型验证\n - 无需多客户端访问\n\n2. **选择 Server 模式**:\n - 生产环境部署\n - 多客户端/多服务访问\n - 需要集中式上下文管理\n - 微服务架构集成\n\n**Service 层复用**:\n两种模式共享 Service 层逻辑,支持 HTTP Server 和 CLI 复用。"}
{"question": "如何扩展自定义的 Parser?例如支持新的文档格式或代码语言?", "files": ["OpenViking/openviking/parse/registry.py", "OpenViking/openviking/parse/parsers/base_parser.py:1-80"], "answer": "通过 ParserRegistry 注册自定义 Parser,支持 Protocol 接口。\n\n**自定义 Parser 步骤**:\n\n1. **实现 BaseParser 接口**:\n```python\nclass BaseParser(ABC):\n @abstractmethod\n async def parse(self, source: Union[str, Path], instruction: str = \"\", **kwargs) -> ParseResult:\n \"\"\"解析文档\"\"\"\n pass\n \n @abstractmethod\n async def parse_content(self, content: str, source_path: Optional[str] = None, **kwargs) -> ParseResult:\n \"\"\"解析内容\"\"\"\n pass\n \n @property\n @abstractmethod\n def supported_extensions(self) -> List[str]:\n \"\"\"支持的文件扩展名\"\"\"\n pass\n```\n\n2. **注册 Parser**:\n```python\nfrom openviking.parse.registry import get_registry\n\nclass MyParser(BaseParser):\n @property\n def supported_extensions(self) -> List[str]:\n return [\".myext\"]\n \n async def parse(self, source, instruction=\"\", **kwargs):\n # 实现解析逻辑\n return ParseResult(...)\n\n# 注册\nregistry = get_registry()\nregistry.register(\"my_parser\", MyParser())\n```\n\n3. **使用 Protocol 接口**:\n```python\nregistry.register_custom(\n handler=my_parser, # 实现 CustomParserProtocol\n extensions=[\".custom\"],\n name=\"custom_parser\"\n)\n```\n\n**内置 Parser**:\n- TextParser:纯文本\n- MarkdownParser:Markdown\n- PDFParser:PDF\n- HTMLParser:HTML\n- CodeRepositoryParser:代码仓库\n- ImageParser:图片(可选)\n\n**扩展点**:\n- `supported_extensions`:定义支持的扩展名\n- `can_parse()`:检查文件是否可解析\n- `_read_file()`:读取文件内容"}
{"question": "eval 模块的 RAGAS 集成是如何实现的?如何自定义评测指标?", "files": ["OpenViking/openviking/eval/ragas.py", "OpenViking/openviking/eval/base.py:1-60"], "answer": "eval 模块通过 RagasEvaluator 适配器集成 RAGAS,支持自定义评测指标。\n\n**RAGAS 集成实现**:\n\n1. **RagasEvaluator 类**:\n```python\nclass RagasEvaluator(BaseEvaluator):\n def __init__(self, metrics=None, llm=None, embeddings=None):\n from ragas.metrics import (\n answer_relevance,\n context_precision,\n context_recall,\n faithfulness,\n )\n self.metrics = metrics or [\n faithfulness,\n answer_relevance,\n context_precision,\n context_recall,\n ]\n```\n\n2. **评测流程**:\n```python\nasync def evaluate_dataset(self, dataset: EvalDataset) -> SummaryResult:\n # 转换为 RAGAS 数据集格式\n data = {\n \"question\": [s.query for s in dataset.samples],\n \"contexts\": [s.context for s in dataset.samples],\n \"answer\": [s.response for s in dataset.samples],\n \"ground_truth\": [s.ground_truth for s in dataset.samples],\n }\n \n # 调用 RAGAS evaluate\n result = evaluate(data, metrics=self.metrics)\n```\n\n**自定义评测指标**:\n\n1. **继承 BaseEvaluator**:\n```python\nclass MyEvaluator(BaseEvaluator):\n async def evaluate_sample(self, sample: EvalSample) -> EvalResult:\n # 实现自定义评测逻辑\n scores = {\"my_metric\": 0.85}\n return EvalResult(sample=sample, scores=scores)\n```\n\n2. **自定义 RAGAS 指标**:\n```python\nfrom ragas import evaluate\nfrom ragas.metrics import Metric\n\nclass MyMetric(Metric):\n name = \"my_metric\"\n # 实现指标计算\n\nevaluator = RagasEvaluator(metrics=[MyMetric()])\n```\n\n3. **评测结果结构**:\n```python\nclass SummaryResult(BaseModel):\n dataset_name: str\n sample_count: int\n mean_scores: Dict[str, float] # 平均分数\n results: List[EvalResult] # 每个样本结果\n```"}