@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.

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

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

60-Second Quickstart

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)

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)

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.

// 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

// 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

// 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:

// 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.

// 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
• Python SDK on PyPI
• REST API Reference
• Full Documentation

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