Moss - Real-time Semantic Search for Conversational AI

Data model

Each document has an id and text (plus optional metadata). Use moss-minilm as the default model.

Examples

import { MossClient } from '@moss-js/moss'
const client = new MossClient(process.env.MOSS_PROJECT_ID!, process.env.MOSS_PROJECT_KEY!)
await client.createIndex('my-index', [
  { id: 'doc-1', text: '...', metadata: { category: 'faq', tags: 'returns,shipping', lang: 'en' } },
  { id: 'doc-2', text: '...' }
], { modelId: 'moss-minilm' })

// Upsert more docs later
await client.addDocs('my-index', [
  { id: 'doc-2', text: 'updated text' }, // will be updated
  { id: 'doc-3', text: 'new text' }
], { upsert: true })

// Fetch specific docs
const subset = await client.getDocs('my-index', { docIds: ['doc-1', 'doc-3'] })

// Delete docs or the index when done
await client.deleteDocs('my-index', ['doc-3'])
await client.deleteIndex('my-index')

from moss import MossClient, DocumentInfo, MutationOptions, GetDocumentsOptions

client = MossClient(project_id, project_key)
await client.create_index('my-index', [
    DocumentInfo(id='doc-1', text='...', metadata={'category': 'faq', 'tags': 'returns,shipping', 'lang': 'en'}),
    DocumentInfo(id='doc-2', text='...')
], 'moss-minilm')

# Upsert more docs later
await client.add_docs('my-index', [
    DocumentInfo(id='doc-2', text='updated text'),
    DocumentInfo(id='doc-3', text='new text')
], MutationOptions(upsert=True))

# Fetch specific docs
subset = await client.get_docs('my-index', GetDocumentsOptions(doc_ids=['doc-1', 'doc-3']))

# Delete docs or the index when done
await client.delete_docs('my-index', ['doc-3'])
await client.delete_index('my-index')

From files (PDF and DOCX)

Build an index directly from raw documents - the server parses, chunks, and embeds them. Up to 20 files per call, 50 MB per file. Parsed document pages count against your plan’s monthly allowance; see Pricing & Limits. When the allowance is used up on a plan without overage billing, createIndexFromFiles fails with 429 USAGE_LIMIT_EXCEEDED at init or at confirm; a denial at confirm marks the job failed. PDF pages are counted before parsing. A PDF that cannot be page-counted before parsing (larger than 10 MB, unreadable, or past the page-counting budget of 200 MB or 20 seconds per request) is also denied on those plans. A confirm denied because your organization is running its maximum number of crawl and parse jobs leaves the job open: retry the confirm once a job finishes.

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

from moss import ParseFileInput, ParseOptions

await client.create_index_from_files('contracts', [
    ParseFileInput(name='report.pdf', content_type='application/pdf', path='/docs/report.pdf'),
], parse_options=ParseOptions(ocr_mode='full_ocr'))

See Index from files for parse options, limits, and querying notes.

From a website

Register a site as a web source and Moss crawls it into an index - optionally on a daily or weekly refresh schedule (scheduled refresh requires the Startup plan or above; omit refreshCadence on Developer and Hobbyist and re-sync manually on Hobbyist). Linked PDF and DOCX files found during the crawl are parsed into the same index. An index can hold up to 20 web sources. Each site is crawled and refreshed on its own, and a crawl only replaces that source’s pages, so several sites can share one index together with documents you add directly. The first source creates the index; later ones add to it, and a crawl requested while another is running on the index simply queues behind it.

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

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

const docs = await client.createWebSource('https://docs.yoursite.com', 'support-kb', {
  maxPages: 500,
  refreshCadence: 'weekly',
})
const blog = await client.createWebSource('https://blog.yoursite.com', 'support-kb', {
  maxPages: 200,
})
// Poll docs.jobId and blog.jobId with client.getJobStatus until status is 'completed'

from moss import MossClient  # 1.10.0+

client = MossClient(project_id, project_key)

docs = await client.create_web_source('https://docs.yoursite.com', 'support-kb',
                                      max_pages=500, refresh_cadence='weekly')
blog = await client.create_web_source('https://blog.yoursite.com', 'support-kb',
                                      max_pages=200)
# Poll docs.job_id and blog.job_id with client.get_job_status until status.value == 'completed'

curl -X POST "https://service.usemoss.dev/v1/manage" \
  -H "Content-Type: application/json" \
  -H "x-service-version: v1" \
  -H "x-project-key: moss_access_key_xxxxx" \
  -d '{
    "action": "createWebSource",
    "projectId": "project_123",
    "rootUrl": "https://docs.yoursite.com",
    "indexName": "support-kb",
    "refreshCadence": "weekly"
  }'

See Web Sources for the JavaScript SDK, Web Sources for Python, and Create Web Source for crawl limits, scheduling, and the full set of web source actions.

Local-first indexing (sessions)

createIndex / create_index builds an index through the cloud (then keeps it usable locally). When you need to index during a live interaction - adding transcript turns mid-call or building a per-user working set - use a session instead. A session indexes documents locally in real time with no cloud round trip, embedding each document on-device, and lets you optionally push the result to the cloud when you’re done.

import asyncio
from moss import DocumentInfo, MossClient

async def main():
    client = MossClient(project_id, project_key)

    # Create or resume a local index by name.
    session = await client.session(index_name="my-session-index")

    # Index locally in real time - embedded on-device, no network.
    await session.add_docs([
        DocumentInfo(id="turn-1", text="Customer confirmed the refund was received."),
    ])

    # Optionally push the session to the cloud when done.
    await session.push_index()

asyncio.run(main())

See Sessions for the full create-resume-query-push lifecycle.

Notes

createIndex / create_index will sync indexes to cloud (if enabled) while remaining usable locally
Supports multiple indexes per project; pick the model per index:
- moss-minilm: fast, lightweight (default)
- moss-mediumlm: higher accuracy, still efficient
- Use moss-minilm for speed-first, edge/offline use; use moss-mediumlm when you need higher recall/precision

Chunking tips

Aim for ~200-500 tokens per chunk
Overlap 10-20% to preserve context
Normalize whitespace and strip boilerplate

Getting Started

Capabilities

Use Cases

How it works

Pricing

Indexing Data

Data model

Examples

From files (PDF and DOCX)

From a website

Local-first indexing (sessions)

Notes

Chunking tips

​Data model

​Examples

​From files (PDF and DOCX)

​From a website

​Local-first indexing (sessions)

​Notes

​Chunking tips

Data model

Examples

From files (PDF and DOCX)

From a website

Local-first indexing (sessions)

Notes

Chunking tips