CLI

The SurrealDB Agent Memory CLI is the memory component of the surreal command-line tool, run as surreal memory. It covers remember, recall, chat, documents and the other operations of the REST API.

Installing the CLI

Install the surreal launcher with the Agent Memory component:

curl -sSf https://install.surrealdb.com | sh -s -- --with memory

With surreal already installed, add the component on its own:

surreal install memory

The launcher installs, upgrades and pins every component, so the CLI has no upgrade command of its own:

surreal upgrade memory

Managing components covers versions and pinning. surreal memory --version prints the installed version.

Connection flags (client)

Most surreal memory subcommands accept:

A flag takes precedence over its environment variable, and the environment variable over a saved login.

surreal memory login --url https://<your-context-host> \
  --api-key "$SURREAL_MEMORY_API_KEY" \
  --context-id dev

login saves these values for later commands.

Local config and secrets

surreal memory login and surreal memory config set save to ~/.surrealdb/memory/config.toml with owner-only permissions (0600 on Unix). The folder follows SURREAL_CLI_HOME when the launcher uses another home, and SURREAL_MEMORY_CONFIG_DIR names another folder. config set prints the key name, never the value. To display a stored secret:

surreal memory config get api_key --reveal

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

Output and exit codes

The CLI uses the same output flags as the other surreal components. --json, --plain, --yes and --no-input can also be set with SURREAL_MEMORY_JSON, SURREAL_MEMORY_PLAIN, SURREAL_MEMORY_YES and SURREAL_MEMORY_NO_INPUT.

Results go to stdout and progress and confirmation messages to stderr, so surreal memory mcp > mcp.json writes a valid file. A failed request sets the exit code from its HTTP status:

Commands

Unified verbs

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; surreal memory lifecycle expire --older-than (expiry thresholds are configured per Context, not per CLI invocation). Use the REST API where those controls exist.

Documents

surreal memory documents upload ./manual.pdf --scope org/acme/team/eng --label team=eng
surreal memory ingest ./folder --scope org/acme/team/eng --label team=eng
surreal memory documents list
surreal 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

surreal memory sessions list
surreal memory entities show Person/alice
surreal 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. surreal 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. See the MCP server install guide.

Terminal workbench

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 surreal memory remember --triple (infer=triples).

Run surreal memory --help for the full command tree.