Skip to main content
The Moss JavaScript SDK (@moss-dev/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 or higher

​
Install

npm install @moss-dev/moss
Get your projectId and projectKey from the Moss portal.
  • 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-dev/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')

​
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))
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() resumes an existing cloud index by name, or starts empty. 
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.

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