am — command-line interface

The am CLI ships with the Python SDK.

pip install oramemory          # installs both `oramemory` library and `am` CLI

One-time setup

am init --api-key om_live_... --agent-id myai

This writes ~/.oramemory/config.json (mode 0600) with:

{
  "api_key":  "om_live_...",
  "agent_id": "myai",
  "base_url": "https://oramemory.com/api"
}

Re-run am init anytime to change settings, or edit the file directly.

Environment variables (override config)

Commands

Account / status

am status                # API health + embedding mode
am whoami                # plan, ops this month, memories stored
am usage                 # alias of whoami

Write

am add "text"            [--tags a b c --category … --importance 0.9 ...]
am add --file notes.md
echo "…" | am add
am update <id> "new text"
am update <id> --importance 0.9 --tags foo bar
am delete <id>

Read

am read "query"          [--top-k 5 --threshold 0.3 --scope agent]
am list                  [--agent-id x --layer l3 --page 1 --page-size 50]
am get <id>
am history <id>

Output format

am list -o json | jq '.[].content'

The -o/--output flag works before or after the subcommand.

Exit codes

Use these in shell scripts:

am get "$ID" >/dev/null 2>&1
case $? in
  0) echo "ok"   ;;
  2) echo "gone" ;;
  3) echo "auth broken" ;;
esac