> 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

Reference for telys mem — an advanced, scriptable wrapper over a single local collection to create, add, search, list, and inspect it from the shell.

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