TypeScript SDK

@keyoku/memory is the official TypeScript client for the Keyoku Engine. It provides a typed, promise-based API for every engine endpoint — memory CRUD, semantic search, heartbeat signals, scheduling, watcher management, teams, and real-time event streaming.

Installation

npm install @keyoku/memory

Requires Node.js 20+ and ESM ("type": "module" in your package.json).

Quick Start

import { KeyokuClient } from '@keyoku/memory';

const client = new KeyokuClient({
  baseUrl: 'http://localhost:18900',  // default
  timeout: 30_000,                    // default: 30s
  token: 'optional-bearer-token',     // or () => getToken()
});

// Store a memory (auto-extracts facts)
const result = await client.remember('user:alice', 'Alice prefers dark mode and uses VS Code');
console.log(result); // { memories_created: 2, memories_updated: 0, ... }

// Semantic search
const hits = await client.search('user:alice', 'editor preferences');
hits.forEach(h => console.log(h.memory.content, h.score));

// Heartbeat check (pure SQL scan)
const heartbeat = await client.heartbeatCheck('user:alice');
if (heartbeat.should_act) {
  console.log(heartbeat.summary);
}

Constructor Options

API Categories

The client exposes 35 public methods organized into 7 categories:

See the Client API page for full method signatures and the Types page for all TypeScript interfaces.

Error Handling

import { KeyokuClient, KeyokuError } from '@keyoku/memory';

try {
  await client.search('user:alice', 'query');
} catch (err) {
  if (err instanceof KeyokuError) {
    console.log(err.status);   // HTTP status code (e.g. 404)
    console.log(err.path);     // API path (e.g. /api/v1/search)
    console.log(err.message);  // Error description
  }
}

All non-2xx responses throw KeyokuError with the HTTP status code, request path, and error message. Timeouts propagate as standard AbortError.

Authentication

Tokens are sent as Authorization: Bearer <token> headers. The token option accepts either a static string or a function, enabling dynamic token rotation at request time.

// Static token
const client = new KeyokuClient({ token: process.env.KEYOKU_TOKEN });

// Dynamic token (resolved per-request)
const client = new KeyokuClient({
  token: () => getCurrentSession()?.accessToken,
});

Authentication is optional — a local Keyoku instance typically runs without tokens.