# Cortex AI TypeScript SDK

The official TypeScript SDK for the Cortex AI platform. Build powerful, context-aware AI applications in your Node.js or TypeScript projects.

**Cortex** is your plug-and-play memory infrastructure. It powers intelligent, context-aware retrieval for any AI app or agent. Whether you’re building a customer support bot, research copilot, or internal knowledge assistant - Cortex handles all!

[Learn more about the SDK from our docs](https://docs.usecortex.ai/)

## Core features

* **Dynamic retrieval and querying** that always retrieve the most relevant context
* **Built-in long-term memory** that evolves with every user interaction
* **Personalization hooks** for user preferences, intent, and history
* **Developer-first SDK** with the most flexible APIs and fine-grained controls

## Getting started

### Installation

```
npm i @usecortex_ai/node
# or
yarn add @usecortex_ai/node
# or
pnpm add @usecortex_ai/node
```

### Client setup

```ts
import { CortexAIClient } from "@usecortex_ai/node";

const client = new CortexAIClient({
  token: process.env.CORTEX_API_KEY,
});
```

### Create a Tenant

You can consider a `tenant` as a single database that can have internal isolated collections called `sub-tenants`. [Know more about the concept of tenant here](https://docs.usecortex.ai/essentials/multi-tenant)

```ts
async function createTenant() {
  const tenantCreationResponse = await client.tenant.create({
    tenant_id: "my-company"
  });
  return tenantCreationResponse;
}
```

### Index Your Data

When you index your data, you make it ready for retrieval from Cortex using natural language.

```ts
// Add to your knowledge base
import fs from 'fs';

const uploadResult = await client.upload.knowledge({
  files: [
    fs.readFileSync("a.pdf"),
    fs.readFileSync("b.pdf")
  ],
  tenant_id: "tenant_123",
  file_metadata: [
    {
      id: "doc_a",
      tenant_metadata: { dept: "sales" },
      document_metadata: { author: "Alice" },
      relations: false
    },
    {
      id: "doc_b",
      tenant_metadata: { dept: "marketing" },
      document_metadata: { author: "Bob" },
      relations: true
    }
  ]
});

// Index user memories
const result = await client.userMemory.add({
  memories: [
    {
      text: "User prefers detailed explanations and dark mode",
      infer: true,
      user_name: "John"
    }
  ],
  tenant_id: "tenant-01",
  sub_tenant_id: "",
  upsert: true
});

// Markdown content
const markdownResult = await client.userMemory.add({
  memories: [
    {
      text: "# Meeting Notes\n\n## Key Points\n- Budget approved\n- Launch date: Q2",
      is_markdown: true,
      infer: false,
      title: "Meeting Notes"
    }
  ],
  tenant_id: "tenant-01",
  sub_tenant_id: "",
  upsert: true
});

// User-assistant pairs with inference
const conversationResult = await client.userMemory.add({
  memories: [
    {
      user_assistant_pairs: [
        { user: "What are my preferences?", assistant: "You prefer dark mode and detailed explanations." },
        { user: "How do I like my reports?", assistant: "You prefer weekly summary reports with charts." }
      ],
      infer: true,
      user_name: "John",
      custom_instructions: "Extract user preferences"
    }
  ],
  tenant_id: "tenant-01",
  sub_tenant_id: "",
  upsert: true
});
```

> **For a more detailed explanation** of document upload, including supported file formats, processing pipeline, metadata handling, and advanced configuration options, refer to the [Ingest Knowledge](https://docs.usecortex.ai/api-reference/endpoint/add-knowledge-memories).

### Search 

```ts
// Search across memories/knowledge base
const results = await client.recall.fullRecall({
  query: "Which mode does user prefer",
  tenantId: "tenant_1234",
  subTenantId: "sub_tenant_4567",
  alpha: 0.8,
  recencyBias: 0
});;

// List all the data (memories + knowledge base)
const allSources = await client.data.listData({
  tenant_id: "tenant_1234",
  sub_tenant_id: "sub_tenant_4567"
});
```

> **For a more detailed explanation** of search and retrieval, including query parameters, scoring mechanisms, result structure, and advanced search features, refer to the [Recall endpoint documentation](https://docs.usecortex.ai/api-reference/endpoint/smart).

## SDK Method Structure & Type Safety

Our SDKs follow a predictable pattern that mirrors the API structure while providing full type safety.

> **Method Mapping** : `client.<group>.<functionName>` mirrors `api.usecortex.ai/<group>/<function_name>`
>
> For example: `client.upload.uploadText()` corresponds to `POST /upload/upload_text`

The SDKs provide exact type parity with the API specification:

- **Request Parameters** : Every field documented in the API reference (required, optional, types, validation rules) is reflected in the SDK method signatures
- **Response Objects** : Return types match the exact JSON schema documented for each endpoint
- **Error Types** : Exception structures mirror the error response formats from the API
- **Nested Objects** : Complex nested parameters and responses maintain their full structure and typing

> This means you can rely on your IDE’s autocomplete and type checking. If a parameter is optional in the API docs, it’s optional in the SDK. If a response contains a specific field, your IDE will know about it. Our SDKs are built in such a way that your IDE will automatically provide **autocompletion, type-checking, inline documentation with examples, and compile time validation** for each and every method.
>
> Just hit **Cmd+Space/Ctrl+Space!**

## Links

- **Homepage:** [usecortex.ai](https://www.usecortex.ai/)
- **Documentation:** [docs.usecortex.ai](https://docs.usecortex.ai/)

## Our docs

Please refer to our [API reference](https://docs.usecortex.ai/api-reference/introduction) for detailed explanations of every API endpoint, parameter options, and advanced use cases.

## Support

If you have any questions or need help, please reach out to our support team at [founders@usecortex.ai](mailto:founders@usecortex.ai).