retrieval.md

Retrieval

The retrieval module provides four ways to query the OpenViking filesystem: vector similarity search, context-aware semantic search, regex grep, and glob matching.

Methods

find(query, options?)

Basic vector similarity search. Returns the most semantically similar contexts for a query.

const results = await huscarl.retrieval.find("authentication configuration", {
  targetUri: "viking://resources/docs/",  // scope to a specific path
  limit: 10,
  scoreThreshold: 0.7,
});

for (const match of results.resources) {
  console.log(match.uri, match.score.toFixed(3), match.abstract);
}

Option	Type	Description
targetUri	string	Scope the search to a specific URI prefix.
limit	number	Maximum results to return. Default: 10.
scoreThreshold	number	Minimum relevance score (0–1).

search(query, options?)

Context-aware semantic search with intent analysis and query expansion. Use this in conversational flows where prior messages should influence retrieval.

const results = await huscarl.retrieval.search("what about the retry logic?", {
  sessionId: "session-123",  // server uses conversation history to expand the query
  targetUri: "viking://resources/",
  limit: 5,
});

if (results.queryPlan) {
  console.log("Expanded queries:", results.queryPlan.expandedQueries);
}

Accepts all the same options as find(), plus sessionId.

grep(uri, pattern, options?)

Regex pattern search across file contents within a Viking URI scope. Filesystem-only — does not require embeddings, works even when the vector index is unhealthy.

const matches = await huscarl.retrieval.grep(
  "viking://resources/",
  "TODO|FIXME",
  { caseInsensitive: true },
);

glob(pattern, options?)

Matches files by glob pattern within the Viking filesystem.

const files = await huscarl.retrieval.glob("**/*.md", {
  uri: "viking://resources/docs/",
});

Result shape

find() and search() both return a FindResult:

interface FindResult {
  resources: MatchedContext[];
  memories:  MatchedContext[];
  skills:    MatchedContext[];
  total:     number;
  queryPlan?: QueryPlan;       // only present on search()
}

interface MatchedContext {
  uri:          string;
  context_type: string;        // "resource", "memory", or "skill" (from the API)
  isLeaf:       boolean;
  abstract:     string;
  score:        number;
  matchReason:  string;
  category?:    string;
  relations?:   RelatedContext[];
}

Note: context_type uses snake_case because it comes directly from the OpenViking API response.