TypeScript SDK

The TypeScript SDK is published as @illumina/client. Its IlluminaClient class wraps every common operation and runs in Node.js, Bun, Deno, and the browser (it uses the fetch API). All methods are async, take namespaceId as the first argument, and accept an optional signal (an AbortSignal) inside their options object.

Install

npm install @illumina/client

Initialize

Construct the client with the hosted base URL and your API key. The key is sent as a bearer token on every request:

import { IlluminaClient } from "@illumina/client";
 
const client = new IlluminaClient({
  baseUrl: "https://api.illumina.sh",
  apiKey: "sub_live_...",
});

Core operations

Memories live in namespaces, and retain does not auto-create one — create it first:

await client.createNamespace("alice");

Retain

Store raw text; Illumina extracts facts, entities, and relationships. retain(namespaceId, content, options?):

await client.retain("alice", "Ada shipped the payments rewrite in Q3 2025.", {
  context: "standup notes",
  tags: ["work"],
});

Options: timestamp, context, metadata, documentId, async, entities, tags, updateMode ("replace" | "append"), observationScopes, strategy, and factType ("world" | "experience" | "decision").

Use retainBatch(namespaceId, items, options?) for multiple memories in one request — each item requires content:

await client.retainBatch("alice", [
  { content: "Alice loves hiking" },
  { content: "Alice visited Paris", context: "travel", timestamp: "2024-07-01" },
], { async: true });

retainFiles(namespaceId, files, options?) takes an Array<File | Blob> plus context or filesMetadata, always processes asynchronously, and returns operation IDs for tracking progress.

Recall

Query a namespace by semantic similarity. recall(namespaceId, query, options?) — budget ("low" | "mid" | "high") controls retrieval effort and defaults to "mid":

const recalled = await client.recall("alice", "What are Alice's hobbies?", {
  budget: "mid",
  includeEntities: true,
});
for (const result of recalled.results) {
  console.log(result.text);
}

Other options: types (filter by fact type), maxTokens, tags and tagsMatch ("any" | "all" | "any_strict" | "all_strict"), tagGroups (compound boolean tag filters, mutually exclusive with tags/tagsMatch), includeChunks, includeSourceFacts, queryTimestamp, and trace.

recall returns a RecallResponse whose facts live on .results (not a bare array). The exported helper recallResponseToPromptString(response) serializes a response into a string for LLM prompts.

Reflect

Ask a higher-level question over everything the namespace knows. reflect(namespaceId, query, options?) — budget defaults to "low"; the answer is on .text:

const answer = await client.reflect("alice", "Summarize Ada's recent work", {
  factTypes: ["world", "observation"],
});
console.log(answer.text);

Other options: context, maxTokens, responseSchema (a JSON Schema — the response then includes structured_output), tags, tagsMatch, tagGroups, excludeAutomations, and excludeAutomationIds.

Error handling

Failed requests throw an IlluminaError carrying statusCode and details:

import { IlluminaClient, IlluminaError } from "@illumina/client";
 
try {
  await client.recall("missing", "anything");
} catch (err) {
  if (err instanceof IlluminaError) {
    console.error(err.statusCode, err.details);
  }
}

Method reference

Retain

Recall

Reflect

Memories

Namespaces

The createNamespace disposition fields (name, mission, background, disposition*) are deprecated in favour of updateNamespaceConfig.

Namespace config

Automations

Directives

Documents

Ontology

Communities

Beyond the wrapper

The package re-exports the generated layer for any endpoint the wrapper does not cover (entity graph, operations, webhooks, namespace templates, monitoring):

import { sdk, createClient, createConfig } from "@illumina/client";

Request and response types are exported from the package root as well (for example RecallResponse, ReflectResponse, RetainResponse, Budget, MemoryItem).