CLI reference

The aimem binary is how an agent reaches its memory. Every command works against one customer-owned cortex — a MinIO AIStor Memory Bucket — and each subcommand touches a different form of that memory: the workspace the agent works in, the long-term memory it remembers through, and the Vault of secrets it needs to act. Five surfaces, one cortex:

• mount — aimem <bucket> <mountpoint> mounts a cortex as the agent's workspace: the filesystem it both works in and remembers through (the default, no-subcommand form). A --config YAML file is the canonical way to configure the mount — see Mounting a cortex below. Mount a sub-prefix with the bucket/prefix/ positional. Mounting only works against a cortex: it needs an explicit endpoint and real signing credentials, and the target bucket must already be a cortex on a paid-tier AIStor deployment.
• aimem cortex — create and manage the Memory Buckets that hold every form of memory.
• aimem secret — the Vault: deployment-side secret provisioning for launchers.
• aimem search — long-term-memory search: regex over a cortex's data at rest.
• aimem bio — experimental structured memory: records and events kept as queryable tables in the same cortex (Iceberg / OTEL).

The management verbs share one set of connection flags. cortex, search, and cortex-backed secret operations use the AIStor Memory API; bio additionally uses the Iceberg REST catalog; and secret provision may instead target a generic HTTP secret store (--store-endpoint). --config applies only to the mount command — the management verbs take their settings as flags (or the connection env vars below), never from a config file.

Mounting a cortex

aimem <bucket> <mountpoint> mounts a cortex as a workspace. The canonical way to configure a mount is a --config YAML file: point --config at it, supply credentials in the environment, and pass the cortex and mountpoint as positionals.

export AIMEM_ACCESS_KEY=... AIMEM_SECRET_KEY=...
aimem my-cortex /workspace --config /etc/aimem/mount.yaml

The --config YAML must declare version: "1.0". It carries every mount setting — including the mandatory local: staging directory and the advanced tunables that have no CLI flag. See Configuration for the full key reference.

Credentials are environment-only: AIMEM_ACCESS_KEY, AIMEM_SECRET_KEY, and the optional AIMEM_SESSION_TOKEN. They are never mount flags and never --config YAML keys, so the signing secret stays out of config files and process arguments.

Mount flags

The everyday mount settings are also available as CLI flags. Each flag is equivalent to the --config YAML key of the same name (dashes become underscores), and --config is the preferred way to set them — the flags exist for quick, one-off mounts. An explicit flag always overrides the YAML value.

Of these, only --local (AIMEM_LOCAL), --tls-ca-file (AIMEM_TLS_CA_FILE), and --region (AIMEM_REGION) also read an environment variable; the rest are flag-or---config only, and credentials remain environment-only (above). Every other mount setting — the FUSE, transfer, memory, observability, and health-check tunables — is --config-only and listed in the Configuration key reference.

Connection flags

Every management verb reaches the Memory API with the same endpoint and credentials. Pass them as flags or — preferably — as environment variables.

export AIMEM_ENDPOINT_URL=https://aistor.example.com:9000
export AIMEM_ACCESS_KEY=your-access-key
export AIMEM_SECRET_KEY=your-secret-key

aimem cortex — manage Memory Buckets

A cortex is a first-class AIStor bucket built for agents: compressed, encrypted, KMS-backed, version-tracked, and stamped with memory metadata. AIStor Memory mounts only a cortex, so this is where every workspace begins.

cortex create <name>

Create a Memory Bucket.

aimem cortex create my-project

cortex convert <name>

Convert an existing regular bucket into a cortex in place. Idempotent — converting an existing cortex is a no-op. Objects written before the conversion are not retro-actively compressed, encrypted, or metadata-stamped; only writes after it honor the cortex contract. Warehouse buckets cannot be converted.

Any bucket you convert becomes a full cortex: besides the workspace and the Memory API, the resulting cortex also serves as an Iceberg warehouse, so structured memory (aimem bio tables, below) works on the same bucket immediately — no separate warehouse to stand up.

aimem cortex convert legacy-bucket --note "migrated 2026-07"

cortex list

List Memory Buckets.

cortex get <name>

