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://github.com/PAIR-Systems-Inc/goodmem/releases/tag/server-latest to download the CLI binary file.

Build from Source

git clone https://github.com/pairsys/goodmem.git
cd goodmem/cli
go build -o goodmem .
sudo mv goodmem /usr/local/bin/

Configuration

Environment Variables

GOODMEM_API_KEY: Your API key for authentication
GOODMEM_SERVER: Server address (optional)

Configuration File

The CLI stores configuration in ~/.goodmem/config.json:

{
  "server_address": "https://api.goodmem.com",
  "api_key": "your-api-key",
  "user_id": "user-uuid",
  "initialized": true,
  "initialized_at": "2024-01-01T00:00:00Z"
}

Authentication

# Set API key via environment
export GOODMEM_API_KEY="your-api-key"

# Or pass as flag
goodmem --api-key "your-api-key" space list

# Or configure during initialization
goodmem init

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) Initialize
goodmem init

# 2) 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 \
    --credentials "$OPENAI_API_KEY" \
    | awk -F': *' '/^ID:/{print $2}')
fi

# 3) 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

# 4) 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

# 5) 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