# kindgi memory

> Memory: the facts agents remember, by type and scope, and erasing a person's words

## `kindgi memory`

**Synopsis**

```sh signature
kindgi memory <command>
```

Memory: the facts agents remember, by type and scope, and erasing a person's words.

**Commands**

| Command                                                                                                    | Description                                                                                |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| [`kindgi memory facts`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-facts)       | Memory facts: list, get, write, supersede, delete, verify, revisions.                      |
| [`kindgi memory erasures`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-erasures) | Erasing a person's words: create, get, list, resume, export, replay (a tenant admin only). |

**See also**

- [Back up and restore the runtime's database](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/back-up-and-restore.md)
- [Erase a person's data](https://docs.kindgi.com/v0.1.10/guides/agents/erase-a-persons-data.md)
- [Give an agent memory](https://docs.kindgi.com/v0.1.10/guides/agents/give-an-agent-memory.md)

### `kindgi memory facts`

**Synopsis**

```sh signature
kindgi memory facts <command>
```

Memory facts: list, get, write, supersede, delete, verify, revisions.

**Commands**

| Command                                                                                                                  | Description                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| [`kindgi memory facts list`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-facts-list)           | List the memory facts you may see, the current revision of each.                                       |
| [`kindgi memory facts get`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-facts-get)             | A memory fact by id: its current revision, one revision, or as it stood then.                          |
| [`kindgi memory facts revisions`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-facts-revisions) | A memory fact's revisions, newest first: who changed or deleted it, when and why.                      |
| [`kindgi memory facts write`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-facts-write)         | Write a memory fact.                                                                                   |
| [`kindgi memory facts supersede`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-facts-supersede) | Change a memory fact's content: writes its next revision (same id).                                    |
| [`kindgi memory facts delete`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-facts-delete)       | Delete a memory fact: agents and reads no longer see it; its history stays until retention removes it. |
| [`kindgi memory facts verify`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-facts-verify)       | Mark a memory fact verified: you checked it.                                                           |
| [`kindgi memory facts retrieve`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-facts-retrieve)   | Search the memory facts you may see: newest first, by keyword, by meaning, or both fused by rank.      |

**See also**

- [Back up and restore the runtime's database](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/back-up-and-restore.md)
- [Erase a person's data](https://docs.kindgi.com/v0.1.10/guides/agents/erase-a-persons-data.md)
- [Give an agent memory](https://docs.kindgi.com/v0.1.10/guides/agents/give-an-agent-memory.md)
- [`kindgi memory`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory)

#### `kindgi memory facts list`

**Synopsis**

```sh signature
kindgi memory facts list [--type=<type>] [--scope=<json-or-@file>] [--as-of=<time>] [--limit=<n>] [--cursor=<c>]
```

List the memory facts you may see, the current revision of each.

**Options**

| Option             | Default              | Description                                                                                                                                                             |
| ------------------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--as-of <value>`  | none                 | Memory as it stood at this time (an ISO 8601 time with a zone, or a date: its start, UTC), deleted and superseded facts included.                                       |
| `--cursor <value>` | none                 | Resume after this cursor, from the previous page's `nextCursor`.                                                                                                        |
| `--limit <value>`  | `25` (at most `100`) | The most facts to return (default 25, at most 100).                                                                                                                     |
| `--scope <value>`  | none                 | Only the facts in this scope, as inline JSON or `@<file>`: any of `userId`, `orgId`, `projectId`, `threadId`, `sessionId`, `participantId`; every key given must match. |
| `--type <value>`   | none                 | Only the facts of this type.                                                                                                                                            |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

From [Give an agent memory](https://docs.kindgi.com/v0.1.10/guides/agents/give-an-agent-memory.md):

```sh
pnpm exec kindgi memory facts list --type=acme.note
```

**See also**

- [Give an agent memory](https://docs.kindgi.com/v0.1.10/guides/agents/give-an-agent-memory.md)
- [`kindgi memory facts`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-facts)

#### `kindgi memory facts get`

**Synopsis**

```sh signature
kindgi memory facts get <fact-id> [--revision=<n>] [--as-of=<time>]
```

A memory fact by id: its current revision, one revision, or as it stood then.

**Options**

| Option               | Default | Description                                                                                                                       |
| -------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `--as-of <value>`    | none    | Memory as it stood at this time (an ISO 8601 time with a zone, or a date: its start, UTC), deleted and superseded facts included. |
| `--revision <value>` | none    | This revision (its `version`), current or not.                                                                                    |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

From [Give an agent memory](https://docs.kindgi.com/v0.1.10/guides/agents/give-an-agent-memory.md):

```sh
pnpm exec kindgi memory facts get <fact-id>
pnpm exec kindgi memory facts get <fact-id> --as-of=2026-10-01T00:00:00Z
```

**See also**

- [Give an agent memory](https://docs.kindgi.com/v0.1.10/guides/agents/give-an-agent-memory.md)
- [`kindgi memory facts`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-facts)

#### `kindgi memory facts revisions`

**Synopsis**

```sh signature
kindgi memory facts revisions <fact-id>
```

A memory fact's revisions, newest first: who changed or deleted it, when and why.

**Options**

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

From [Give an agent memory](https://docs.kindgi.com/v0.1.10/guides/agents/give-an-agent-memory.md):

```sh
pnpm exec kindgi memory facts revisions <fact-id>
```

**See also**

- [Give an agent memory](https://docs.kindgi.com/v0.1.10/guides/agents/give-an-agent-memory.md)
- [`kindgi memory facts`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-facts)

#### `kindgi memory facts write`

**Synopsis**

```sh signature
kindgi memory facts write --input=<json-or-@file>
```

Write a memory fact. Prints it, with the id and version the server gave it.

**Options**

| Option            | Default  | Description                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--input <value>` | required | The fact as inline JSON or `@<file>`: its `type` and `content`, and optionally `scope` (default: your tenant; narrow it with `userId`, `orgId`, `projectId`, `threadId`, `sessionId`, or an app's end user with `projectId` and `participantId`), `retention` (`keepDays`, `keepUntil`, `legalHold`), `subjects` (whom it is about: `[{"kind":"participant","id":"…"}]`) and `validFrom`/`validUntil`/`observedAt`. Required. |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

From [Give an agent memory](https://docs.kindgi.com/v0.1.10/guides/agents/give-an-agent-memory.md):

```sh
pnpm exec kindgi memory facts write --input=@fact.json
```

**See also**

- [Give an agent memory](https://docs.kindgi.com/v0.1.10/guides/agents/give-an-agent-memory.md)
- [`kindgi memory facts`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-facts)

#### `kindgi memory facts supersede`

**Synopsis**

```sh signature
kindgi memory facts supersede <fact-id> --input=<json-or-@file> [--expect-version=<n>]
```

Change a memory fact's content: writes its next revision (same id). Prints the new revision.

**Options**

| Option                     | Default  | Description                                                                                                                                                                                                                |
| -------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--expect-version <value>` | none     | Only if the fact is still at this revision (its `version`); if someone changed it first, nothing changes and the command fails with `fact-changed`.                                                                        |
| `--input <value>`          | required | The next revision as inline JSON or `@<file>`: its `content`, and optionally `retention`, `subjects` and `validFrom`/`validUntil`/`observedAt` (absent ones keep their current values). Its type and scope stay. Required. |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

From [Give an agent memory](https://docs.kindgi.com/v0.1.10/guides/agents/give-an-agent-memory.md):

```sh
pnpm exec kindgi memory facts supersede <fact-id> --input='{"content":"Prefers phone"}' --expect-version=1
```

**See also**

- [Give an agent memory](https://docs.kindgi.com/v0.1.10/guides/agents/give-an-agent-memory.md)
- [`kindgi memory facts`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-facts)

#### `kindgi memory facts delete`

**Synopsis**

```sh signature
kindgi memory facts delete <fact-id> [--expect-version=<n>]
```

Delete a memory fact: agents and reads no longer see it; its history stays until retention removes it. Prints the closed revision.

**Options**

| Option                     | Default | Description                                                                                                                                         |
| -------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--expect-version <value>` | none    | Only if the fact is still at this revision (its `version`); if someone changed it first, nothing changes and the command fails with `fact-changed`. |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

From [Give an agent memory](https://docs.kindgi.com/v0.1.10/guides/agents/give-an-agent-memory.md):

```sh
pnpm exec kindgi memory facts delete <fact-id>
```

**See also**

- [Give an agent memory](https://docs.kindgi.com/v0.1.10/guides/agents/give-an-agent-memory.md)
- [`kindgi memory facts`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-facts)

#### `kindgi memory facts verify`

**Synopsis**

```sh signature
kindgi memory facts verify <fact-id> [--expect-version=<n>]
```

Mark a memory fact verified: you checked it. Prints the new revision (`trust: verified`).

**Options**

| Option                     | Default | Description                                                                                                                                         |
| -------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--expect-version <value>` | none    | Only if the fact is still at this revision (its `version`); if someone changed it first, nothing changes and the command fails with `fact-changed`. |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

From [Give an agent memory](https://docs.kindgi.com/v0.1.10/guides/agents/give-an-agent-memory.md):

```sh
pnpm exec kindgi memory facts verify <fact-id>
```

**See also**

- [Give an agent memory](https://docs.kindgi.com/v0.1.10/guides/agents/give-an-agent-memory.md)
- [`kindgi memory facts`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-facts)

#### `kindgi memory facts retrieve`

**Synopsis**

```sh signature
kindgi memory facts retrieve --query=<json-or-@file>
```

Search the memory facts you may see: newest first, by keyword, by meaning, or both fused by rank.

**Options**

| Option            | Default  | Description                                                                                                                                                                                                                                                              |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--query <value>` | required | The retrieval as inline JSON or `@<file>`: a `mode` (`list`, `keyword`, `semantic` or `both`), and optionally `query` (required for a search), `type`, `scope` and `limit`. `semantic` and `both` need embeddings on the runtime (`KINDGI_MEMORY_EMBEDDINGS`). Required. |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

Search facts by keyword.

```sh
kindgi memory facts retrieve --query='{"mode":"keyword","query":"delivery window","limit":5}'
```

Run a retrieval whose query is kept in a file.

```sh
kindgi memory facts retrieve --query=@query.json
```

**See also**

- [Back up and restore the runtime's database](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/back-up-and-restore.md)
- [Erase a person's data](https://docs.kindgi.com/v0.1.10/guides/agents/erase-a-persons-data.md)
- [Give an agent memory](https://docs.kindgi.com/v0.1.10/guides/agents/give-an-agent-memory.md)
- [`kindgi memory facts`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-facts)

### `kindgi memory erasures`

**Synopsis**

```sh signature
kindgi memory erasures <command>
```

Erasing a person's words: create, get, list, resume, export, replay (a tenant admin only).

**Commands**

| Command                                                                                                                  | Description                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| [`kindgi memory erasures create`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-erasures-create) | Erase a person's words: their facts, conversations, the runs that served them, and what those left in provenance.        |
| [`kindgi memory erasures get`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-erasures-get)       | An erasure: its status, phase, and what each store cleared.                                                              |
| [`kindgi memory erasures list`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-erasures-list)     | Erasures, newest first.                                                                                                  |
| [`kindgi memory erasures resume`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-erasures-resume) | Try an erasure again now; --force stops one waiting on a run in a flow that serves other people (that run is cancelled). |
| [`kindgi memory erasures export`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-erasures-export) | The erasure ledger, content-free, to keep off-box: restoring a backup rolls it back too, and `replay` takes it.          |
| [`kindgi memory erasures replay`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-erasures-replay) | After restoring a backup: put the exported ledger back, and erase again whoever the tenant holds again.                  |

**See also**

- [Back up and restore the runtime's database](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/back-up-and-restore.md)
- [Erase a person's data](https://docs.kindgi.com/v0.1.10/guides/agents/erase-a-persons-data.md)
- [Give an agent memory](https://docs.kindgi.com/v0.1.10/guides/agents/give-an-agent-memory.md)
- [`kindgi memory`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory)

#### `kindgi memory erasures create`

**Synopsis**

```sh signature
kindgi memory erasures create (--participant=<id> | --external=<id> | --fact=<fact-id> | --conversation=<conversation-id>)
```

Erase a person's words: their facts, conversations, the runs that served them, and what those left in provenance. Runs in the background; a tenant admin only.

**Options**

| Option                   | Default | Description                                      |
| ------------------------ | ------- | ------------------------------------------------ |
| `--conversation <value>` | none    | One conversation.                                |
| `--external <value>`     | none    | A person facts name as an `external` subject.    |
| `--fact <value>`         | none    | One fact, every revision.                        |
| `--participant <value>`  | none    | An app's end user (the `participantId` it gave). |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

From [Erase a person's data](https://docs.kindgi.com/v0.1.10/guides/agents/erase-a-persons-data.md):

```sh
pnpm exec kindgi memory erasures create --participant=end-7
```

**See also**

- [Erase a person's data](https://docs.kindgi.com/v0.1.10/guides/agents/erase-a-persons-data.md)
- [`kindgi memory erasures`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-erasures)

#### `kindgi memory erasures get`

**Synopsis**

```sh signature
kindgi memory erasures get <erasure-id>
```

An erasure: its status, phase, and what each store cleared.

**Options**

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

From [Erase a person's data](https://docs.kindgi.com/v0.1.10/guides/agents/erase-a-persons-data.md):

```sh
pnpm exec kindgi memory erasures get <erasure-id>
```

**See also**

- [Erase a person's data](https://docs.kindgi.com/v0.1.10/guides/agents/erase-a-persons-data.md)
- [`kindgi memory erasures`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-erasures)

#### `kindgi memory erasures list`

**Synopsis**

```sh signature
kindgi memory erasures list [--limit=<n>] [--cursor=<c>]
```

Erasures, newest first.

**Options**

| Option             | Default              | Description                                                  |
| ------------------ | -------------------- | ------------------------------------------------------------ |
| `--cursor <value>` | none                 | Resume after this cursor (the previous page's `nextCursor`). |
| `--limit <value>`  | `25` (at most `100`) | The most to return (default 25, at most 100).                |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

From [Erase a person's data](https://docs.kindgi.com/v0.1.10/guides/agents/erase-a-persons-data.md):

```sh
pnpm exec kindgi memory erasures list
```

**See also**

- [Erase a person's data](https://docs.kindgi.com/v0.1.10/guides/agents/erase-a-persons-data.md)
- [`kindgi memory erasures`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-erasures)

#### `kindgi memory erasures resume`

**Synopsis**

```sh signature
kindgi memory erasures resume <erasure-id> [--force]
```

Try an erasure again now; --force stops one waiting on a run in a flow that serves other people (that run is cancelled).

**Options**

| Option    | Default | Description                                                                                             |
| --------- | ------- | ------------------------------------------------------------------------------------------------------- |
| `--force` | off     | Don't wait for the shared flow's run: cancel it and go on (it would otherwise wait until its deadline). |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

From [Erase a person's data](https://docs.kindgi.com/v0.1.10/guides/agents/erase-a-persons-data.md):

```sh
pnpm exec kindgi memory erasures resume <erasure-id>           # try again now
pnpm exec kindgi memory erasures resume <erasure-id> --force   # stop waiting: cancel that run and go on
```

**See also**

- [Erase a person's data](https://docs.kindgi.com/v0.1.10/guides/agents/erase-a-persons-data.md)
- [`kindgi memory erasures`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-erasures)

#### `kindgi memory erasures export`

**Synopsis**

```sh signature
kindgi memory erasures export [--out=<file>]
```

The erasure ledger, content-free, to keep off-box: restoring a backup rolls it back too, and `replay` takes it.

**Options**

| Option          | Default         | Description                              |
| --------------- | --------------- | ---------------------------------------- |
| `--out <value>` | standard output | Write it to this file (else, to stdout). |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

From [Back up and restore the runtime's database](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/back-up-and-restore.md):

```sh
npx --yes @kindgi/cli@0.1 memory erasures export --out=erasures-$(date +%F).json
```

From [Erase a person's data](https://docs.kindgi.com/v0.1.10/guides/agents/erase-a-persons-data.md):

```sh
pnpm exec kindgi memory erasures export --out=erasure-ledger.json
```

**See also**

- [Back up and restore the runtime's database](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/back-up-and-restore.md)
- [Erase a person's data](https://docs.kindgi.com/v0.1.10/guides/agents/erase-a-persons-data.md)
- [`kindgi memory erasures`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-erasures)

#### `kindgi memory erasures replay`

**Synopsis**

```sh signature
kindgi memory erasures replay <export-file>
```

After restoring a backup: put the exported ledger back, and erase again whoever the tenant holds again.

**Options**

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags).

**Examples**

From [Back up and restore the runtime's database](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/back-up-and-restore.md):

```sh
npx --yes @kindgi/cli@0.1 memory erasures replay erasures-<date>.json
```

From [Erase a person's data](https://docs.kindgi.com/v0.1.10/guides/agents/erase-a-persons-data.md):

```sh
pnpm exec kindgi memory erasures replay erasure-ledger.json
```

**See also**

- [Back up and restore the runtime's database](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/back-up-and-restore.md)
- [Erase a person's data](https://docs.kindgi.com/v0.1.10/guides/agents/erase-a-persons-data.md)
- [`kindgi memory erasures`](https://docs.kindgi.com/v0.1.10/reference/cli/memory.md#kindgi-memory-erasures)