memories-cli

JSON-first Python CLI for the memories.ai v1, v2, and raw HTTP workflows.

Install

Three install lanes are supported.

Lane 1: Developer/Internal Install From Source

From the repo root, create and activate a virtualenv first. This avoids macOS/Homebrew python3 environments where global pip install is externally managed:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e ".[dev]"

This is the supported lane for contributors and internal development. The editable install provides the memories entrypoint plus developer tools such as pytest.

Lane 2: External Install With Curl

The curl installer is the primary external install path. It downloads the matching GitHub Release archive for the platform, verifies it against sha256sums.txt, unpacks in a temporary directory, and installs memories to ~/.local/bin by default.

The installer requires published memories-cli-v* GitHub releases and will fail clearly if no release has been published yet.

On macOS, public release binaries may be unsigned when Apple signing credentials are not configured for that tagged release. In that case the first launch may require manual approval in Gatekeeper.

Standard public tags currently publish darwin-arm64 and linux-x64 archives. Intel macOS users should use the source install lane for now.

These one-line commands fetch the installer into a temporary file first so a failed curl exits clearly before sh runs.

Examples:

(tmp="$(mktemp)" && curl -fsSL https://raw.githubusercontent.com/Memories-ai-labs/memories-cli/main/install.sh -o "$tmp" && sh "$tmp"; status=$?; rm -f "$tmp"; exit $status)
(tmp="$(mktemp)" && curl -fsSL https://raw.githubusercontent.com/Memories-ai-labs/memories-cli/main/install.sh -o "$tmp" && sh "$tmp" --version 0.1.3; status=$?; rm -f "$tmp"; exit $status)
(tmp="$(mktemp)" && curl -fsSL https://raw.githubusercontent.com/Memories-ai-labs/memories-cli/main/install.sh -o "$tmp" && sh "$tmp" --bin-dir ~/.local/bin --force; status=$?; rm -f "$tmp"; exit $status)

Lane 3: Manual Install From GitHub Releases

Use this manual fallback lane if you do not want the curl installer and prefer GitHub Releases.

Archive name patterns:

• memories-v<version>-darwin-arm64.tar.gz
• memories-v<version>-linux-x64.tar.gz

Runtime contract:

• darwin-arm64: macOS 13+ on Apple Silicon
• linux-x64: x86_64 Linux with glibc >= 2.35, validated on Ubuntu 22.04

Public macOS release artifacts may be unsigned when Apple signing credentials are not configured. In that case macOS may require manual approval in Gatekeeper before first run.

Intel macOS public archives are temporarily unavailable on standard public tags because GitHub-hosted Intel macOS runner availability has been unreliable. Use the source install lane if you need to dogfood on Intel macOS.

Quick start:

1. Go to GitHub Releases and download the archive for your platform.
2. Download sha256sums.txt and verify the archive against it.
3. Unpack the archive and change into the unpacked directory.
4. Set MEMORIES_API_KEY in your shell.
5. Run ./memories --help.

Moving the binary onto PATH is optional. Direct execution from the unpacked directory is the primary supported first-run flow.

Test

For source installs, with the virtualenv still active, run:

python3 -m pytest tests -q

Configuration

• MEMORIES_API_KEY: required
• MEMORIES_V1_BASE_URL: optional override, defaults to https://api.memories.ai
• MEMORIES_V2_BASE_URL: optional override, defaults to https://mavi-backend.memories.ai/serve/api/v2
• MEMORIES_TIMEOUT_MS: optional override, defaults to 30000

The CLI also reads ~/.openclaw/memories/config.json when present.

Help

memories --help
memories v1 --help
memories v2 --help
memories raw request --help

Command surface

v1 (Visual Search, https://api.memories.ai/serve/api/v1)

Indexing — Private library: upload-file, upload-url, upload-image, upload-platform-url, upload-creator, upload-hashtag

Indexing — Public library: upload-platform-url-public, upload-creator-public, upload-hashtag-public

Library inspection: list-videos, list-unique-ids, get-metadata, videos-by-task-id, video-transcription, audio-transcription, video-caption

Search — Private: search, search-similar-images, search-clips-by-image, search-audio-transcripts

Search — Public: search-public, search-public-similar-images, search-public-audio-transcripts

Download / delete: download, download-by-bucket-blob, delete-videos

v2 (Visual Intelligence, https://mavi-backend.memories.ai/serve/api/v2)

Assets: asset upload | upload-signed-url | upload-by-signed-url | download | download-by-bucket-blob | delete | metadata | extract-frames

Transcription: transcribe {sync-audio,sync-speaker,async-audio,async-summary,async-video,async-speaker,async-multi-speaker} plus speech-to-text (provider-routed: elevenlabs / whisper / etc.)

Captions: caption {image,video,video-frame-description}, summary video

Embeddings: embeddings {image,text,video}

Multimodal chat: model {gemini,gpt,nova,qwen} {image,video}

Social metadata: social {metadata,transcript,mai-transcript} — supports youtube, tiktok, instagram, twitter; --channel accepts apify / rapid / memories.ai

Social scraping: scraper {tiktok,youtube} {video-detail,comments,comment-replies}

Streams: stream {audio,video-moderation,video-understanding} {start,stop}

Examples

V1 upload from URL:

memories v1 upload-url \
  --url https://example.com/demo.mp4 \
  --callback https://example.com/callback \
  --unique-id upload-123

V1 search (private library):

memories v1 search \
  --search-param "red sports car" \
  --search-type BY_CLIP \
  --top-k 20

V1 search by image inside a single video:

memories v1 search-clips-by-image \
  --file query.png \
  --video-no VI568102998803353600 \
  --prompt "the moment the goal is scored"

V1 download:

memories v1 download \
  --video-no VI568102998803353600 \
  --output ./demo.mp4

V2 transcription (sync):

memories v2 transcribe sync-audio --asset-id asset-123

V2 social metadata across platforms:

memories v2 social metadata \
  --platform tiktok \
  --video-url https://www.tiktok.com/@x/video/1 \
  --channel apify

V2 scraper:

memories v2 scraper youtube comments \
  --video-id dQw4w9WgXcQ

V2 embedding:

memories v2 embeddings text --text "the moment the goal is scored"

V2 multimodal chat (Gemini on a video asset):

memories v2 model gemini video \
  --asset-id re_657929111888723968 \
  --prompt "Summarize the key moments"

V2 live stream control:

memories v2 stream video-understanding start \
  --stream-url rtmp://example/live \
  --callback https://example.com/webhook

memories v2 stream video-understanding stop --task-id T1

Raw request:

memories raw request \
  --family v1 \
  --method GET \
  --path /serve/api/v1/get_video_transcription \
  --query video_no=VI568102998803353600

delete-videos and asset delete are destructive and require explicit confirmation:

memories v1 delete-videos --video-no VI568102998803353600 --yes
memories v2 asset delete --asset-id A1 --yes

JSON Contract

Successful commands print one JSON object to stdout and exit 0:

{
  "ok": true,
  "family": "v1",
  "command": "upload-url",
  "request": {
    "url": "https://example.com/demo.mp4",
    "callback": "https://example.com/callback",
    "uniqueId": "upload-123"
  },
  "result": {
    "videoNo": "VI568102998803353600"
  },
  "raw": {
    "message": "Success"
  }
}

Failed commands print one JSON object to stderr and exit non-zero:

{
  "ok": false,
  "error": {
    "code": "validation_error",
    "message": "the following arguments are required: --video-no",
    "retryable": false,
    "details": {}
  }
}

raw contains the original API response body when the server returns JSON. Binary download commands report structured metadata in result and set raw to null.