@klevox-context/sdk

The official TypeScript SDK for Klevox Context — retrieval and memory primitives for AI agents.

Install

npm i @klevox-context/sdk

Get an API key

1. Sign up at https://context.klevox.com.
2. Create a project. The project ID appears in the URL: https://context.klevox.com/projects/<project-id>.
3. Generate an API key under Settings → API Keys. Treat it like a password — store it in KLEVOX_API_KEY env var, never check it into source.

Quickstart

import { Klevox } from "@klevox-context/sdk";

const kx = new Klevox({ apiKey: process.env.KLEVOX_API_KEY });
const p = kx.project(process.env.KLEVOX_PROJECT_ID!);

// userId is required: it scopes per-user memory and access policies
// the server uses to filter retrieval results (omitting it returns 422).
const result = await p.retrieve({
  query: "what did we decide about pricing tiers?",
  userId: process.env.KLEVOX_USER_ID ?? "demo-user",
});
for (const c of result.chunks) {
  console.log(c.score.toFixed(2), c.source, c.text.slice(0, 200));
}

Sample output:

0.87  vector   We standardized on three tiers: Free, Pro …
0.81  episode  Q4 review confirmed Pro tier conversion …
0.74  memory   Pricing changes require finance approval …

result.chunks is an array of RetrievalChunk objects with id (use it to deduplicate or build citations), text, score, source (one of "vector", "graph", "memory", "episode", "fused"), documentId, episodeId, provenanceIds (audit-trail IDs that link the chunk back to the originating events — useful for citations and recall debugging), and metadata. See src/types/retrieve.ts for the full shape.

v1 limitation: topK, tools, metadata, and additionalProjectIds are accepted on the SDK type for forward compatibility but the v1 server applies its own defaults — these options have no effect until v0.2.

Adapters

// LangChain.js
import { KlevoxRetriever, KlevoxMemory } from "@klevox-context/sdk/langchain";

// LlamaIndex.TS
import { KlevoxRetriever } from "@klevox-context/sdk/llamaindex";

// Vercel AI SDK
import { tools } from "@klevox-context/sdk/ai-sdk";

CLI

npx klevox login
npx klevox retrieve "pricing tiers" --project=$KLEVOX_PROJECT_ID
npx klevox ingest ./handbook.pdf --project=$KLEVOX_PROJECT_ID --tags=hr,public --wait

Errors

The SDK throws a KlevoxError hierarchy. Each subtype tells you whether to retry, whether the SDK already retried, and (where applicable) carries an upgradeUrl. See docs/errors.md.

Migrating from Graphiti / Zep / Mem0

See docs/migration-from-graphiti-zep-mem0.md for a side-by-side mapping of the most common operations.

Runtime support

• Node.js >= 20, Bun, Deno — full support.
• Edge runtimes (Cloudflare Workers, Vercel Edge) — supported, but p.documents.add({ source: { kind: "file", path } }) is Node-only because it uses node:fs/promises. Use kind: "buffer" or kind: "blob" (browser File/Blob) on Edge.

License

Apache-2.0