GoodMem CLI

The GoodMem CLI is a command-line interface for interacting with the GoodMem memory management APIs. It provides comprehensive commands for managing spaces, memories, embedders, and more.

Installation

Download Binary

Visit https://get.goodmem.ai/tag/latest to download the CLI binary file.

The CLI stores connection details in named profiles. One profile is current and used by default, which makes it easy to switch between local, staging, and production deployments without rewriting flags in every command.

Environment Variables

GOODMEM_HOME_DIR: Override the CLI config directory
GOODMEM_PROFILE: Select a profile for a single invocation
GOODMEM_SERVER_URL: Override the server URL for a single invocation
GOODMEM_API_KEY: Override the API key for a single invocation

Configuration File

By default, the CLI stores profiles in ~/.goodmem/config.toml:

current_profile = "local"

[profiles.local]
server_url = "https://localhost:9090"
api_key = "gm_local_key_here"
install_type = "local-docker"

[profiles.local.local_docker]
path = "/home/user/.goodmem/installs/local-docker/local"

[profiles.production]
server_url = "https://api.goodmem.io:9090"
api_key = "gm_prod_key_here"

Authentication

# Use the current profile
goodmem profile current

# Create a profile for a remote deployment
goodmem profile create production \
  --url https://api.goodmem.io:9090 \
  --api-key "your-api-key"

# Switch between saved profiles
goodmem profile switch production

# Override the active profile for one command
GOODMEM_PROFILE=production goodmem space list

For commands that connect to a GoodMem server, values are resolved in this order:

CLI flags such as --server and --api-key
Environment variables such as GOODMEM_SERVER_URL and GOODMEM_API_KEY
The selected profile
Defaults (https://localhost:9090 and an empty API key)

If you install a local server with goodmem system install, the installer creates a local profile and makes it current. Use goodmem init when you need to initialize a server and save the returned API key into the current profile.

Global Flags

Flag	Description	Default
`--api-key`	API key for authentication	`$GOODMEM_API_KEY`
`--server`	GoodMem server address (gRPC API)	`https://localhost:9090`
`--help`	Show help information

Output Formats

Most commands support multiple output formats:

Table Format (Default)

goodmem space list --format table

JSON Format

goodmem space list --format json

Compact Format

goodmem space list --format compact

Error Handling

The CLI provides detailed error messages:

# Invalid UUID format
$ goodmem space get invalid-uuid
Error: Invalid UUID format: invalid-uuid

# Authentication error
$ goodmem space list
Error: Authentication failed. Please check your API key.

# Network error
$ goodmem --server http://invalid space list
Error: Failed to connect to server: connection refused

Examples

Complete Workflow

# 1) Install a local server, or create/select a profile for an existing one
goodmem system install

# 2) Confirm which profile is active
goodmem profile current

# 3) Create an embedder (skip if already set in the current shell)
if [[ -z "${EMBEDDER_ID:-}" ]]; then
  EMBEDDER_ID=$(goodmem embedder create \
    --display-name "My Embedder" \
    --provider-type OPENAI \
    --endpoint-url "https://api.openai.com/v1" \
    --model-identifier "text-embedding-3-small" \
    --dimensionality 1536 \
    --cred-api-key "$OPENAI_API_KEY" \
    | awk -F': *' '/^ID:/{print $2}')
fi

# 4) Create a space (skip if already set)
if [[ -z "${SPACE_ID:-}" ]]; then
  SPACE_ID=$(goodmem space create \
    --name "My Knowledge Base" \
    --embedder-id "$EMBEDDER_ID" \
    --embedder-weight 1.0 \
    | awk -F': *' '/^ID:/{print $2}')
fi

# 5) Add memories
goodmem memory create \
  --space-id "$SPACE_ID" \
  --content "Machine learning is a subset of artificial intelligence" \
  --metadata "topic=AI" \
  --metadata "source=definition"

goodmem memory create \
  --space-id "$SPACE_ID" \
  --content "Neural networks are inspired by biological neurons" \
  --metadata "topic=AI" \
  --metadata "source=definition"

sleep 2

# 6) Retrieve (search memories)
goodmem memory retrieve --space-id "$SPACE_ID" "What is machine learning?"

Batch Operations

# Create multiple memories from files
for file in docs/*.txt; do
  goodmem memory create --space-id "$SPACE_ID" \
    --file "$file" \
    --metadata "filename=$(basename $file)" \
    --metadata "source=docs" &
done
wait

# List and delete old memories
goodmem memory list --space-id "$SPACE_ID" --format json | \
  jq -r '.memories[] | select(.created_at < "2024-01-01") | .memory_id' | \
  xargs -I {} goodmem memory delete {}

CLI Reference