CLI reference

The aimem binary mounts a Memory Bucket and manages what is in it. Every command works on a Memory Bucket in your MinIO AIStor deployment.

The mount takes its settings from a --config file. The other commands take their settings as flags or environment variables (see Connection flags), never from a config file. They use the AIStor Memory API; aimem bio also uses the Iceberg REST catalog.

Mounting a Memory Bucket

aimem s3://<bucket>/ <mountpoint> mounts a Memory Bucket as a workspace. Put the settings in a YAML file, pass it with --config, and set credentials in the environment:

export AIMEM_ACCESS_KEY=... AIMEM_SECRET_KEY=...
aimem s3://my-memory-bucket/ /workspace --config /etc/aimem/mount.yaml

• Give the bucket as an S3 URI: s3://bucket/, or s3://bucket/prefix/ to mount a sub-prefix. A sub-prefix must end in /. The URI is never mistaken for an aimem command, so use it in scripts, fstab entries and systemd units. bucket and bucket/prefix/ are accepted as shorthand.
• The config file must set version: "1.0". It holds every mount setting, including the required staging directory (local:). See Configuration for every key.
• Credentials come only from the environment: AIMEM_ACCESS_KEY, AIMEM_SECRET_KEY, and the optional AIMEM_SESSION_TOKEN, or AIMEM_CREDENTIALS_FILE. They are never flags or config keys, so they stay out of config files and the process list.
• The target must be a Memory Bucket on a paid-tier AIStor server. See Prerequisites.

Mount flags

Each flag matches the config key of the same name, with dashes changed to underscores. A flag overrides the file. Use the flags for quick, one-off mounts.

Only --local, --local-size, --region, --tls-ca-file, and --tls-server-name also read an environment variable. Every other mount setting is set only in the config file; see Configuration.

Connection flags

Every command other than the mount reaches the Memory API with the same endpoint and credentials. Set them as environment variables (preferred) or as flags.

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

The credentials file is JSON: {"access_key_id": "...", "secret_access_key": "...", "session_token": "...", "expiration": "<RFC 3339>"}. session_token and expiration are optional.

Manage Memory Buckets

A Memory Bucket is an AIStor bucket built for agents: compressed, versioned, tagged with memory metadata, and encrypted when AIStor has a KMS. AIStor Memory mounts only a Memory Bucket, so every workspace starts here.

Each of these commands follows aimem directly, for example aimem create my-project.

create <name>

Create a Memory Bucket.

aimem create my-project

The name cannot be one of the aimem commands, such as list or secret. aimem <name> <mountpoint> would run the command instead of mounting the bucket.

You cannot change encryption, compression, or the KMS key after you create or convert a bucket.

convert <name>

Convert an existing regular bucket into a Memory Bucket, in place.

• Objects written before the conversion are not compressed, encrypted, or tagged. Only later writes are.
• Converting a bucket that is already a Memory Bucket does nothing.
• Warehouse buckets cannot be converted.
• A bucket named after an aimem command, such as list, can be converted. Mount it as aimem s3://list/ <mountpoint>, because aimem list runs the command.
• The converted bucket is also an Iceberg warehouse, so aimem bio tables work on it at once.

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

list

List Memory Buckets.

get <name>

Show one Memory Bucket: name, UUID, creation time, encryption, compression, KMS key (when pinned), memory format, and whether it was converted (upgraded). --json prints the full detail, including any operator metadata.

aimem get my-project --json

delete <name>

Delete a Memory Bucket and all its data.

On a terminal, aimem delete asks you to type the bucket name before it deletes anything. Scripts, which have no terminal, are not asked.

credentials <name>

Create temporary STS credentials that reach one Memory Bucket only (AssumeRole with an inline session policy). They can mount the bucket and use the Memory API on it, and nothing else. Use them to give a sandbox access to exactly one workspace.

# Set scoped, time-limited credentials in a sandbox.
eval "$(aimem credentials my-project --duration 3600)"

aimem secret — deployment-side secret provisioning

The process that launches the agent runs aimem secret, outside the sandbox: for example a sandbox controller, a CI job, or an orchestrator. The agent does not run it. Secrets never pass through the mount.

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

Fetch the granted secrets and set them as environment variables.

• With a command after --, provision starts the command as a child process, waits for it, and exits with its status. The command inherits the current environment, plus the granted secrets, minus the store and connection credentials. Removed: the AIMEM_SECRET_STORE_* variables, AIMEM_ACCESS_KEY, AIMEM_SECRET_KEY, AIMEM_SESSION_TOKEN, AIMEM_CREDENTIALS_FILE, AIMEM_ENDPOINT_URL, and AIMEM_REGION. The agent gets its API keys as ordinary environment variables but cannot read the store credential or fetch secrets again.
• With no command, it prints KEY=VALUE lines for the caller to use.

With --bucket, provision also needs the connection flags: an endpoint and either an access key and secret key or a credentials file. It stops with an error if they are missing. Use HTTPS for a production endpoint.

# Launch the agent with OPENAI_API_KEY set; store credentials are removed.
aimem secret provision --bucket my-project \
    --grant OPENAI_API_KEY=openai -- claude

secret put / get / list / delete

