> 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

`telys_create_collection` **creates a Telys memory collection**. It is one of the five 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`](/mcp/tool-list-collections.md) until a [`telys_add`](/mcp/tool-add.md) writes to it (only `telys_add` calls `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](/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](/mcp/configuration-and-scoping.md) and [Exceptions & error codes](/reference/exceptions-and-errors.md).

## See also

* [Tool: telys\_add](/mcp/tool-add.md) — populate the new collection (also auto-creates when absent).
* [Tool: telys\_list\_collections](/mcp/tool-list-collections.md) — lists saved collections (a created collection shows up only after a `telys_add` persists it).
* [Create a collection](/working-with-data/create-a-collection.md) — the SDK equivalent, with dtype, filter columns, and tuners.
* [Collections](/understand-telys/collections.md) — what a collection is and how it persists.


---

# 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/mcp/tool-create-collection.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.