> 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/cli/mem.md).

# telys mem

`telys mem` is a thin, advanced CLI over one local Telys collection — for smoke tests, shell pipelines, and quick inspection, not as the primary API. For real applications, use the [SDK](/reference/sdk-api-index.md). Every subcommand operates on a memory directory: `--path`, `$TELYS_MEMORY_PATH`, or the default `~/.telys/memory` (the same store the MCP server uses).

`mem` embeds and searches text, so it needs the signed runtime and native kernel installed. Run [`telys runtime status`](/cli/runtime.md) first.

## Synopsis

```
telys mem create --name NAME [--partition-by KEY] [--path PATH]
telys mem add    -c COLLECTION -t TEXT [-t TEXT ...] [--id ID ...] [--path PATH]
telys mem search -c COLLECTION -q QUERY [--top-k N] [--path PATH]
telys mem list   [--path PATH]
telys mem stats  -c COLLECTION [--path PATH]
```

## `telys mem create`

Create a collection in the memory directory.

| Flag             | Value  | Default    | Meaning                     |
| ---------------- | ------ | ---------- | --------------------------- |
| `--name`         | string | (required) | Collection name.            |
| `--partition-by` | key    | `scope`    | Physical partition key.     |
| `--path`         | dir    | memory dir | Where the collection lives. |

```bash
telys mem create --name notes
telys mem create --name notes --partition-by scope --path ./project-memory
```

{% hint style="info" %}
`--partition-by` sets a single physical partition key. Telys does not build composite keys from a list — compose one string key yourself with `scope_key(...)` in the SDK when you need multi-part scoping. See [Partitions & scope keys](/understand-telys/partitions-scope-key.md).
{% endhint %}

## `telys mem add`

Add one or more text documents to a collection.

| Flag                 | Value               | Default    | Meaning                                       |
| -------------------- | ------------------- | ---------- | --------------------------------------------- |
| `-c`, `--collection` | string              | (required) | Target collection.                            |
| `-t`, `--text`       | string (repeatable) | (required) | A document to add. Repeat `-t` for multiple.  |
| `--id`               | string (repeatable) | auto       | External id(s), aligned with the `-t` values. |
| `--path`             | dir                 | memory dir | Where the collection lives.                   |

```bash
telys mem add -c notes -t "Telys runs entirely on-device."
telys mem add -c notes \
  -t "Collections are directories on disk." \
  -t "Search returns external ids and scores." \
  --id fact-1 --id fact-2
```

Adding an id that already exists is an error — `add` inserts new rows only. Use the SDK's `upsert_texts` to replace existing rows.

## `telys mem search`

Search a collection by text and print the matching ids and scores.

| Flag                 | Value  | Default    | Meaning                               |
| -------------------- | ------ | ---------- | ------------------------------------- |
| `-c`, `--collection` | string | (required) | Collection to search.                 |
| `-q`, `--query`      | string | (required) | Query text (embedded, then searched). |
| `--top-k`            | int    | `5`        | Number of results to return.          |
| `--path`             | dir    | memory dir | Where the collection lives.           |

```bash
telys mem search -c notes -q "does Telys use the cloud?"
telys mem search -c notes -q "on-device" --top-k 10
```

## `telys mem list`

List the collections saved in the memory directory.

```bash
telys mem list
telys mem list --path ./project-memory
```

Only persisted collections (those with a `collection.json` on disk) are listed.

## `telys mem stats`

Print runtime statistics for a collection, including its name, key name, and external id count.

```bash
telys mem stats -c notes
```

## Exit codes

| Code | Meaning                                                             |
| ---- | ------------------------------------------------------------------- |
| `0`  | The action succeeded.                                               |
| `1`  | Runtime not available, or the collection/store could not be opened. |
| `2`  | Usage error (a missing required flag such as `-c` or `-q`).         |

## See also

* [SDK API index](/reference/sdk-api-index.md) — the full programmatic surface `mem` wraps.
* [Add & upsert records](/working-with-data/add-and-upsert.md) and [Search by text](/working-with-data/search-by-text.md) — the same operations in Python.
* [Partitions & scope keys](/understand-telys/partitions-scope-key.md) — how `--partition-by` works.
* [telys mcp](/cli/mcp.md) — the assistant-facing server over the same memory store.


---

# 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/cli/mem.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.