Manage secrets stored in a Memory Bucket. Run these from the launcher or an operator's machine, not from inside the sandbox. Each takes the connection flags.

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 regular-expression search on the server over a Memory Bucket's objects, which stay compressed and encrypted. It prints the names of matching objects, or with --content, the matching lines (name:line:text).

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

aimem history — who wrote each version

aimem history shows an object's versions: who wrote each one, and in which agent session. It takes the connection flags.

aimem history my-project/notes/plan.md

The object is bucket/key or s3://bucket/key, the same form the mount takes.

aimem bio — the agent's biography

aimem bio records what an agent did. It runs an OpenTelemetry collector next to the agent, writes the agent's traces, logs, and metrics into tables in the same Memory Bucket as its files, and reads them back.

The collector accepts standard OTLP/HTTP. Any harness or SDK that exports OpenTelemetry can send to it.

bio serve <bucket> --agent <ID> --endpoint-file <FILE> --session-key <ATTRIBUTE>

Run the collector. It listens on a loopback port, writes its base URL to --endpoint-file, and accepts OTLP/HTTP on /v1/traces, /v1/logs, and /v1/metrics, as JSON or protobuf, compressed with gzip or not.

aimem bio serve my-project --agent checkout-bot \
  --session-key session.id \
  --endpoint-file /run/agent/otlp-endpoint

• Run one collector per agent. An aimem.agent.id attribute in a payload is stored but does not choose the agent.
• Run it with the agent's own credential. A Memory Bucket's tables accept only that credential, and it cannot read the agent record, which is why --session-key is required. See Scoping a collector to one agent.
• You do not need to create tables first. Before it publishes its endpoint, the collector creates the agent's namespace and any missing tables.

Point the agent's exporter at the published endpoint:

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

For crash safety and back-pressure, see Agent telemetry.

Tables and columns

Each agent's telemetry goes into six tables: otel_spans, otel_span_events, otel_span_links, otel_logs, otel_metric_points, and otel_metric_exemplars. Payloads that cannot be stored go to otel_quarantine. bio serve creates missing tables before it publishes its endpoint; bio ingest creates them on its first write.

• Histograms. In otel_metric_points, a histogram point also fills count, sum, min, max, bucket_counts, and explicit_bounds, so SQL can add up token use and durations without parsing JSON. Other point types leave these columns empty. value_json holds every point in full.
• GenAI attributes. Spans, span events, and logs also store gen_ai_input_messages, gen_ai_output_messages, gen_ai_system_instructions, and gen_ai_tool_definitions as JSON. A key-value list becomes a JSON object with sorted keys, and an array stays an array. A string that holds a JSON object or array is stored as that JSON. Any other value is stored as a JSON scalar, so a plain string keeps its quotes ("gpt-5"). A non-finite number is stored as null; on its own, it leaves the column empty. The attribute map is unchanged.
• New columns. A table created before a column existed gets it the next time the collector starts; older rows read it as null. If the credential cannot change the table's schema, the collector says so and keeps writing the table as it is.

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

Read an agent's telemetry as JSON lines. --table defaults to otel_spans, and --limit to 100. --where takes one filter, session_id = <value>, to read one session. The session ID is whatever the harness sends. If the harness names it something AIStor Memory does not recognize, the column is 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 <bucket>[.<agent>]

List a Memory Bucket's namespaces (one per agent with telemetry), or the tables in one namespace.

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

bio export <bucket> --agent <ID> --output <FILE> [--table <TABLE>] [--where <EXPR>]

Write every row of an agent's table to a Parquet file, for engines that cannot read the tables directly, such as DuckDB and Spark. There is no row limit. Each timestamp is written in microseconds, which those engines read, and the exact value is kept in an integer column named <column>_unix_nano. --table defaults to otel_spans, and --where takes the same session_id = <value> filter as bio query.

aimem bio export my-project --agent checkout-bot --output spans.parquet

bio ingest <bucket> <path> [--session-key <ATTRIBUTE>]

Load OTLP/JSON from a file or directory, for example telemetry captured before the collector was running. Rows go to the same tables as live telemetry. Loading the same file again adds no duplicate rows while AIStor Memory still has its record of the payload. That record is limited in size, so after many later writes to a table, a replay can add rows again.

--session-key defaults to session.id. Run it with the agent's own credential: a Memory Bucket accepts only that agent's credential for its rows.

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

bio quarantine replay <bucket> --agent <ID> --session-key <ATTRIBUTE>

Write the rows in an agent's otel_quarantine table again, for example after you fix the cause. This writes rows again even when they were written before.

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

Create your own table in an agent's namespace, next to its telemetry tables, with that agent's credential. AIStor Memory manages the rest of a Memory Bucket's catalog: every credential, root included, is refused a namespace that is not an agent's own.

• --schema takes an Iceberg struct schema or a simple ordered field list ([{"name":"id","type":"string"}, …]). --schema - reads it from stdin.
• If the table exists with the same schema, nothing changes. If it exists with a different schema (a missing field, or a different type or required setting), the command fails.

aimem bio create my-project.checkout-bot.events --schema schema.json

What's next

• Configuration: every mount key.
• How memory works: workspace mode, memory warmup, and SKILLS.
• Operations: mounting in each sandbox runtime, logging, and metrics.