Moss Agent Skills

---

name: moss-docs

description: Documentation and capabilities reference for Moss semantic search.

Use for understanding Moss APIs, SDKs, and integration patterns.

metadata:

author: usemoss

version: "1.0"

docs-url: https://docs.moss.dev

mintlify-proj: moss

primary-credential: MOSS_PROJECT_KEY

required-env:

- name: MOSS_PROJECT_ID

description: Project identifier from the Moss Portal

- name: MOSS_PROJECT_KEY

description: Project access key from the Moss Portal (treat as a secret)

---

# Moss Agent Skills

Capabilities

Moss is the real-time semantic search runtime for conversational AI. It delivers sub-10ms lookups and instant index updates that run in the browser, on-device, or in the cloud - wherever your agent lives. Agents can create indexes, embed documents, perform semantic/hybrid searches, and manage document lifecycles without managing infrastructure. The platform handles embedding generation, index persistence, and optional cloud sync - allowing agents to focus on retrieval logic rather than infrastructure.

Skills

Index Management

Document Operations

Search & Retrieval

Embedding Models

SDK Methods

| JavaScript | Python | Description |

| ----------------- | ------------------ | ------------------------------ |

| `createIndex()` | `create_index()` | Create index with documents |

| `loadIndex()` | `load_index()` | Load index from storage |

| `getIndex()` | `get_index()` | Get index metadata |

| `listIndexes()` | `list_indexes()` | List all indexes |

| `deleteIndex()` | `delete_index()` | Delete an index |

| `addDocs()` | `add_docs()` | Add/upsert documents |

| `getDocs()` | `get_docs()` | Retrieve documents |

| `deleteDocs()` | `delete_docs()` | Remove documents |

| `query()` | `query()` | Semantic / hybrid search |

API Actions

All REST API operations go through `POST /v1/manage` (base URL: `https://service.usemoss.dev/v1`) with an `action` field:

| Action | Purpose | Extra required fields |

| -------------- | ------------------------------------------------ | ----------------------------------------------- |

| `initUpload` | Get a presigned URL to upload index data | `indexName`, `modelId`, `docCount`, `dimension` |

| `startBuild` | Trigger an index build after uploading data | `jobId` |

| `getJobStatus` | Check the status of an async build job | `jobId` |

| `getIndex` | Fetch metadata for a single index | `indexName` |

| `listIndexes` | Enumerate every index under the project | — |

| `deleteIndex` | Remove an index record and assets | `indexName` |

| `getIndexUrl` | Get download URLs for a built index | `indexName` |

| `addDocs` | Upsert documents into an existing index | `indexName`, `docs` |

| `deleteDocs` | Remove documents by ID | `indexName`, `docIds` |

| `getDocs` | Retrieve stored documents (without embeddings) | `indexName` |

Workflows

Basic Semantic Search Workflow

1. Initialize MossClient with project credentials

2. Call `createIndex()` with documents and model options (`{ modelId: 'moss-minilm' }` in JS; `"moss-minilm"` string in Python)

3. Call `loadIndex()` to prepare index for queries

4. Call `query()` with search text and `topK` (JS) or `QueryOptions(top_k=...)` (Python)

5. Process returned documents with scores

Hybrid Search Workflow (Python)

Hybrid blending via `alpha` is available in the Python SDK via `QueryOptions`:

1. Create and load index as above

2. Call `query()` with a `QueryOptions` object specifying `alpha`

3. `alpha=1.0` = pure semantic, `alpha=0.0` = pure keyword, `alpha=0.6` = 60/40 blend

4. Default is semantic-heavy for conversational use cases

Document Update Workflow

1. Initialize client and ensure index exists

2. Call `addDocs()` with new documents (upserts by default — existing IDs are updated)

3. Call `deleteDocs()` to remove outdated documents by ID

Voice Agent Context Injection Workflow

This is an opt-in integration pattern for voice agent pipelines — it is not automatic behavior of this skill.

1. Initialize MossClient and load index at agent startup

2. In your application code, call `query()` on each user message to retrieve relevant context

3. Inject search results into the LLM context before generating a response

4. Respond with knowledge-grounded answer (no tool-calling latency)

Offline-First Search Workflow

1. Create index with documents using local embedding model

2. Load index from local storage

3. Query runs entirely on-device with sub-10ms latency

4. Optionally sync to cloud for backup and sharing

Integration

Voice Agent Frameworks

Context

Authentication

SDK requires project credentials:

export MOSS_PROJECT_ID=your_project_id
export MOSS_PROJECT_KEY=your_project_key

REST API requires the following on every request:

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": "listIndexes", "projectId": "project_123"}'

Package Installation

| Language | Package | Install Command |

| --------------------- | ----------------- | ----------------------------- |

| JavaScript/TypeScript | `@inferedge/moss` | `npm install @inferedge/moss` |

| Python | `inferedge-moss` | `pip install inferedge-moss` |

| Pipecat Integration | `pipecat-moss` | `pip install pipecat-moss` |

Document Schema

interface DocumentInfo {
  id: string;        // Required: unique identifier
  text: string;      // Required: content to embed and search
  metadata?: object; // Optional: key-value pairs for filtering
}

Query Parameters

| Parameter | SDK | Type | Default | Description |

| ----------- | ----------- | ------ | -------- | -------------------------------------------- |

| `indexName` | JS + Python | string | — | Target index name (required) |

| `query` | JS + Python | string | — | Natural language search text (required) |

| `topK` | JS | number | 5 | Max results to return |

| `top_k` | Python | int | 5 | Max results to return |

| `alpha` | Python only | float | ~0.8 | Hybrid weighting: 0.0=keyword, 1.0=semantic |

| `filters` | JS + Python | object | — | Metadata constraints |

Model Selection

| Model | Use Case | Tradeoff |

| --------------- | ----------------------------------- | ----------------- |

| `moss-minilm` | Edge, offline, browser, speed-first | Fast, lightweight |

| `moss-mediumlm` | Precision-critical, higher accuracy | Slightly slower |

Performance Expectations

Chunking Best Practices

Common Errors

| Error | Cause | Fix |

| -------------------------- | ------------------- | -------------------------------------------- |

| Unauthorized | Missing credentials | Set `MOSS_PROJECT_ID` and `MOSS_PROJECT_KEY` |

| Index not found | Query before create | Call `createIndex()` first |

| Index not loaded | Query before load | Call `loadIndex()` before `query()` |

| Missing embeddings runtime | Invalid model | Use `moss-minilm` or `moss-mediumlm` |

Async Pattern

All SDK methods are async — always use `await`:

// JavaScript
import { MossClient, DocumentInfo } from '@inferedge/moss'
const client = new MossClient(process.env.MOSS_PROJECT_ID!, process.env.MOSS_PROJECT_KEY!)
await client.createIndex('faqs', docs, { modelId: 'moss-minilm' })
await client.loadIndex('faqs')
const results = await client.query('faqs', 'search text', { topK: 5 })

# Python
import os
from inferedge_moss import MossClient, QueryOptions
client = MossClient(os.getenv('MOSS_PROJECT_ID'), os.getenv('MOSS_PROJECT_KEY'))
await client.create_index('faqs', docs, 'moss-minilm')
await client.load_index('faqs')
results = await client.query('faqs', 'search text', QueryOptions(top_k=5, alpha=0.6))

---

> For additional documentation and navigation, see: [https://docs.moss.dev/llms.txt](https://docs.moss.dev/llms.txt)