mem0ai--mem0/skills/mem0-cli/references/workflows.md

Mem0 CLI Workflows

Practical recipes for using the mem0 CLI in scripts, pipelines, and agent loops.

---

Piping Content via Stdin

The CLI reads from stdin when no text argument is provided and input is piped (not a TTY). This works with add, search, and update.

Stdin detection method:

• Python: not sys.stdin.isatty()
• Node: !process.stdin.isTTY

Add from pipe

echo "I prefer dark mode" | mem0 add --user-id alice

Pipe multi-line content

cat <<EOF | mem0 add --user-id alice
The user prefers dark mode in all applications.
They also like monospace fonts for code editing.
EOF

Pipe from another command

git log --oneline -5 | mem0 add --user-id ci-bot --metadata '{"source":"git"}'

Search from pipe

echo "preferences" | mem0 search --user-id alice

Update from pipe

echo "Updated: prefers dark mode AND high contrast" | mem0 update abc-123-def-456

---

File Import

Use mem0 import to bulk-load memories from a JSON file.

Basic import

mem0 import memories.json --user-id alice

File format

The file should be a JSON array where each item has a memory, text, or content field:

[
  { "memory": "Prefers dark mode" },
  { "text": "Allergic to nuts", "metadata": { "source": "intake-form" } },
  { "content": "Uses VS Code", "user_id": "bob" }
]

CLI-provided --user-id overrides per-item user_id values.

Import with JSON output

mem0 import data.json --user-id alice -o json

Output:

{
  "status": "success",
  "command": "import",
  "data": { "added": 42, "failed": 0, "duration_s": 3.14 },
  "duration_ms": 3140
}

---

Agent Mode for LLM Consumption

Use --json or --agent to get structured JSON output suitable for LLM tool calling or agent frameworks. Spinners and progress always go to stderr, keeping stdout clean.

Search with agent mode

mem0 search "preferences" --user-id alice --agent

Output (stdout):

{
  "status": "success",
  "command": "search",
  "duration_ms": 187,
  "scope": { "user_id": "alice" },
  "count": 2,
  "error": null,
  "data": [
    { "id": "mem-abc", "memory": "User prefers dark mode", "score": 0.95, "created_at": "2025-01-15T10:00:00Z", "categories": ["preferences"] },
    { "id": "mem-def", "memory": "User likes monospace fonts", "score": 0.82, "created_at": "2025-01-15T10:01:00Z", "categories": ["preferences"] }
  ]
}

Add with agent mode

mem0 add "Uses Python 3.12" --user-id alice --json

Error handling in agent mode

Errors also return valid JSON with "status": "error":

mem0 search "test" --user-id alice --api-key invalid --agent

Output:

{
  "status": "error",
  "command": "search",
  "error": "Authentication failed. Your API key may be invalid or expired.",
  "data": null
}

---

JSON Output + jq

Use --output json (or -o json) for raw JSON output, then pipe to jq for processing.

Extract just memory text

mem0 list --user-id alice --output json | jq '.[] | .memory'

Get memory IDs

mem0 list --user-id alice -o json | jq '.[].id'

Count memories

mem0 list --user-id alice -o json | jq 'length'

Filter by category in jq

mem0 list --user-id alice -o json | jq '[.[] | select(.categories[]? == "preferences")]'

Extract search scores

mem0 search "tools" --user-id alice -o json | jq '.[] | {memory, score}'

---

Bulk Operations

Delete multiple memories by ID

# Get IDs, then delete each one
mem0 list --user-id alice -o json | jq -r '.[].id' | while read id; do
  mem0 delete "$id" --force
done

Bulk add from a text file (one memory per line)

while IFS= read -r line; do
  mem0 add "$line" --user-id alice
done < memories.txt

Copy memories between users

mem0 list --user-id alice -o json | jq -r '.[].memory' | while IFS= read -r mem; do
  mem0 add "$mem" --user-id bob
done

Export all memories to a file

mem0 list --user-id alice -o json > alice_memories.json

Paginate through all results

page=1
while true; do
  result=$(mem0 list --user-id alice -o json --page "$page" --page-size 100)
  count=$(echo "$result" | jq 'length')
  if [ "$count" -eq 0 ]; then
    break
  fi
  echo "$result"
  page=$((page + 1))
done

---

CI/CD Patterns

Store build context as a memory

