> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# CLI

Command-line interface reference.

The **`agent-memory`** CLI is the client for SurrealDB Agent Memory: `remember`, `recall`, `chat`, `documents`, and more.

> [!NOTE]
> The client binary is **`agent-memory`**. It was called `spectron` before the CLI rebrand; if you installed it earlier, `agent-memory upgrade` replaces it. The client environment variables (`SPECTRON_URL`, `SPECTRON_API_KEY` and `SPECTRON_CONTEXT_ID`) keep their names.

## Installing the CLI

Prebuilt `agent-memory` binaries for macOS, Linux, and Windows are published to `download.surrealdb.com` under a version path. On macOS and Linux the install script resolves the latest version, verifies the checksum, and installs to `/usr/local/bin` (or `~/.local/bin` when that is not writable):

```bash
curl -fsSL https://download.surrealdb.com/agent-memory/install.sh | sh
```

Set **`AGENT_MEMORY_INSTALL_DIR`** to install somewhere else. Once installed, the CLI updates itself in place, so you do not need to re-run the script:

```bash
agent-memory upgrade
```

### Manual download

To install by hand, resolve the current version from the pointer file, then download the archive for your platform:

```bash
VERSION=$(curl -fsSL https://download.surrealdb.com/agent-memory/latest.txt)
BASE="https://download.surrealdb.com/agent-memory/${VERSION}/agent-memory-${VERSION}"

# macOS (Apple Silicon)
curl -fsSL "${BASE}.darwin-arm64.tgz" | tar -xz && sudo mv agent-memory /usr/local/bin/

# macOS (Intel)
curl -fsSL "${BASE}.darwin-amd64.tgz" | tar -xz && sudo mv agent-memory /usr/local/bin/

# Linux (x86_64)
curl -fsSL "${BASE}.linux-amd64.tgz" | tar -xz && sudo mv agent-memory /usr/local/bin/

# Linux (arm64)
curl -fsSL "${BASE}.linux-arm64.tgz" | tar -xz && sudo mv agent-memory /usr/local/bin/
```

On **Windows**, download `agent-memory-<version>.windows-amd64.zip` from `https://download.surrealdb.com/agent-memory/<version>/` (use `latest.txt` for `<version>`), extract it, and put the folder containing `agent-memory.exe` on `PATH`. `agent-memory upgrade` works on Windows once a first install is on `PATH`.

### Verifying the download

Each archive has a `.sha256` sidecar next to it:

```bash
shasum -a 256 -c agent-memory-*.tgz.sha256   # macOS / Linux
```

The binaries are unsigned. Downloading with `curl` avoids the macOS Gatekeeper quarantine flag that a browser download adds; if you did download through a browser, clear it first with `xattr -d com.apple.quarantine ./agent-memory`.

## Connection flags (client)

Most `agent-memory` subcommands accept:

| Flag | Environment variable | Description |
| --- | --- | --- |
| `--url` / `-u` | `SPECTRON_URL` | Context host base URL (for example `https://<your-context-host>`), shown in the SurrealDB Studio **API keys** view |
| `--api-key` / `-a` | `SPECTRON_API_KEY` | Context API key |
| `--context-id` / `-c` | `SPECTRON_CONTEXT_ID` | Context id in `/api/v1/{context_id}/...` |

```bash
agent-memory login --url https://<your-context-host> \
  --api-key "$SPECTRON_API_KEY" \
  --context-id dev
```

Stores a named profile for later commands.

### Local config and secrets

`agent-memory login` and `agent-memory config set` write profiles to `~/.config/spectron/config.toml` with owner-only permissions (`0600` on Unix). **`config set`** prints the key name, never the value. To display a stored secret:

```bash
agent-memory config get api_key --reveal
```

Without **`--reveal`**, `api_key` is shown as `<hidden>`.

## Commands

### Unified verbs

| Command | REST equivalent |
| --- | --- |
| `agent-memory remember "…"` | `POST /api/v1/{ctx}/facts` |
| `agent-memory recall "…"` | `POST /api/v1/{ctx}/query` |
| `agent-memory context "…"` | `POST /api/v1/{ctx}/context` |
| `agent-memory chat [message]` | `POST /api/v1/{ctx}/chat` |
| `agent-memory reflect "…"` | `POST /api/v1/{ctx}/reflect` |
| `agent-memory forget "…"` | `POST /api/v1/{ctx}/forget` |

`forget` supports **`--dry-run`** to preview matches without expiring records.

`remember` flags: `--infer full|triples|preview|none`, `--from-file`, `--transcript`, `--scope org/acme/user/alice`, `--extract whole_conversation|per_message` (batch).

`recall` flags: `--limit`, `--mode hybrid|vector|bm25|graph`, `--include facts,passages`. Pass **`lens`** on the REST `/query` body - the CLI does not expose `--scope` on `recall` today.

**Unsupported CLI flags (rejected with a clear error):** `remember --confidence`, `--trust`, `--location`; `recall --min-trust`; `agent-memory lifecycle expire --older-than` (expiry thresholds are configured per Context, not per CLI invocation). Use the REST API where those controls exist.

### Documents

```bash
agent-memory documents upload ./manual.pdf --scope org/acme/team/eng --label team=eng
agent-memory ingest ./folder --scope org/acme/team/eng --label team=eng
agent-memory documents list
agent-memory recall "return policy" --include passages
```

`--scope` on upload narrows tagging to a path within the caller's `memory:write` region (same semantics as `remember --scope`). `--label` may be repeated for `key=value` tags stamped on the document and chunks. Omit `--scope` to use the full write region.

### Sessions, entities, traces

```bash
agent-memory sessions list
agent-memory entities show Person/alice
agent-memory traces show <trace_id>
```

### MCP server

The MCP server is served at `/mcp` on the same host as the REST API - no CLI step is needed to run it. `agent-memory mcp` prints ready-to-paste config snippets for Claude Desktop, Cursor and Claude Code, using the URL, key and Context id from your connection settings. Point your client at that endpoint, or run [`install-mcp`](https://github.com/supermemoryai/install-mcp). See the [MCP server install guide](/docs/agent-memory/integrations/mcp-server/install.md).

### Terminal workbench

| Command | Description |
| --- | --- |
| `agent-memory tui` | Four-pane workbench: input, entity tree, trace timeline, inspector (`Tab` cycles panes). `--session <id>` pins a session; `--replay <path>` plays a recorded jsonl without HTTP. |
| `agent-memory repl` | Interactive REPL: bare lines and **`/remember`** write facts (`infer: full`); `/recall`, `/chat`, `/inspect`, `/scope`, `/as-of`, `/upload`, `/forget`, `/record`; tab completion from prior responses. Colour is on when stdout is a terminal; pass **`--ascii`** for plain output (same flag as `agent-memory tui`). |

Scope in the REPL and TUI uses **slash paths** (`org/acme/user/alice`), matching the wire `ScopeSet`.

### REPL triple syntax

Interactive mode supports structured triple writes:

```text
/fact entity=Person/Alice attr=role val=CTO
```

Uses the same triple syntax as `agent-memory remember --triple` (`infer=triples`).

Run `agent-memory --help` for the full command tree.