Show a single cortex — bucket, uuid, created timestamp, encryption, compression, KMS key (when pinned), memory format, and the upgraded flag. Add --json for the full detail object (which also includes any operator metadata).

aimem cortex get my-project --json

cortex delete <name>

Delete a cortex and all its data.

cortex credentials <name>

Mint STS credentials scoped to a single cortex (AssumeRole with an inline session policy). The temporary credentials can mount the bucket and use the Memory API on it — and nothing else. This is how a launcher hands a sandbox least-privilege access to exactly one workspace.

# inject scoped, time-boxed credentials into a sandbox
eval "$(aimem cortex credentials my-project --duration 3600)"

aimem secret — deployment-side secret provisioning

aimem secret is a launcher / deployment helper, not a skill and not a command the agent runs. It is invoked by the process that launches the agent — a sandbox controller, a CI job, an orchestrator — outside the sandbox. Secrets never touch the mount, and the agent inside the workspace has no reason to call aimem secret at all.

secret provision --grant VAR=name [-- cmd …]

Fetch the granted secrets and inject them as environment variables. With a trailing -- <command>, the agent inherits the ambient environment with the store and connection credentials scrubbed (the AIMEM_SECRET_STORE_* and AIMEM_ACCESS_KEY / AIMEM_SECRET_KEY / AIMEM_SESSION_TOKEN / AIMEM_ENDPOINT_URL / AIMEM_REGION variables removed) and the leased secrets injected on top — so it keeps PATH/HOME, receives its API keys as ordinary environment variables, and can neither read the store credential nor re-fetch. The command is launched as a child process; provision waits for it and exits with the child's status (it does not exec). With no command, it prints KEY=VALUE lines for the caller to consume.

The --cortex path additionally requires the Memory-API connection credentials, given either as flags or environment variables:

provision errors if the endpoint, access key, or secret key is unset when --cortex is used.

# launch the agent with OPENAI_API_KEY leased in, store creds scrubbed
aimem secret provision --cortex my-project \
    --grant OPENAI_API_KEY=openai -- claude

secret put / get / list / delete

Manage secrets stored in a cortex over the Memory API. These, too, are launcher/operator-side administration — not something the sandboxed agent invokes.

printf '%s' "$OPENAI_KEY" | aimem secret put my-project openai
aimem secret list my-project

aimem search — regex over data at rest

Server-side regex search over a cortex's objects (compressed and encrypted at rest), returning matching object names — or the matched content with --content.

aimem search my-project --pattern 'TODO|FIXME' --ext md --ext rs --ignore-case

aimem bio — structured memory as tables (experimental)

Long-term memory can also take a structured form: records and events kept as queryable tables in the same cortex that holds the agent's files. aimem bio provisions those tables — backed by an Apache Iceberg catalog on the cortex — and ingests OpenTelemetry traces/logs/metrics into them, so a run's activity becomes durable memory the agent can query alongside its files.

bio create <cortex>.<namespace>.<table> --schema <FILE>

Create a namespace and table. --schema accepts a raw Iceberg struct schema or a friendly ordered field list ([{"name":"id","type":"string"}, …]); --schema - reads from stdin. Idempotent — an existing table with a matching schema is a no-op, and a create against an incompatible existing schema (a missing field, or a type/requiredness mismatch) is rejected.

aimem bio create my-project.app.events --schema schema.json

bio ls <cortex>[.<namespace>]

List a cortex's namespaces, or a namespace's tables.

aimem bio ls my-project        # namespaces
aimem bio ls my-project.otel   # tables in the otel namespace

bio ingest <cortex> <path>

Ingest OTLP/JSON telemetry (traces, logs, metrics) into the otel.* tables, which are auto-provisioned on first use. Idempotent per source file — a re-ingest of the same file adds no duplicate rows.

aimem bio ingest my-project ./otel-traces.json

bio query <cortex> <namespace>.<table> [--limit N]

Scan a table and print rows as JSON lines (default namespace otel, default limit 100).

aimem bio query my-project otel.spans --limit 20

What's next

• Configuration — the full mount-flag / YAML reference.
• aimem reference — workspace mode, memory warmup, SKILLS.
• Operations — per-sandbox recipes, logging, metrics.