mem0 add "Build #${BUILD_NUMBER} deployed ${APP_VERSION} to ${ENVIRONMENT} at $(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --agent-id "ci-bot" \
  --metadata "{\"build_number\":\"${BUILD_NUMBER}\",\"version\":\"${APP_VERSION}\",\"env\":\"${ENVIRONMENT}\"}"

Retrieve deployment history

mem0 search "deployment to production" --agent-id ci-bot -o json -k 10

Check CLI connectivity in CI

if mem0 status -o json | jq -e '.data.connected' > /dev/null 2>&1; then
  echo "mem0 is connected"
else
  echo "mem0 connection failed" >&2
  exit 1
fi

Non-interactive init in CI

mem0 init --api-key "$MEM0_API_KEY" --user-id ci-bot --force

Or simply use the environment variable (no init needed):

export MEM0_API_KEY="$MEM0_API_KEY"
mem0 add "CI run started" --user-id ci-bot

Store test results

test_summary=$(cat test-results.txt | head -20)
mem0 add "$test_summary" --agent-id ci-bot --metadata '{"type":"test-results"}' --categories "ci,testing"

---

Stdin Detection Details

The CLI reads from stdin only when ALL of these conditions are met:

1. No text argument was provided on the command line.
2. For add: no --messages and no --file flag.
3. For update: no --metadata flag.
4. stdin is piped (not a TTY).

This means:

• mem0 add --user-id alice in an interactive terminal will NOT hang waiting for input. It will print a usage error.
• echo "text" | mem0 add --user-id alice will read "text" from stdin.
• mem0 add "explicit text" --user-id alice will use the explicit text, even if stdin is piped.

Reading method:

• Python: sys.stdin.read().strip()
• Node: fs.readFileSync(0, "utf-8").trim()

---

Common Shell Patterns

Error handling with exit codes

set -e  # Exit on error

# This will exit the script if the API key is invalid
mem0 status > /dev/null 2>&1

# Add with error check
if mem0 add "test memory" --user-id alice 2>/dev/null; then
  echo "Memory added successfully"
else
  echo "Failed to add memory" >&2
  exit 1
fi

Capture memory ID from add

# Use agent mode to get structured output
result=$(mem0 add "new fact" --user-id alice --agent 2>/dev/null)
memory_id=$(echo "$result" | jq -r '.data[0].id // empty')
if [ -n "$memory_id" ]; then
  echo "Created memory: $memory_id"
fi

Conditional memory addition

# Only add if search returns no results
count=$(mem0 search "dark mode" --user-id alice --agent 2>/dev/null | jq '.count // 0')
if [ "$count" -eq 0 ]; then
  mem0 add "User prefers dark mode" --user-id alice
fi

Quiet mode for scripts

# Suppress all output except errors
mem0 add "background note" --user-id alice --output quiet 2>/dev/null
mem0 delete --all --user-id temp-user --force --output quiet 2>/dev/null

Using environment variables for scope

export MEM0_USER_ID="alice"
export MEM0_API_KEY="m0-xxx"

# All commands now default to user alice, no --user-id needed
mem0 add "prefers dark mode"
mem0 search "preferences"
mem0 list

Timeout handling

The CLI uses a 30-second timeout for all API requests. For long-running scripts, handle timeouts:

if ! mem0 search "query" --user-id alice -o json 2>/dev/null; then
  echo "Request failed or timed out" >&2
fi

---

Processing Delay Workaround

Memories are processed asynchronously after mem0 add. If you need to search for a newly added memory immediately, add a short delay:

mem0 add "new preference" --user-id alice
sleep 3
mem0 search "new preference" --user-id alice

Or use the event system to poll for completion:

# Add and capture event ID from agent output
result=$(mem0 add "new preference" --user-id alice --agent 2>/dev/null)
event_id=$(echo "$result" | jq -r '.data[0].event_id // empty')

if [ -n "$event_id" ]; then
  # Poll until processing completes
  while true; do
    status=$(mem0 event status "$event_id" --agent 2>/dev/null | jq -r '.data.status')
    if [ "$status" = "SUCCEEDED" ] || [ "$status" = "FAILED" ]; then
      break
    fi
    sleep 1
  done
fi

---

Multi-User Agent Pattern

For AI agents managing memories across multiple users:

#!/bin/bash
# agent_memory.sh -- manage memories for the current conversation

USER_ID="$1"
ACTION="$2"
shift 2

case "$ACTION" in
  recall)
    mem0 search "$*" --user-id "$USER_ID" --agent 2>/dev/null
    ;;
  remember)
    mem0 add "$*" --user-id "$USER_ID" --agent 2>/dev/null
    ;;
  forget)
    mem0 delete --all --user-id "$USER_ID" --force --agent 2>/dev/null
    ;;
  history)
    mem0 list --user-id "$USER_ID" --agent 2>/dev/null
    ;;
  *)
    echo '{"status":"error","error":"Unknown action: '"$ACTION"'"}' >&2
    exit 1
    ;;
esac

Usage:

./agent_memory.sh alice recall "dietary preferences"
./agent_memory.sh alice remember "allergic to shellfish"
./agent_memory.sh alice history