# Model Management

Manage embedding models for semantic search

## [Model Management](https://knowns.sh/docs/model#model-management)

The `knowns model` command provides full control over embedding models used for semantic search. Models are stored globally at `~/.knowns/models/` and shared across all projects.

## [Commands](https://knowns.sh/docs/model#commands)

### [Status](https://knowns.sh/docs/model#status)

```
knowns model           # Show current model status
knowns model status    # Detailed status with disk usage
```

### [List Models](https://knowns.sh/docs/model#list-models)

```
knowns model list      # List all available models
knowns model ls        # Alias
```

### [Download](https://knowns.sh/docs/model#download)

```
knowns model download <model-id>
knowns model dl <model-id>    # Alias
```

### [Set Model](https://knowns.sh/docs/model#set-model)

```
knowns model set <model-id>
knowns search --reindex        # Rebuild index after changing model
```

## [Built-in Models](https://knowns.sh/docs/model#built-in-models)

| Model ID | Quality | Dimensions | Size | Best For |
| --- | --- | --- | --- | --- |
| `gte-small` | Balanced | 384 | ~50MB | Most projects (recommended) |
| `all-MiniLM-L6-v2` | Fast | 384 | ~45MB | Large codebases |
| `gte-base` | Quality | 768 | ~110MB | High accuracy |
| `bge-small-en-v1.5` | Balanced | 384 | ~50MB | English text |
| `bge-base-en-v1.5` | Quality | 768 | ~110MB | English, high quality |
| `e5-small-v2` | Balanced | 384 | ~50MB | General use |

## [Custom Models](https://knowns.sh/docs/model#custom-models)

Add any HuggingFace `feature-extraction` ONNX model:

```
# Add a custom model
knowns model add Xenova/bge-large-en-v1.5 --dims 1024 --tokens 512

# Download and use it
knowns model download bge-large-en-v1.5
knowns model set bge-large-en-v1.5
knowns search --reindex
```

| Option | Description |
| --- | --- |
| `--dims <number>` | Embedding dimensions (default: 384) |
| `--tokens <number>` | Max input tokens (default: 512) |
| `--name <name>` | Display name for the model |

### [Remove Custom Model](https://knowns.sh/docs/model#remove-custom-model)

```
knowns model remove <model-id>
knowns model rm <model-id>       # Alias
knowns model rm <model-id> -f    # Also delete downloaded files
```

## [Workflow Examples](https://knowns.sh/docs/model#workflow-examples)

### [Setup semantic search](https://knowns.sh/docs/model#setup-semantic-search)

```
knowns init
# ? Enable semantic search? Yes
# ? Select model: gte-small (recommended)

knowns search "authentication"    # Works immediately
```

### [Upgrade to higher quality model](https://knowns.sh/docs/model#upgrade-to-higher-quality-model)

```
knowns model list
knowns model download gte-base
knowns model set gte-base
knowns search --reindex
```

### [Add multilingual support](https://knowns.sh/docs/model#add-multilingual-support)

```
knowns model add Xenova/multilingual-e5-small --dims 384 --name "E5 Multilingual"
knowns model download multilingual-e5-small
knowns model set multilingual-e5-small
knowns search --reindex
```