SDK

@cognitivx/sdk is a typed TypeScript client for the CognitiveX / iCog API at https://api.cognitivx.io. It is a thin, fully typed wrapper over fetch: each endpoint is a small function that returns a typed Promise, grouped into namespaces (memory, auth, billing, and so on). There is no class to instantiate. You configure one shared client, then call namespace functions.

The same package powers the CognitiveX web surfaces, so the types you import are the types the product runs on.

Install

pnpm add @cognitivx/sdk

Initialise

For server-side or programmatic use, configure the client once with an API key. The key is sent as Authorization: Bearer <key> on every request, and the browser cookie refresh flow is disabled (there is no .cognitivx.io cookie outside the browser).

import { configureApiClient } from '@cognitivx/sdk';

configureApiClient({
  apiKey: process.env.ICOG_API_KEY, // an `icog_...` key
});

Create keys at developers.cognitivx.io/keys. A key is shown only once; keep it server-side.

configureApiClient accepts:

Your first round trip

Write a memory, then read it back. Every namespace function returns a typed result you can await directly.

import { configureApiClient, memory } from '@cognitivx/sdk';

configureApiClient({ apiKey: process.env.ICOG_API_KEY });

// Store a fact. memory_type is one of: semantic, episodic, procedural, foundational.
const { memory_id } = await memory.remember({
  content: 'The user prefers dark mode and TypeScript.',
  memory_type: 'semantic',
});

// Read it back with semantic search.
const { memories, count } = await memory.recall({
  query: 'user preferences',
  limit: 5,
});

console.log(count, memories[0]?.text);

# Remember
curl -X POST https://api.cognitivx.io/api/remember \
  -H "Authorization: Bearer $ICOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"The user prefers dark mode and TypeScript.","memory_type":"semantic"}'

# Recall
curl -X POST https://api.cognitivx.io/api/recall \
  -H "Authorization: Bearer $ICOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"user preferences","limit":5}'

A recall response looks like:

{
  "count": 1,
  "memories": [
    {
      "id": "f3c1...",
      "text": "The user prefers dark mode and TypeScript.",
      "memory_type": "semantic",
      "age_days": 0,
      "created_at": "2026-06-16T09:12:44Z",
      "occurred_at": null,
      "occurred_at_end": null,
      "occurred_precision": null,
      "similarity": 0.83,
      "temporal_context": null
    }
  ]
}

Error handling

