> 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

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`](/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` (`"1.0.0"`) 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](/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](/embeddings/bigram.md) — the compact lexical space.
* [Choosing an embedder](/embeddings/choosing-an-embedder.md) — the decision matrix.
* [MCP overview](/mcp/overview.md) — where this embedder is the default.
* [EmbeddingProfile & space compatibility](/embeddings/embedding-profile.md) — how space identity is computed.
* [Embedders API](/reference/embedders-api.md) — the full embedding surface.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.telys.ai/embeddings/multigram.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.