Moss - Real-time Semantic Search for Conversational AI

The Moss JavaScript SDK (@moss-js/moss) brings semantic search to Node.js. It wraps a high-performance Rust core and exposes an async, Promise-based API. Documents are embedded and queried locally, with optional cloud sync.

Requirements

Node.js 20.4 or higher

Install

npm install @moss-js/moss

Keep optional dependencies on. The native binary comes only from the @moss-js/moss-core-<platform> package that npm installs for your platform as an optional dependency. After npm install --omit=optional, optional=false in .npmrc or pnpm --no-optional, importing @moss-js/moss throws Cannot find native binding. The same happens on npm ci from a lockfile that npm older than 11.3 rebuilt while node_modules existed, because that lockfile keeps only that machine’s platform package. Before installing on another platform, such as Linux CI or Docker from a lockfile made on a Mac, regenerate the lockfile with node_modules removed, or with npm 11.3 or newer. (@moss-js/moss 1.17.0+)

Versions below 1.9.0 will stop loading models when the legacy download path is retired. Upgrade to 1.9.0+ before then.

Moss for Node moved from @moss-dev/moss to @moss-js/moss with 1.8.0. @moss-dev/moss is a frozen 1.7.1 package. Versions below 1.9.0 will stop loading models when the legacy download path is retired. Upgrade to @moss-js/moss 1.9.0+ before then. The date will be announced in the changelog. @moss-dev/moss-web is the browser SDK and is not this package.

Get your projectId and projectKey from the Moss portal.

Two ways to search

MossClient - the entry point. Manage cloud indexes, load one into memory, and query it.
SessionIndex - a local, in-process index for real-time indexing during a live interaction; push to the cloud when done.

Quick start

import { MossClient } from '@moss-js/moss'

const client = new MossClient(process.env.MOSS_PROJECT_ID!, process.env.MOSS_PROJECT_KEY!)

await client.createIndex('faqs', [
  { id: 'doc1', text: 'Track your order in your account.', metadata: { category: 'shipping' } },
  { id: 'doc2', text: '30-day return policy for most items.', metadata: { category: 'returns' } },
])
await client.loadIndex('faqs')
const results = await client.query('faqs', 'return a damaged product', { topK: 3 })
results.docs.forEach(d => console.log(d.id, d.score))

Indexes

Create, inspect, and delete cloud indexes. Mutations run as async jobs and return a MutationResult with a jobId and docCount.

// Create (defaults to moss-minilm)
const result = await client.createIndex('faqs', documents)

// Inspect
const info = await client.getIndex('faqs')   // IndexInfo: name, docCount, model.id, status
const indexes = await client.listIndexes()    // IndexInfo[]

// Delete
await client.deleteIndex('faqs')

Index from files

Build an index straight from PDF and DOCX files - the server parses, chunks, and embeds them. Up to 20 files per call.

await client.createIndexFromFiles('contracts', [
  { name: 'report.pdf', contentType: 'application/pdf', path: '/docs/report.pdf' },
], { parseOptions: { ocrMode: 'full_ocr' } })

See Index from files.

Documents

Add, update, fetch, and remove documents on an existing index.

// Add or upsert
await client.addDocs('faqs', newDocs, { upsert: true })

// Fetch all, or by id
const allDocs = await client.getDocs('faqs')
const some = await client.getDocs('faqs', { docIds: ['doc1', 'doc2'] })

// Delete by id
await client.deleteDocs('faqs', ['doc6', 'doc7'])

Load and query

Load an index into memory, then query it in-process. Call loadIndex before querying.

await client.loadIndex('faqs')
const results = await client.query('faqs', 'return a damaged product', { topK: 3 })
results.docs.forEach(d => console.log(d.id, d.score, d.text))

Hybrid search

Blend semantic and keyword scoring with alpha (1.0 = semantic, 0.0 = keyword; default 0.8).

await client.query('faqs', 'return policy', { topK: 3, alpha: 0.6 })

See Hybrid search.

Metadata filtering

Narrow results by document metadata on a loaded index.

await client.query('products', 'running shoes', {
  topK: 5,
  filter: {
    $and: [
      { field: 'category', condition: { $eq: 'shoes' } },
      { field: 'price',    condition: { $lt: 100 } },
    ],
  },
})

Operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $near, composed with $and / $or. See Metadata filtering.

Custom embeddings

Supply your own vectors with modelId: 'custom' (each document carries embedding, and queries pass embedding).

await client.createIndex('tickets', docsWithEmbeddings, { modelId: 'custom' })
await client.loadIndex('tickets')
await client.query('tickets', 'billing problem', { topK: 3, embedding: queryVector })

See Custom embeddings.

Sessions

Index and query locally in real time with a SessionIndex, then push to the cloud. session() starts empty; session.loadIndex(name) resumes an existing cloud index.

const session = await client.session('call-123')
await session.addDocs([{ id: 'turn-1', text: 'Customer reported a duplicate charge.' }])
const hits = await session.query('billing issue', { topK: 3 })
await session.pushIndex()

See Sessions.

Keeping indexes fresh

Auto-refresh a loaded index (poll the cloud and hot-swap newer versions in automatically), and track async jobs.

await client.loadIndex('faqs', { autoRefresh: true, pollingIntervalInSeconds: 300 })
const status = await client.getJobStatus(result.jobId)

Authentication

Construct the client with a projectKey for server-side use, or use a custom authenticator to mint short-lived tokens for untrusted clients (getAuthToken()).

const { token, expiresIn } = await client.getAuthToken()

See Custom Authenticator.

Errors

A failure from the native core rejects with an Error whose code is a stable MossErrorCode, such as NOT_FOUND or NETWORK. Branch on code, not on the message. isMossError narrows a caught value, and loadIndexes reports each failed name’s code in failedCodes. Some checks the SDK makes itself, such as a closed client, throw a plain Error with no code. (@moss-js/moss 1.16.0+)

import { isMossError } from '@moss-js/moss'

try {
  await client.query('faqs', 'refund policy')
} catch (error) {
  if (isMossError(error) && error.code === 'NOT_FOUND') {
    await client.loadIndex('faqs')
  } else {
    throw error
  }
}

See Error codes.

Models

moss-minilm (default) - fast, lightweight
moss-mediumlm - higher accuracy
custom - supply your own embedding vectors via DocumentInfo.embedding

Guides

Reference

MossClient and SessionIndex, plus all interfaces and types, are in the Reference section of the sidebar.

Python

JavaScript

Swift (iOS)

Android

Elixir

Browser

C

Overview

Requirements

Install

Two ways to search

Quick start

Indexes

Index from files

Documents

Load and query

Hybrid search

Metadata filtering

Custom embeddings

Sessions

Keeping indexes fresh

Authentication

Errors

Models

Guides

Reference

​Requirements

​Install

​Two ways to search

​Quick start

​Indexes

​Index from files

​Documents

​Load and query

​Hybrid search

​Metadata filtering

​Custom embeddings

​Sessions

​Keeping indexes fresh

​Authentication

​Errors

​Models

​Guides

​Reference

Requirements

Install

Two ways to search

Quick start

Indexes

Index from files

Documents

Load and query

Hybrid search

Metadata filtering

Custom embeddings

Sessions

Keeping indexes fresh

Authentication

Errors

Models

Guides

Reference