Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
import {
getOvResult,
normalizeOvClientError,
postSearchFind,
postSearchGlob,
postSearchGrep,
postSearchSearch,
} from '#/lib/ov-client'
import type { FindContextType, SearchResult } from '@ov-server/api/v1/search'
export type { FindContextType } from '@ov-server/api/v1/search'
export interface FindResultItem {
uri: string
context_type: FindContextType
level: number
score: number
abstract: string
overview?: string | null
category: string
match_reason: string
result_kind?: 'semantic' | 'grep' | 'glob'
line?: number
}
export interface FindQueryPlanItem {
query: string
context_type?: FindContextType | null
intent?: string | null
priority?: number | null
}
export interface FindQueryPlan {
reasoning?: string | null
queries: FindQueryPlanItem[]
}
export interface GroupedFindResult {
memories: FindResultItem[]
resources: FindResultItem[]
skills: FindResultItem[]
total: number
query_plan?: FindQueryPlan | null
provenance?: Array<Record<string, unknown>> | null
}
export interface VikingApiError {
code: string
message: string
requestId?: string
statusCode?: number
details?: unknown
}
export interface FetchFindOptions {
contextTypes?: FindContextType[]
includeProvenance?: boolean
levels?: number[]
targetUri?: string
limit?: number
scoreThreshold?: number
filter?: Record<string, unknown>
since?: string
tags?: string[]
timeField?: 'created_at' | 'updated_at'
until?: string
}
export interface FetchSearchOptions extends FetchFindOptions {
sessionId?: string
}
export interface FetchGrepOptions {
caseInsensitive?: boolean
limit?: number
uri: string
}
export interface FetchGlobOptions {
limit?: number
uri?: string
}
const FIND_CONTEXT_TYPES = ['resource', 'memory', 'skill'] as const
function toVikingApiError(error: unknown): VikingApiError {
const normalized = normalizeOvClientError(error)
return {
code: normalized.code,
details: normalized.details,
message: normalized.message,
requestId: normalized.requestId,
statusCode: normalized.statusCode,
}
}
function isFindContextType(value: unknown): value is FindContextType {
return FIND_CONTEXT_TYPES.some((type) => type === value)
}
function normalizeFindItems(
value: unknown,
fallbackType: FindContextType,
): FindResultItem[] {
if (!Array.isArray(value)) return []
return value
.filter(
(item): item is Record<string, unknown> =>
item !== null && typeof item === 'object' && !Array.isArray(item),
)
.map((item) => ({
abstract: typeof item.abstract === 'string' ? item.abstract : '',
category: typeof item.category === 'string' ? item.category : '',
context_type: isFindContextType(item.context_type)
? item.context_type
: fallbackType,
level: typeof item.level === 'number' ? item.level : 2,
match_reason:
typeof item.match_reason === 'string' ? item.match_reason : '',
overview: typeof item.overview === 'string' ? item.overview : null,
score: typeof item.score === 'number' ? item.score : 0,
uri: typeof item.uri === 'string' ? item.uri : '',
}))
}
function normalizeQueryPlan(value: unknown): FindQueryPlan | null {
if (value === null || value === undefined) return null
if (typeof value !== 'object' || Array.isArray(value)) return null
const data = value as Record<string, unknown>
const queries = Array.isArray(data.queries)
? data.queries
.filter(
(query): query is Record<string, unknown> =>
query !== null &&
typeof query === 'object' &&
!Array.isArray(query),
)
.map<FindQueryPlanItem>((query) => ({
context_type: isFindContextType(query.context_type)
? query.context_type
: null,
intent: typeof query.intent === 'string' ? query.intent : null,
priority: typeof query.priority === 'number' ? query.priority : null,
query: typeof query.query === 'string' ? query.query : '',
}))
.filter((query) => query.query.trim().length > 0)
: []
return {
queries,
reasoning: typeof data.reasoning === 'string' ? data.reasoning : null,
}
}
function normalizeGroupedFindResult(
result: SearchResult | unknown,
): GroupedFindResult {
const data =
result !== null && typeof result === 'object' && !Array.isArray(result)
? (result as Record<string, unknown>)
: {}
const memories = normalizeFindItems(data.memories, 'memory')
const resources = normalizeFindItems(data.resources, 'resource')
const skills = normalizeFindItems(data.skills, 'skill')
const total =
typeof data.total === 'number'
? data.total
: memories.length + resources.length + skills.length
return {
memories,
provenance: Array.isArray(data.provenance)
? data.provenance.filter(
(item): item is Record<string, unknown> =>
item !== null && typeof item === 'object' && !Array.isArray(item),
)
: null,
query_plan: normalizeQueryPlan(data.query_plan),
resources,
skills,
total,
}
}
export async function fetchFind(
query: string,
options: FetchFindOptions = {},
): Promise<GroupedFindResult> {
try {
const result = await getOvResult<SearchResult>(
postSearchFind({
body: {
filter: options.filter,
context_type:
options.contextTypes && options.contextTypes.length > 0
? options.contextTypes
: undefined,
include_provenance: options.includeProvenance,
level:
options.levels && options.levels.length > 0
? options.levels
: undefined,
limit: options.limit ?? 10,
query,
score_threshold: options.scoreThreshold,
since: options.since,
tags:
options.tags && options.tags.length > 0 ? options.tags : undefined,
target_uri: options.targetUri,
time_field: options.timeField,
until: options.until,
},
}),
)
return normalizeGroupedFindResult(result)
} catch (error) {
throw toVikingApiError(error)
}
}
export async function fetchSearch(
query: string,
options: FetchSearchOptions = {},
): Promise<GroupedFindResult> {
try {
const result = await getOvResult<SearchResult>(
postSearchSearch({
body: {
filter: options.filter,
context_type:
options.contextTypes && options.contextTypes.length > 0
? options.contextTypes
: undefined,
include_provenance: options.includeProvenance,
level:
options.levels && options.levels.length > 0
? options.levels
: undefined,
limit: options.limit ?? 10,
query,
score_threshold: options.scoreThreshold,
since: options.since,
session_id: options.sessionId,
tags:
options.tags && options.tags.length > 0 ? options.tags : undefined,
target_uri: options.targetUri,
time_field: options.timeField,
until: options.until,
},
}),
)
return normalizeGroupedFindResult(result)
} catch (error) {
throw toVikingApiError(error)
}
}
/**
* Fetch all context types in one request.
*
* The server already groups resources, memories, and skills in its response,
* so issuing one request per type only duplicates work and can exceed the
* requested global limit.
*/
export function fetchFindAllTypes(
query: string,
options: Omit<FetchFindOptions, 'targetUri' | 'filter'> = {},
): Promise<GroupedFindResult> {
return fetchFind(query, options)
}
function emptyPatternResult(resources: FindResultItem[]): GroupedFindResult {
return {
memories: [],
resources,
skills: [],
total: resources.length,
}
}
function patternResultItem(
uri: string,
kind: 'grep' | 'glob',
options: { content?: string; line?: number } = {},
): FindResultItem {
return {
abstract: options.content ?? '',
category: '',
context_type: 'resource',
level: 2,
line: options.line,
match_reason: '',
result_kind: kind,
score: 0,
uri,
}
}
export async function fetchGrep(
pattern: string,
options: FetchGrepOptions,
): Promise<GroupedFindResult> {
try {
const result = await getOvResult<unknown>(
postSearchGrep({
body: {
case_insensitive: options.caseInsensitive,
node_limit: options.limit ?? 10,
pattern,
uri: options.uri,
},
}),
)
const matches =
result && typeof result === 'object' && 'matches' in result
? (result as { matches?: unknown }).matches
: undefined
const resources = Array.isArray(matches)
? matches
.filter(
(match): match is Record<string, unknown> =>
match !== null &&
typeof match === 'object' &&
!Array.isArray(match) &&
typeof match.uri === 'string',
)
.map((match) =>
patternResultItem(match.uri as string, 'grep', {
content:
typeof match.content === 'string' ? match.content : undefined,
line: typeof match.line === 'number' ? match.line : undefined,
}),
)
: []
return emptyPatternResult(resources)
} catch (error) {
throw toVikingApiError(error)
}
}
export async function fetchGlob(
pattern: string,
options: FetchGlobOptions = {},
): Promise<GroupedFindResult> {
try {
const result = await getOvResult<unknown>(
postSearchGlob({
body: {
node_limit: options.limit ?? 10,
pattern,
uri: options.uri ?? 'viking://',
},
}),
)
const matches =
result && typeof result === 'object' && 'matches' in result
? (result as { matches?: unknown }).matches
: undefined
const resources = Array.isArray(matches)
? matches
.filter((uri): uri is string => typeof uri === 'string')
.map((uri) => patternResultItem(uri, 'glob'))
: []
return emptyPatternResult(resources)
} catch (error) {
throw toVikingApiError(error)
}
}