# uip agent memory

> Attach, list, and remove memory spaces and memory items on a low-code agent with `uip agent memory`.

`uip agent memory` manages the memory-space features attached to an agent: a memory space is a retrieval-augmented recall source (episodic or escalation memory) the agent can search against at runtime. `uip agent memory item` manages individual key/value items seeded into a configured memory space.

Local-only — no login required.

## Synopsis

```
uip agent memory add    <name> --memory-space <name> --folder-path <path> [--reference-key <key>] [--description <desc>] [--threshold <n>] [--result-count <n>] [--search-mode <hybrid|semantic>] [--field <name=weight>]... [--disable-dynamic-few-shot] [--path <dir>]
uip agent memory list                                                                                                                                                                                                                            [--path <dir>]
uip agent memory remove <name> [--folder-path <path>]                                                                                                                                                                                             [--path <dir>]

uip agent memory item add    <name> <key> <value> --memory-type <episodic|escalation> [--folder-path <path>] [--description <desc>] [--metadata <json>] [--path <dir>]
uip agent memory item list   <name> [--folder-path <path>]                                                                                                                                                                                        [--path <dir>]
uip agent memory item remove <name> <key> [--folder-path <path>]                                                                                                                                                                                  [--path <dir>]
```

All invocations honor the [global options](./global-options.md) (`--output`, `--output-filter`, `--log-level`, `--log-file`). Exit codes follow the [standard contract](./exit-codes.md).

## uip agent memory add

Attach a memory space to the agent.

### Arguments

- `<name>` *(required)* — Feature name to use in the agent.

### Options

| Flag | Default | Required | Purpose |
|---|---|---|---|
| `--memory-space <name>` | — | yes | Memory space name to attach. |
| `--folder-path <path>` | — | yes | Folder path where the memory space exists. |
| `--reference-key <key>` | — | | Memory space solution resource key. |
| `--description <desc>` | — | | Memory space description. |
| `--threshold <n>` | `0` | | Retrieval score threshold. |
| `--result-count <n>` | `3` | | Number of results to retrieve (positive integer). |
| `--search-mode <mode>` | `hybrid` | | `hybrid` or `semantic`. |
| `--field <name=weight>` | — | | Input field weight. Repeatable. |
| `--disable-dynamic-few-shot` | off | | Attach the memory space without enabling dynamic few-shot retrieval (enabled by default). |
| `--path <path>` | `.` | | Path to the agent project directory. |

### Example

```bash
uip agent memory add SupportRecall --memory-space customer-support-recall --folder-path Shared --path ./my-agent
```

### Data shape (--output json)

```json
{
  "Code": "AgentMemoryAdd",
  "Data": {
    "Status": "Memory space added",
    "Name": "SupportRecall",
    "MemorySpace": "customer-support-recall",
    "FolderPath": "Shared",
    "DynamicFewShotEnabled": true,
    "Id": "a1b2c3d4-0000-0000-0000-000000000070"
  }
}
```

## uip agent memory list

### Options

| Flag | Default | Purpose |
|---|---|---|
| `--path <path>` | `.` | Path to the agent project directory. |

### Example

```bash
uip agent memory list --path ./my-agent
```

### Data shape (--output json)

```json
{
  "Code": "AgentMemoryList",
  "Data": [
    { "Name": "SupportRecall", "MemorySpace": "customer-support-recall", "FolderPath": "Shared", "DynamicFewShotEnabled": true, "Id": "a1b2c3d4-0000-0000-0000-000000000070" }
  ]
}
```

## uip agent memory remove

### Arguments

- `<name>` *(required)* — Feature name, memory space name, or ID to remove.

### Options

| Flag | Purpose |
|---|---|
| `--folder-path <path>` | Folder path, when removing by memory space name. |
| `--path <path>` | Path to the agent project directory (default `.`). |

### Example

```bash
uip agent memory remove SupportRecall --path ./my-agent
```

### Data shape (--output json)

```json
{ "Code": "AgentMemoryRemove", "Data": { "Status": "Memory space removed", "Name": "SupportRecall" } }
```

A memory space not found by name/ID fails the command with a non-zero exit code.

## uip agent memory item add

Add a memory item to a configured memory space.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<name>` | yes | Feature name, memory space name, or ID. |
| `<key>` | yes | Memory item key. |
| `<value>` | yes | Memory item value. |

### Options

| Flag | Required | Purpose |
|---|---|---|
| `--folder-path <path>` | | Folder path, when selecting by memory space name. |
| `--memory-type <type>` | yes | `episodic` (0) or `escalation` (1) — numeric values `0`/`1` also accepted. |
| `--description <desc>` | | Memory item description. |
| `--metadata <json>` | | Memory item metadata as a JSON object. |
| `--path <path>` | | Path to the agent project directory (default `.`). |

### Examples

```bash
uip agent memory item add SupportRecall customer-tier gold --memory-type episodic --metadata '{"source":"seed"}' --path ./my-agent

uip agent memory item add SupportRecall escalation-case pending --memory-type escalation --path ./my-agent
```

### Data shape (--output json)

```json
{
  "Code": "AgentMemoryItemAdd",
  "Data": { "Status": "Memory item added", "Memory": "SupportRecall", "Key": "customer-tier", "MemoryType": 0, "Id": "a1b2c3d4-0000-0000-0000-000000000080" }
}
```

## uip agent memory item list

### Arguments

- `<name>` *(required)* — Feature name, memory space name, or ID.

### Options

| Flag | Purpose |
|---|---|
| `--folder-path <path>` | Folder path, when selecting by memory space name. |
| `--path <path>` | Path to the agent project directory (default `.`). |

### Example

```bash
uip agent memory item list SupportRecall --path ./my-agent
```

### Data shape (--output json)

```json
{
  "Code": "AgentMemoryItemList",
  "Data": [
    { "Key": "customer-tier", "Value": "gold", "MemoryType": 0, "Description": null, "Metadata": { "source": "seed" }, "Id": "a1b2c3d4-0000-0000-0000-000000000080" }
  ]
}
```

## uip agent memory item remove

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<name>` | yes | Feature name, memory space name, or ID. |
| `<key>` | yes | Memory item key or ID to remove. |

### Options

| Flag | Purpose |
|---|---|
| `--folder-path <path>` | Folder path, when selecting by memory space name. |
| `--path <path>` | Path to the agent project directory (default `.`). |

### Example

```bash
uip agent memory item remove SupportRecall customer-tier --path ./my-agent
```

### Data shape (--output json)

```json
{ "Code": "AgentMemoryItemRemove", "Data": { "Status": "Memory item removed", "Memory": "SupportRecall", "Key": "customer-tier" } }
```

## Related

- [`uip agent validate`](./uip-agent-validate.md) — re-run after editing memory configuration.
- [`uip agent refresh`](./uip-agent-refresh.md) — regenerates derived files after a memory space is added.

## See also

- [Global options](./global-options.md), [Exit codes](./exit-codes.md).