Skip to content

resources.md

Latest commit

 

History

History
155 lines (102 loc) · 4.6 KB

resources.md

File metadata and controls

155 lines (102 loc) · 4.6 KB

Resources

The resources module manages files, directories, and semantic relations within viking://resources/.

All path parameters are relative to the resources root — e.g. "docs/guide.md" maps to viking://resources/docs/guide.md.

Methods

add(path, options?)

Ingest a file, directory, or URL into OpenViking.

await huscarl.resources.add("./data/report.pdf", {
  target: "reports/",          // destination path within resources
  reason: "Q4 financial report", // improves search relevance
  wait: true,                  // block until L0/L1 generation completes
  watchInterval: 60,           // re-ingest every 60 minutes (requires target)
});
Option Type Description
target string Destination path within viking://resources/. If omitted, the server chooses.
reason string Why this resource is being added — improves search relevance and memory extraction.
wait boolean Block until semantic processing (L0/L1 generation) completes. Default: false.
watchInterval number Re-ingest interval in minutes. > 0 enables, <= 0 disables. Requires target.

stat(path)

Returns metadata for a resource or directory: size, type, and timestamps.

Returns: ResourceStat with size, type, created, modified, accessed.

const info = await huscarl.resources.stat("docs/guide.md");
console.log(info.size, info.type);

read(path)

Returns the full content (L2) of a file. For directories, returns the concatenated content of all children.

Returns: string containing the full file content or concatenated children.

const content = await huscarl.resources.read("docs/guide.md");

abstract(path)

Returns the L0 abstract — a short, AI-generated summary. Fast to retrieve and useful for ranking, previews, or building compact search result snippets.

Returns: string containing the L0 abstract (typically 1–2 sentences).

const summary = await huscarl.resources.abstract("docs/guide.md");

overview(path)

Returns the L1 overview — a medium-length AI-generated summary with key details, structure, and main takeaways.

Returns: string containing the L1 overview (typically a few paragraphs).

const overview = await huscarl.resources.overview("docs/");

list(path?, options?)

Lists the immediate children of a directory. Pass recursive: true to list all descendants.

Returns: ListEntry[] with name, type, and metadata for each child.

const entries = await huscarl.resources.list("docs/");
const allEntries = await huscarl.resources.list("docs/", { recursive: true });

for (const entry of entries) {
  console.log(entry.name, entry.isDirectory ? "dir" : "file");
}

tree(path?)

Returns the full recursive directory tree as a nested structure, including L0 abstracts for directories.

Returns: Nested tree object with name, isDirectory, abstract, and children.

const tree = await huscarl.resources.tree("docs/");

move(fromPath, toPath)

Moves or renames a resource or directory.

await huscarl.resources.move("old-project/", "archive/old-project/");

remove(path, options?)

Deletes a resource or directory. Pass recursive: true when deleting a non-empty directory.

await huscarl.resources.remove("docs/guide.md");
await huscarl.resources.remove("old-project/", { recursive: true });

createDirectory(path)

Creates an empty directory.

await huscarl.resources.createDirectory("new-project/");

link(fromPath, toUris, options?)

Creates a semantic relation between two resources. Linked resources surface together in search results and inform memory extraction.

The toUris parameter can be a single path (string) or an array of paths.

// Single link
await huscarl.resources.link("docs/guide.md", "docs/api-reference.md", {
  reason: "The guide references the API docs",
});

// Link to multiple targets at once
await huscarl.resources.link("docs/guide.md", ["docs/faq.md", "docs/examples.md"]);

unlink(fromPath, toPath)

Removes a semantic relation between two resources.

await huscarl.resources.unlink("docs/guide.md", "docs/api-reference.md");

relations(path)

Returns all resources linked to the given resource.

Returns: RelatedResource[] with URI, abstract, and relation reason.

const related = await huscarl.resources.relations("docs/guide.md");
for (const rel of related) {
  console.log(rel.uri, rel.reason);
}