CLI | Agent Memory reference

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

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. Every SPECTRON_* environment variable keeps its name. See Configuration.

Installing the CLI

Prebuilt spectron 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):

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

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

agent-memory upgrade

Manual download

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

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 spectron /usr/local/bin/

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

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

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

On Windows, download spectron-<version>.windows-amd64.zip from https://download.surrealdb.com/agent-memory/<version>/ (use latest.txt for <version>), extract it, and put the folder containing spectron.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:

shasum -a 256 -c spectron-*.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 ./spectron.

Connection flags (client)

Most spectron subcommands accept:

Flag	Environment variable	Description
`--url` / `-u`	`SPECTRON_URL`	Server base URL (for example `http://localhost:9090`)
`--api-key` / `-a`	`SPECTRON_API_KEY`	Context API key
`--context-id` / `-c`	`SPECTRON_CONTEXT_ID`	Context id in `/api/v1/{context_id}/...`

agent-memory login --url http://localhost:9090 \
  --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:

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 scope 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 REST or management API where those controls exist.

Documents

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

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 and port as the REST API - no CLI step is needed. Point your client at that endpoint, or run install-mcp. See the MCP server install guide.

Provisioning principals

Create principals with the management API key, not the data-plane Context key. The client reaches the management API over REST at SPECTRON_MANAGEMENT_URL:

export SPECTRON_MANAGEMENT_URL=http://127.0.0.1:9090
export SPECTRON_MANAGEMENT_API_KEY=sp-…

# reads SPECTRON_MANAGEMENT_* + SPECTRON_CONTEXT_ID from env
agent-memory principals create "Planner bot" --kind agent -c demo \
  --grant memory:read=team/eng --grant memory:write=team/eng

Prints the server-minted principal id. Mint an agent key for that principal through the management API.

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:

/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.