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

API Actions

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

Workflows

Basic Semantic Search Workflow

• Initialize MossClient with project credentials
• Call createIndex() with documents and model options ({ modelId: 'moss-minilm' } in JS; "moss-minilm" string in Python)
• Call loadIndex() to prepare index for queries
• Call query() with search text and topK (JS) or QueryOptions(top_k=...) (Python)
• Process returned documents with scores

Hybrid Search Workflow (Python)

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

• Create and load index as above
• Call query() with a QueryOptions object specifying alpha
• alpha=1.0 = pure semantic, alpha=0.0 = pure keyword, alpha=0.6 = 60/40 blend
• Default is semantic-heavy for conversational use cases

Document Update Workflow

• Initialize client and ensure index exists
• Call addDocs() with new documents (upserts by default — existing IDs are updated)
• 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.

• Initialize MossClient and load index at agent startup
• In your application code, call query() on each user message to retrieve relevant context
• Inject search results into the LLM context before generating a response
• Respond with knowledge-grounded answer (no tool-calling latency)

Offline-First Search Workflow

• Create index with documents using local embedding model
• Load index from local storage
• Query runs entirely on-device with sub-10ms latency
• 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

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

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

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

For additional documentation and navigation, see: https://docs.moss.dev/llms.txt