telys-ai (TypeScript SDK)

Telys — embedded, on-device memory & retrieval for AI systems. Filtered vector search as a contiguous memory operation: in-process, zero cloud roundtrips at query time. This is the TypeScript SDK (published as telys-ai — npm's typo-squatting guard holds the bare telys name pending review); the Python SDK lives in packages/telys-sdk.

Encapsulated by design — no sidecar, no setup

npm install telys-ai gives you the engine inside your Node process. The closed Mojo runtime (libty_runtime) is loaded in-process over a frozen C-ABI (koffi FFI) — there is no server process to manage and nothing to configure:

• a runtime already installed by the Python CLI (telys runtime install) is reused from $TELYS_HOME/runtime/<platform>/ (default ~/.telys) — both SDKs share one verified install;
• otherwise the SDK fetches the signed bundle itself (TELYS_TOKEN / TELYS_API_KEY) and verifies it OFFLINE: RS256 manifest signature + SHA-256 artifact hashes + the strict ver:2 license policy — the same trust core as the Python SDK (telys/verify.py), ported to node:crypto.

Install is the only networked step. Queries never touch the network.

import { Telys, Eq } from "telys-ai";

const db = await Telys.open("./memory");           // resolves/installs the signed runtime
const col = db.createCollection("docs", {
  dim: 768,
  partitionBy: "tenant_id",
  filterColumns: ["lang"],
});

col.add(vectors, ids, metadata);                   // bring your own vectors (embedding-agnostic)
const hits = col.search(queryVec, {
  topK: 10,
  where: new Eq("tenant_id", "acme"),              // partition-key or filter-column equality
  explain: true,
});

Surface

| Area | API | |---|---| | Engine | await Telys.open(path) · Telys.openSync(path) · createCollection · openCollection · collections() · scopeKey(...parts) | | Collection | add (new ids only) · upsert · update (strict — unknown ids raise) · search · ids(where?) · fetch(ids) · delete · compact · snapshot · stats · save | | Filters | new Eq(column, value) on the partition key or any declared filter column | | Runtime ops | ensureRuntime() · installFromHost() · installFromFile() · verifyInstalled() · resolveRuntimeLib() | | Trust core | verifyManifest() · verifyLicense() · verifyArtifact() (RS256, fail-closed) |

Embedders (text in / text out) are Python-side today (kernel-backed bigram/multigram) — from TypeScript, bring your own vectors (any embedding model). Text search + lexical (the CoIR-beating code index) are on the roadmap for this SDK.

Cross-language collections

Collections persist in the SAME on-disk format as the Python SDK (ty_base.npy + ty_native.json + collection.json): a store written by Python opens in TypeScript and vice versa, including the Python id_map.npy pickle sidecar. Verified both directions by the test suite.

Requirements

• Node >= 22 (koffi prebuilds: macOS arm64/x64, Linux x64/arm64, Windows x64)
• Runtime platform: macOS arm64 or Linux x86_64 (the signed-bundle P0 targets; see telys/paths.py)

Development

npm install
npm test          # build + unit (trust core, pickle sidecar) + lifecycle on the real Mojo runtime

The lifecycle tests resolve libty_runtime via $TELYS_NATIVE_KERNEL, a verified ~/.telys install, or the repo dev build (mojo_build/libty_runtime.<ext> — built with pixi, see the root README), and skip cleanly when none is present.