Quick Start

Get CtxIQ running in under five minutes. This guide walks you from installation to your first managed AI session.

Installation

npm

pnpm

yarn

npm

bash npm install @ctxiq/sdk

pnpm

bash pnpm add @ctxiq/sdk

yarn

bash yarn add @ctxiq/sdk

success

Requirements: Node.js 18+, TypeScript 4.9+ (optional but recommended). Works with CommonJS and ESM.

Basic Setup

Add your API key to your environment. CtxIQ reads from CTXIQ_KEY by default.

CTXIQ_KEY=ctxiq_live_xxxxxxxxxxxxxxxx

First Session

Import and initialize

Create an orchestrator instance with your chosen adapter and token budget.

import { CtxIQ } from '@ctxiq/sdk';

const orchestrator = new CtxIQ({
  apiKey: process.env.CTXIQ_KEY,
  adapter: 'openai-v4-turbo',
  budget: 4096,
});

Create a session

Call createSession() with a unique user identifier. CtxIQ will persist state across calls.

const session = await orchestrator.createSession({
  id: 'user-unique-id',
  persistence: 'long-term',
});

Send messages

Use session.ask() to send messages. Context pruning and session management happen automatically.

const response = await session.ask("What is the capital of France?");
console.log(response.content);

Inspect metrics

Access session.metrics for real-time token usage, pruning events, and latency data.

const { budget, pruningEvents, latencyMs } = session.metrics;
console.log(`Used ${budget.used}/${budget.limit} tokens`);

Next Steps

Now that you have a working session, explore the core concepts:

Session Management — persistence modes, TTL, lifecycle
Token Budgeting — hard/soft limits, budget events
Semantic Pruning — tuning similarity thresholds
Adapter Integration — switching providers, custom adapters