> 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-create-collection.md).

# telys\_create\_collection

Reference for the telys\_create\_collection MCP tool — create a named Telys memory collection, partitioned by scope, in the active memory store.

`telys_create_collection` **creates a Telys memory collection**. 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.

The server builds a new collection in the active store (`$TELYS_MEMORY_PATH`, default `~/.telys/memory`) and wires it to the default embedder (`AlgentaMultigramEmbedder`), but does **not** persist it to disk. The collection is built and cached only; it will not appear in [`telys_list_collections`](https://docs.telys.ai/mcp/tool-list-collections.md) until a mutating tool such as [`telys_add`](https://docs.telys.ai/mcp/tool-add.md) or `telys_upsert` writes to it (the mutating tools — `telys_add`, `telys_upsert`, `telys_update`, `telys_delete`, `telys_compact`, `telys_build_ivf`, `telys_build_lexical` — are the ones that call `save()`). Creating a collection explicitly is optional — `telys_add` auto-creates one on first write — but it lets you fix the name and partition key up front.

## Input schema

Required: `name`.

| Field          | Type   | Required | Default   | Description                                                  |
| -------------- | ------ | -------- | --------- | ------------------------------------------------------------ |
| `name`         | string | yes      | —         | Name of the collection to create.                            |
| `partition_by` | string | no       | `"scope"` | Name of the metadata key used as the physical partition key. |

{% hint style="info" %}
`partition_by` is a **single** key name, not a composite. For a compound partition (for example, tenant + project), compose one string value with `scope_key(...)` in the SDK and store it under a single key. See [Partitions & scope keys](https://docs.telys.ai/understand-telys/partitions-scope-key.md).
{% endhint %}

## Output schema

| Field          | Type    | Description                                                                                                                                                              |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `created`      | string  | Name of the collection that was created.                                                                                                                                 |
| `dim`          | integer | Vector dimension of the collection, taken from the default embedder. With the shipped multigram kernel this is `384`; the exact value is sourced from the native kernel. |
| `partition_by` | string  | The partition key name the collection was created with (defaults to `scope`).                                                                                            |

## Example call

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

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "telys_create_collection",
    "arguments": {
      "name": "notes",
      "partition_by": "scope"
    }
  }
}
```

{% endcode %}

The wrapped result:

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

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      { "type": "text", "text": "{\"created\": \"notes\", \"dim\": 384, \"partition_by\": \"scope\"}" }
    ],
    "isError": false
  }
}
```

{% endcode %}

Decoding the `text` field:

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

```json
{ "created": "notes", "dim": 384, "partition_by": "scope" }
```

{% endcode %}

## In practice

```
Create a Telys memory collection called notes.
```

## Errors

Failures return the same envelope with `isError: true` and a single text block of the form `<Type>: <message>`. 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\_add](https://docs.telys.ai/mcp/tool-add.md) — populate the new collection (also auto-creates when absent).
* [Tool: telys\_list\_collections](https://docs.telys.ai/mcp/tool-list-collections.md) — lists saved collections (a created collection shows up only after a mutating tool persists it).
* [Create a collection](https://docs.telys.ai/working-with-data/create-a-collection.md) — the SDK equivalent, with dtype, filter columns, and tuners.
* [Collections](https://docs.telys.ai/understand-telys/collections.md) — what a collection is and how it persists.
