The Node.js/TypeScript client for OpenViking. Bring full context database access to your Node.js backend.

Huscarl is a typed Node.js/TypeScript client for OpenViking, an open-source context database for AI agents. OpenViking stores resources, memories, and skills in a virtual filesystem addressed by viking:// URIs, with semantic retrieval and automatic AI-generated summaries at three levels of detail (L0/L1/L2).

OpenViking is Python-first. It ships a Python SDK, a CLI, and an MCP server. Huscarl fills the Node.js gap, giving TypeScript developers full REST API access through an idiomatic, ergonomic interface. Types are bundled; no @types/ package needed.

Huscarl is the right choice when you need programmatic control over OpenViking from a Node.js application:

• Ingestion pipelines: batch ingest files, URLs, and directories
• Admin tooling: manage accounts, users, and roles in a multi-tenant deployment
• Backend services: retrieve context before calling an LLM, implement RAG workflows
• Session tracking: build persistent conversation memory with automatic knowledge extraction
• Full API access: covers the complete OpenViking REST API, not just a subset

OpenViking also exposes an MCP server that integrates directly with Claude, Cursor, and other AI tools. MCP is the right choice when an AI model needs to call OpenViking as a tool inside a chat interface.

Use Huscarl when you are building Node.js services, ingestion pipelines, admin tooling, or anything that needs programmatic access beyond what MCP's six high-level tools expose.

npm install @yfedberts/huscarl

Requires Node.js >= 18.

import { Huscarl } from "@yfedberts/huscarl";

const huscarl = new Huscarl({
  url: "http://localhost:1933",
  apiKey: "your-api-key",
});

await huscarl.initialize(); // verify server is reachable

// Ingest a document
await huscarl.resources.add("./docs/guide.md", {
  target: "docs/",
  reason: "Project documentation",
  wait: true, // block until embeddings are ready
});

// Semantic search
const results = await huscarl.retrieval.find("how to configure authentication", {
  targetUri: "viking://resources/docs/",
  limit: 5,
});

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

A typical integration follows this pattern:

1. Ingest: Add files, URLs, or directories via resources.add(). Set wait: true to block until semantic processing completes, or call waitProcessed() at a checkpoint.

2. Retrieve: Use retrieval.find() for vector similarity search, retrieval.search() for context-aware search that uses conversation history to expand the query, or retrieval.grep() / retrieval.glob() for exact text and filename matching.

3. Track: Create a session, append messages with addMessage(), record which contexts were actually used with used(), then call commit() to archive the conversation and trigger long-term memory extraction.

4. Administer: Use admin to manage accounts and users in a multi-tenant deployment. Use contexts.get() to obtain a scoped handle that acts as a specific user, useful for building multi-user backends.

The examples/ folder contains runnable .ts files for common patterns: quickstart, RAG pipeline, batch ingestion, and multi-tenant setup. Each file is self-contained with inline comments.

All methods throw HuscarlError on failure. Use HuscarlError.isHuscarlError(err) as a type guard.

import { HuscarlError } from "@yfedberts/huscarl";

try {
  await huscarl.resources.read("missing/file.md");
} catch (err) {
  if (HuscarlError.isHuscarlError(err)) {
    console.error(err.code, err.message);
  }
}

npm install       # install dependencies
npm run typecheck # type-check without emitting
npm test          # run tests
npm run build     # build CJS + ESM + .d.ts

Zero runtime dependencies. Contributions welcome - open an issue or PR.

Licensed under the Apache License 2.0.

Copyright 2026 Yulius Faustinus Edbert Santoso