npm package: @sovant/sdk
Description: Official Sovant Memory-as-a-Service SDK for JavaScript and TypeScript
Author: Sovant
Latest version: 1.4.4

# @sovant/sdk

**Sovant is a governed AI memory layer for LLM applications.**
It gives your apps hybrid recall, profile-aware context, and a structured memory store you can audit, inspect, and control.

The official **JavaScript and TypeScript** SDK for the Sovant Memory API.

[![npm version](https://img.shields.io/npm/v/@sovant/sdk)](https://www.npmjs.com/package/@sovant/sdk)
[![Documentation](https://img.shields.io/badge/docs-sovant.ai-blue)](https://sovant.ai/docs)
[![GitHub](https://img.shields.io/badge/github-sovant-lightgrey)](https://github.com/sovant-ai/sovant)

---

## What is Sovant?

Sovant is an **AI infrastructure company** providing the **memory layer for AI systems**.  
Our platform makes it simple to persist, search, and manage conversational and contextual data securely across sessions, channels, and applications.

- **Problem:** Most AI systems forget everything once a session ends. This causes compliance risks, knowledge loss, and poor user experience.  
- **Solution:** Sovant provides a **Memory-as-a-Service API** — a single SDK and API key that lets you store, retrieve, and search memories with audit-ready controls.  
- **Target audience:** Developers, startups, and enterprises building AI agents, copilots, or compliance-driven apps who need context persistence.

---

## Installation

```bash
npm install @sovant/sdk
# or
yarn add @sovant/sdk
# or
pnpm add @sovant/sdk
```

## 60-Second Quickstart

### TypeScript

```typescript
import { Sovant } from "@sovant/sdk";

const sv = new Sovant({ apiKey: process.env.SOVANT_API_KEY! });

// Create a memory
await sv.memory.create({
  data: { note: "User prefers morning meetings" },
  type: "preference"
});

// Search memories
const results = await sv.memory.search({
  query: "meeting preferences",
  limit: 3
});

console.log(results);
```

### JavaScript (ESM)

```javascript
import { Sovant } from "@sovant/sdk";

const sv = new Sovant({ apiKey: process.env.SOVANT_API_KEY });

// Create a memory
await sv.memory.create({
  data: "User prefers morning meetings",
  type: "preference"
});

// Search memories
const results = await sv.memory.search({
  query: "meeting preferences",
  limit: 3
});

console.log(results);
```

### JavaScript (CommonJS)

```javascript
const { Sovant } = require("@sovant/sdk");

const sv = new Sovant({ apiKey: process.env.SOVANT_API_KEY });

// Works the same as ESM
sv.memory.create({ data: "User likes coffee", type: "preference" })
  .then(() => console.log("Memory saved!"));
```

## Recall vs Search

Sovant provides two ways to query memories:

- **`memory.recall()`** – Hybrid recall, profile-aware
  Best for conversational AI queries like "What do you know about me?" or "What happened on Project X?".
  Uses Sovant's hybrid pipeline (profile fast-path + thread-scoped lexical + vector semantic search) and prioritizes profile facts (name/age/location) when available.

- **`memory.search()`** – Semantic search
  Best for topic-based lookup and discovery, e.g., "hiking", "Q1 marketing plan".
  Pure vector similarity search without profile logic. Behavior unchanged from previous versions.

```typescript
// Recall for conversational queries (returns { results: [...], total, query_type })
const recall = await sv.memory.recall({
  query: "what do you know about me?",
  limit: 10
});
console.log(recall.results); // array of matching memories

// Search for topic discovery
const topics = await sv.memory.search({
  query: "project updates",
  limit: 5
});
```

## Working with Threads

Threads let you organize related memories into conversations or sessions. Each thread has a `title` and can contain multiple memories.

### Create a thread and store memories

```typescript
// Create a new thread
const thread = await sv.threads.create({
  title: "Project Alpha Discussion",
  description: "Q1 planning meeting notes",
  metadata: { project: "alpha", quarter: "Q1" }
});

// Store memories in the thread
await sv.memory.create({
  data: "Decided to launch in March",
  type: "journal",
  thread_id: thread.id
});

await sv.memory.create({
  data: "Budget approved: $50k",
  type: "insight",
  thread_id: thread.id
});

// Recall memories from this specific thread
const threadRecall = await sv.memory.recall({
  query: "launch date",
  thread_id: thread.id,
  limit: 10
});
console.log(threadRecall.results); // thread-scoped matches
```

### List and manage threads

```typescript
// List all threads
const { threads, total } = await sv.threads.list({
  limit: 20,
  offset: 0
});

// Get a specific thread with its memories
const result = await sv.threads.get(thread.id, {
  include_memories: true,
  limit: 50
});

// Update thread details
await sv.threads.update(thread.id, {
  title: "Project Alpha - Q1 Launch",
  status: "completed"
});

// Delete a thread (keeps memories by default)
await sv.threads.delete(thread.id);

// Delete a thread and all its memories
await sv.threads.delete(thread.id, true);
```

### Default mode (without threads)

You can still use Sovant without threads - just omit `thread_id`:

```typescript
// Store memory globally
await sv.memory.create({
  data: "User prefers email notifications",
  type: "preference"
});

// Recall from all memories
const recall = await sv.memory.recall({
  query: "notification preferences"
});
console.log(recall.results);
```

## List Memories

Fetch memories with filtering and pagination. Use `list()` to retrieve recent memories or filter by criteria — it's more efficient than `search()` when you don't need vector similarity.

```typescript
// List recent memories
const { memories, total, has_more } = await sv.memory.list({
  limit: 20,
  offset: 0
});

// Filter by thread
const threadMemories = await sv.memory.list({
  thread_id: "thread-uuid",
  limit: 50
});

// Filter by type and tags
const preferences = await sv.memory.list({
  type: "preference",
  tags: ["settings"],
  sort_by: "updated_at",
  sort_order: "desc"
});

// Pinned memories only
const pinned = await sv.memory.list({
  is_pinned: true
});
```

**Available parameters:**
- `limit` — max results (default: 20, max: 100)
- `offset` — pagination offset
- `thread_id` — filter by thread
- `type` — filter by memory type
- `tags` — filter by tags (must have all)
- `is_pinned` — filter by pinned status
- `is_archived` — filter by archived status
- `sort_by` — `created_at`, `updated_at`, `importance`, or `type`
- `sort_order` — `asc` or `desc`

## Features

- **Memory CRUD** — create, list, retrieve, update, delete memories
- **Semantic Search** — query memories with filters and ranking
- **Threads** — organize memories into conversations or sessions (fully supported in SDK)
- **Batch Operations** — create multiple memories in one request
- **Compliance-ready** — audit trails, PDPA/GDPR-friendly by design
- **SDKs** — official TypeScript and Python SDKs, with REST API reference

## SDKs and Documentation

- [TypeScript SDK Documentation](https://sovant.ai/docs/sdk/typescript)
- [Python SDK on PyPI](https://pypi.org/project/sovant/)
- [REST API Reference](https://sovant.ai/docs/api)
- [Full Documentation](https://sovant.ai/docs)

## API Overview

### Endpoints Summary
- `POST /api/v1/memory` — Create memory
- `GET /api/v1/memory` — List memories
- `GET /api/v1/memories/{id}` — Get memory by ID
- `PATCH|PUT /api/v1/memories/{id}` — Update memory
- `DELETE /api/v1/memories/{id}` — Delete memory
- `GET /api/v1/memory/search` — Search memories
- `POST /api/v1/memory/batch` — Batch create

## Field Mapping Note

- **SDK level:** accepts `data`
- **API level:** expects `content`
- SDK automatically converts `data` → `content`.

## Versioning & Changelog

- **Current release:** 1.4.4
- Version 1.4.4 — add `X-Sovant-Client` header for SDK telemetry
- Version 1.4.3 — add `memory.list()` for filtered pagination
- Version 1.4.2 — README sync
- Version 1.4.1 — CJS export fix
- Version 1.4.0 — full threads support (create, list, get, update, delete)
- Version 1.3.0 — hybrid recall with profile awareness
- Version 1.2.0 — retry logic, batch operations, telemetry hooks

## License & Use

- This SDK is MIT-licensed for integration convenience.
- The Sovant API and platform are proprietary to Sovant Technologies Sdn. Bhd.
- You may use this SDK to integrate with Sovant's hosted API.
- Hosting/redistributing the Sovant backend or any proprietary components is not permitted.

## License

MIT © Sovant AI