> For the complete documentation index, see [llms.txt](https://docs.telys.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telys.ai/embeddings/multigram.md).

# Multigram embedder

Reference for AlgentaMultigramEmbedder — the richer on-device lexical embedder and the default used by the Telys MCP server.

A richer, on-device **lexical** embedder. It hashes unigrams, bigrams, and trigrams into three blocks, L2-normalizes each block independently, and concatenates them into one `float32` vector: `[unigram | bigram | trigram]`. Blockwise normalization keeps each n-gram order on its own scale, giving better recall over prose than the bigram-only space. It runs entirely inside the native kernel — no model download, no network — and is the **default embedder for the MCP server and `telys mem`**.

```python
from telys.embedding import AlgentaMultigramEmbedder

emb = AlgentaMultigramEmbedder(max_bytes=1 << 20)
```

## Signature

```python
AlgentaMultigramEmbedder(*, max_bytes: int = 1 << 20)
```

Keyword-only. Takes no `dimension`, `model_id`, or `space_id` argument — space identity comes from the profile, and the dimension is read from the native kernel at construction time.

| Parameter   | Type  | Default           | Meaning                                                                                           |
| ----------- | ----- | ----------------- | ------------------------------------------------------------------------------------------------- |
| `max_bytes` | `int` | `1 << 20` (1 MiB) | Upper bound on the UTF-8 bytes read per input string. Longer inputs are truncated before hashing. |

## Requirements

{% hint style="warning" %}
`AlgentaMultigramEmbedder` requires the **native kernel**. Constructing it without the kernel raises `ImportError`. Install and confirm the runtime with `telys runtime install` and `telys runtime verify`. Override the kernel library path with `$TELYS_KERNEL` (highest priority), then `$AME_KERNEL`.
{% endhint %}

## Interface

`AlgentaMultigramEmbedder` satisfies the `EmbeddingProvider` protocol:

| Member                   | Returns                   | Notes                                          |
| ------------------------ | ------------------------- | ---------------------------------------------- |
| `profile`                | `EmbeddingProfile`        | The frozen space descriptor (see below).       |
| `embed_documents(texts)` | `ndarray[N, D]` `float32` | Embeds documents for ingestion.                |
| `embed_queries(texts)`   | `ndarray[N, D]` `float32` | Embeds queries; defaults to `embed_documents`. |

```python
emb = AlgentaMultigramEmbedder()

emb.profile.dimension            # e.g. 384 — read from the native kernel
vecs = emb.embed_documents(["the release runbook", "go-live checklist"])
vecs.shape                       # (2, D)   float32; per-block L2-normalized
```

## Profile

The embedder exposes a frozen [`EmbeddingProfile`](https://docs.telys.ai/embeddings/embedding-profile.md) with fixed identity fields:

| Field           | Value                                                         |
| --------------- | ------------------------------------------------------------- |
| `provider`      | `"algenta"`                                                   |
| `model_id`      | `"multigram"`                                                 |
| `dimension`     | read from the native kernel (hint: `384`)                     |
| `dtype`         | `"float32"`                                                   |
| `normalization` | `"l2-blockwise"` (each n-gram block normalized independently) |
| `distance`      | `"ip"` (inner product)                                        |
| `pooling`       | `"multigram-hash"`                                            |

`model_version` (`"0.1.15"`) and `tokenizer_hash` (`"utf8-bytes"`) are fixed constants; `projection_version` and `created` default to empty strings. Only `dimension` is read from the native kernel build. Inspect the exact values for your install:

```python
emb.profile.as_dict()
emb.profile.space_id()           # "sha256:<16 hex>" identity of the space
```

## The MCP default

The Telys MCP server and the `telys mem` CLI use `AlgentaMultigramEmbedder` as their internal default (hint: 384-d). Collections created through `telys_add` / `telys_create_collection` or `telys mem create` therefore live in the multigram space, unless you build them in Python with a different embedder. See [MCP overview](https://docs.telys.ai/mcp/overview.md).

## Using it with a collection

Create the collection with the embedder's own dimension, never a hard-coded kernel hint:

```python
from telys import Telys
from telys.embedding import AlgentaMultigramEmbedder

engine = Telys("./memory")
emb = AlgentaMultigramEmbedder()

col = engine.create_collection(
    "notes",
    dim=emb.profile.dimension,
    partition_by="scope",
    embedder=emb,
)
col.add_texts(
    ["telys keeps memory on device", "the runtime is signed and verified"],
    ids=["n1", "n2"],
    metadata=[{"scope": "demo"}, {"scope": "demo"}],
)
col.save()

hits = col.search_text("on-device memory engine", top_k=5)
```

## See also

* [AlgentaBigramEmbedder](https://docs.telys.ai/embeddings/bigram.md) — the compact lexical space.
* [Choosing an embedder](https://docs.telys.ai/embeddings/choosing-an-embedder.md) — the decision matrix.
* [MCP overview](https://docs.telys.ai/mcp/overview.md) — where this embedder is the default.
* [EmbeddingProfile & space compatibility](https://docs.telys.ai/embeddings/embedding-profile.md) — how space identity is computed.
* [Embedders API](https://docs.telys.ai/reference/embedders-api.md) — the full embedding surface.
