Moss Docs

---
name: moss-docs
description: "Documentation and capabilities reference for Moss semantic search."
---

# 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

- **Create Index**: Build a new semantic index with documents and embedding model selection
- **Load Index**: Load an existing index from persistent storage for querying
- **Get Index**: Retrieve metadata about a specific index (document count, model, etc.)
- **List Indexes**: Enumerate all indexes under a project
- **Delete Index**: Remove an index and all associated data

### Document Operations

- **Add Documents**: Insert or upsert documents into an existing index with optional metadata
- **Get Documents**: Retrieve stored documents by ID or fetch all documents
- **Delete Documents**: Remove specific documents from an index by their IDs

### Search & Retrieval

- **Semantic Search**: Query using natural language with vector similarity matching
- **Keyword Search**: Use BM25-based keyword matching for exact term lookups
- **Hybrid Search**: Blend semantic and keyword search with configurable alpha weighting (Python SDK)
- **Metadata Filtering**: Constrain results by document metadata (category, language, tags)
- **Top-K Results**: Return configurable number of best-matching documents with scores

### Embedding Models

- **moss-minilm**: Fast, lightweight model optimized for edge/offline use (default)
- **moss-mediumlm**: Higher accuracy model with reasonable performance for precision-critical use cases

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

- **LiveKit**: Context injection into voice agent pipeline with `inferedge-moss` SDK
- **Pipecat**: Pipeline processor via `pipecat-moss` package that auto-injects retrieval results

## Context

### Authentication

SDK requires project credentials:

- `MOSS_PROJECT_ID`: Project identifier from Moss Portal
- `MOSS_PROJECT_KEY`: Project access key from Moss Portal

```bash theme={null}
export MOSS_PROJECT_ID=your_project_id
export MOSS_PROJECT_KEY=your_project_key
```

REST API requires the following on every request:

- `x-project-key` header: project access key
- `x-service-version: v1` header: API version
- `projectId` field in the JSON body

```bash theme={null}
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

```typescript theme={null}
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

- Sub-10ms local queries (hardware-dependent)
- Instant index updates without reindexing entire corpus
- Sync is optional; compute stays on-device
- No infrastructure to manage

### Chunking Best Practices

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

### 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`:

```typescript theme={null}
// 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 theme={null}
# 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)