Any non-2xx response throws an ApiError. It carries the HTTP status, a human-readable message (taken from the API's detail or message field), and the raw parsed body so you can inspect structured error payloads.

import { configureApiClient, memory, ApiError } from '@cognitivx/sdk';

configureApiClient({ apiKey: process.env.ICOG_API_KEY });

try {
  await memory.remember({ content: 'A new fact.', memory_type: 'semantic' });
} catch (err) {
  if (err instanceof ApiError) {
    if (err.status === 401) {
      // Missing or invalid API key.
    } else if (err.status === 402 || err.status === 403) {
      // Tier or quota gate (e.g. remember requires `awakened`+).
      console.error(err.message, err.body);
    } else {
      throw err;
    }
  } else {
    throw err; // network or non-HTTP failure
  }
}

ApiError shape:

Common statuses you will handle across endpoints:

Namespaces

Import any namespace by name. Each is a flat group of functions over one part of the API.

Below, the most-used namespaces are documented with method, path, parameters, and examples. The full per-function reference (every signature, interface, and field) is generated from source under Generated reference.

memory

The cognitive value surface: write to and read from your persistent memory, and converse with iCog directly. Auth: Authorization: Bearer <key> (or X-API-Key: <key>).

memory.remember

Store a new memory. POST /api/remember. Requires the awakened tier or above.

const { memory_id } = await memory.remember({
  content: 'Shipped the org-memory feature on 2026-06-14.',
  memory_type: 'episodic',
});

Response: { "memory_id": "f3c1..." }

memory.recall

Semantic search over your memories. POST /api/recall. Works on any tier.

const { memories, count } = await memory.recall({
  query: 'what did I ship last week',
  limit: 10,
});

Response: { memories: MemoryResult[], count: number } (see the JSON example above).

memory.talk

Converse with iCog directly. It recalls context and replies as a cognitive peer. POST /api/talk. A streaming variant exists at POST /api/talk/stream (SSE).

const reply = await memory.talk({
  message: 'Should I retry on 5xx or fall back to a zero vector?',
  current_task: 'fixing intermittent 500s on remember',
});
console.log(reply.response, reply.context_used);

Response: { response: string, context_used: number, identity_proposal: object | null }

Other memory functions

Errors: 401 (bad key), 402/403 (remember/update below awakened), 404 (forget/update on a missing id), 422 (validation).

memories

CRUD and search over stored memories, with pagination. Useful for building memory browsers and admin views.

import { memories } from '@cognitivx/sdk';

const { memories: rows, total, has_more } = await memories.list({
  memory_type: 'episodic',
  limit: 20,
  sort: 'recent',
});

list and search return { memories: StoredMemory[], total: number, has_more: boolean }.

Errors: 401 (bad key), 404 (get/remove on a missing id), 422 (bad params).

keys

Personal API keys for programmatic and MCP access. Mounted at /api/auth/api-keys.

import { keys } from '@cognitivx/sdk';

const created = await keys.create({ name: 'ci-runner' });
console.log(created.key); // shown only once — store it now

Errors: 401 (bad session/key), 404 (revoke on a missing id).

billing

Tier, subscription, credit balance, and pay-as-you-go (PAYG) controls. Mounted at /api/billing.

import { billing } from '@cognitivx/sdk';

const status = await billing.me();
console.log(status.tier, status.payg_balance_usd);

billing.me() returns:

{
  "tier": "awakened",
  "subscription_status": "active",
  "trial_ends_at": null,
  "renewal_date": "2026-07-01",
  "subscription_interval": "monthly",
  "payg_eligible": true,
  "payg_balance_usd": 12.40,
  "payg_transactions_30d": 8
}

Errors: 401 (bad session/key), 402/403 (action not allowed on the current plan), 422 (e.g. top-up amount out of the $5–$500 range).

usage

Cognition observability — a read-only window onto the engine activity behind your memory. Mounted at /api/me/cognition.

import { usage } from '@cognitivx/sdk';

const recent = await usage.timeline(14);

Errors: 401 (bad key), 422 (days out of the 1–30 range).

senses

The multi-device registry: the Macs, phones, and other clients ("senses") attached to one account. Mounted at /api/senses.

import { senses } from '@cognitivx/sdk';

const device = await senses.register({
  device_type: 'mac',
  device_name: 'Parsa MacBook',
  device_uid: 'a-stable-per-install-id',
  capabilities: ['presence', 'voice'],
});
console.log(device.device_token); // shown only once — persist it

device_type is one of mac, iphone, android, ipad, web, watch. capabilities is a subset of presence, voice, location, motion, notifications, screen.

Errors: 401 (bad key), 404 (update/heartbeat/revoke on a missing id), 422 (bad device_type or capabilities).

orgs

Organizations — multi-user teams with isolated, shared memory. Mounted at /api/orgs. Most write actions require admin or owner role.

To scope recall / remember and other org-aware endpoints to an org's shared memory, set the active org. It is sent as the X-Org-ID header on every request.

import { configureApiClient, apiClient, orgs, memory } from '@cognitivx/sdk';

configureApiClient({ apiKey: process.env.ICOG_API_KEY });

// Set the active org for subsequent calls (X-Org-ID header).
apiClient.setActiveOrg('org_123'); // or: configureApiClient({ orgId: 'org_123' })

await memory.remember({ content: 'Team decision: ship behind a flag.', memory_type: 'semantic' });

apiClient.setActiveOrg(null); // back to personal memory

Selected functions:

The full set (member role updates, invite revocation, seat changes, GitHub authorize, logo upload/remove) is in the generated reference.

Errors: 401 (bad key), 403 (role too low for an admin/owner action), 404 (org / member / invite not found), 422 (validation).

Low-level client

Every namespace function calls apiClient under the hood. You can use it directly for endpoints not yet wrapped, or to set auth and org context.

import { apiClient } from '@cognitivx/sdk';

// Call any endpoint, typed.
const me = await apiClient.get<{ id: string; email: string }>('/api/auth/me');

Next steps