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. 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. This is the default form, with no subcommand. 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 — the biography: an OpenTelemetry collector that records what an agent did into queryable tables in the same cortex.

The management verbs share one set of connection flags. cortex, search, and cortex-backed secret operations use the AIStor Memory API. bio also uses the Iceberg REST catalog. secret provision can 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 as 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 — the advanced tunables that have no CLI flag, and the mandatory staging directory (via the local: key here, or the --local flag / AIMEM_LOCAL env var — at least one is required). 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. The process that launches the agent — a sandbox controller, a CI job, an orchestrator — runs it 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 and the leased secrets injected on top. Scrubbing removes the AIMEM_SECRET_STORE_* variables and AIMEM_ACCESS_KEY / AIMEM_SECRET_KEY / AIMEM_SESSION_TOKEN / AIMEM_ENDPOINT_URL / AIMEM_REGION. The agent therefore keeps PATH/HOME and receives its API keys as ordinary environment variables, but can neither read the store credential nor re-fetch.

provision launches the command as a child process, 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

aimem search runs a server-side regex search over a cortex's objects, which stay compressed and encrypted at rest. It returns the names of matching objects, or with --content, the matching lines in grep style (name:line:text).

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

aimem bio — the agent's biography

An agent's memory also has a structured form: what it did, kept as queryable tables in the same cortex that holds its files. aimem bio runs an OpenTelemetry collector beside the agent, writes what the agent's harness emits into that cortex, and reads it back — so a run's activity becomes durable memory alongside the files it produced.

The collector speaks standard OTLP/HTTP, so nothing has to be written against a proprietary API. Any harness or SDK that can export OpenTelemetry — a coding agent's telemetry plugin, an application's own instrumentation — points at it and its traces, logs and metrics land in the cortex.

bio serve <cortex> --endpoint-file <FILE>

Run the collector. It binds a loopback port, writes the base URL it chose to --endpoint-file, and accepts OTLP/HTTP on the standard /v1/traces, /v1/logs and /v1/metrics paths — JSON or protobuf, gzipped or not.

aimem bio serve my-project --endpoint-file /run/agent/otlp-endpoint

Run one per agent. The collector carries no identity of its own: each payload is stored under the agent named by its aimem.agent.id resource attribute, and what it may actually write is decided by the credential it runs with — give it one scoped to its agent and AIStor refuses the rest. See Scoping a collector to one agent for the policy.

Point the agent's exporter at the published endpoint:

export OTEL_EXPORTER_OTLP_ENDPOINT="$(cat /run/agent/otlp-endpoint)"

Each agent's telemetry is written to six tables — otel_spans, otel_span_events, otel_span_links, otel_logs, otel_metric_points and otel_metric_exemplars — created on first use.

bio query <cortex> --agent <ID> [--table <TABLE>] [--where <EXPR>] [--limit N]

Read an agent's telemetry back, as JSON lines. --table defaults to otel_spans and --limit to 100. --where takes one filter, session_id = <value>, which narrows the read to a single agent session. The session is whatever identifier the harness itself emits — nothing to configure — so a harness that names it something the reader does not recognise leaves the column empty and the filter matches nothing.

aimem bio query my-project --agent checkout-bot --limit 20
aimem bio query my-project --agent checkout-bot --table otel_logs \
  --where "session_id = 2f9c1b04"

bio ls <cortex>[.<agent>]

List a cortex's namespaces — one per agent that has telemetry, plus any you made yourself with bio create — or the tables in one of them.

aimem bio ls my-project              # namespaces
aimem bio ls my-project.checkout-bot # that agent's tables

bio ingest <cortex> <path>

Load OTLP/JSON from a file or directory — for backfilling telemetry captured before the collector was running, or for replaying a capture. Routed the same way as live telemetry, and idempotent per payload: re-ingesting a file adds no duplicate rows while its record is still held, which covers replaying a capture or re-running a backfill. The record is bounded, so a replay is not deduplicated indefinitely against a table that has been written many times since.

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

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

Create a table of your own in the cortex, alongside the telemetry ones. --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

What's next

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