> 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/mcp/tool-add.md).

# telys\_add

Reference for the telys\_add MCP tool — add text documents to a Telys memory collection, auto-creating and saving it when the collection does not exist.

`telys_add` **adds text documents to a Telys memory collection (created if absent)**. It is one of the 19 tools on the Telys MCP server (`telys mcp`), called by name over JSON-RPC 2.0 (protocol version `2025-06-18`) on stdio.

Given a `collection` and a list of `texts`, the server embeds each document with its default embedder (`AlgentaMultigramEmbedder`), inserts the new rows, and persists the collection to the active store (`$TELYS_MEMORY_PATH`, default `~/.telys/memory`). If the collection does not exist, the server creates it first — partitioned by `scope` — then saves. This is the write path that feeds [`telys_search`](https://docs.telys.ai/mcp/tool-search.md).

## Input schema

Required: `collection`, `texts`.

| Field        | Type            | Required | Default | Description                                                                                                                    |
| ------------ | --------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `collection` | string          | yes      | —       | Target collection. Auto-created (with `partition_by="scope"`) and saved if it does not exist.                                  |
| `texts`      | array of string | yes      | —       | The documents to embed and store.                                                                                              |
| `ids`        | array of string | no       | auto    | External IDs, one per text. When omitted, the server assigns IDs.                                                              |
| `metadata`   | array of object | no       | —       | One metadata object per text. Include a `scope` key to route each record into a partition and to filter it later with `where`. |

{% hint style="info" %}
When you supply `ids`, `texts`, and `metadata`, the arrays align by position — element *i* of each describes the same record. Keep their lengths equal.
{% endhint %}

{% hint style="warning" %}
`telys_add` inserts **new rows only**; an ID that already exists raises a conflict. To replace existing records, use the `telys_upsert` or `telys_update` tools — or the SDK's `Collection.upsert_texts(...)` / `Collection.update_texts(...)`. See [Add & upsert records](https://docs.telys.ai/working-with-data/add-and-upsert.md) and [Update records](https://docs.telys.ai/working-with-data/update-records.md).
{% endhint %}

## Output schema

| Field        | Type    | Description                                                                |
| ------------ | ------- | -------------------------------------------------------------------------- |
| `added`      | integer | Number of documents inserted in this call.                                 |
| `collection` | string  | Echoes the collection that was written (and created, if it did not exist). |

## Example call

A `tools/call` request that seeds a fresh `notes` collection:

{% code title="request.json" %}

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "telys_add",
    "arguments": {
      "collection": "notes",
      "texts": [
        "Scope keys compose one partition string with scope_key().",
        "Partitions physically split a collection; the first element becomes the key."
      ],
      "ids": ["n-018", "n-019"],
      "metadata": [
        { "scope": "project:acme", "source": "design-doc" },
        { "scope": "project:acme", "source": "design-doc" }
      ]
    }
  }
}
```

{% endcode %}

The wrapped result — a JSON payload in one text content block, with `isError` for status:

{% code title="response.json" %}

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      { "type": "text", "text": "{\"added\": 2, \"collection\": \"notes\"}" }
    ],
    "isError": false
  }
}
```

{% endcode %}

Decoding the `text` field:

{% code title="payload.json" %}

```json
{ "added": 2, "collection": "notes" }
```

{% endcode %}

## In practice

Drive it from natural language; the client fills `texts` and `metadata`:

```
Remember in my notes collection, scope project:acme: "we standardized on scope_key() for partitions".
```

## Errors

Failures return the same envelope with `isError: true` and a single text block of the form `<Type>: <message>` — for example, a duplicate ID or mismatched array lengths. See [MCP configuration & scoping](https://docs.telys.ai/mcp/configuration-and-scoping.md) and [Exceptions & error codes](https://docs.telys.ai/reference/exceptions-and-errors.md).

## See also

* [Tool: telys\_search](https://docs.telys.ai/mcp/tool-search.md) — query the documents you added.
* [Tool: telys\_create\_collection](https://docs.telys.ai/mcp/tool-create-collection.md) — create a collection explicitly instead of on first add.
* [Add & upsert records](https://docs.telys.ai/working-with-data/add-and-upsert.md) — the SDK write paths, including upsert and update.
* [Partitions & scope keys](https://docs.telys.ai/understand-telys/partitions-scope-key.md) — how the `scope` metadata routes records.
