Configuration

YAML-key reference for the AIStor Memory mount — how you point an agent at its memory on a MinIO AIStor Memory Bucket (cortex). Covers the local staging store, multi-endpoint, health checks, request timeout, metadata TTL, FUSE / S3 client tunables.

An AIStor Memory mount is how an agent reaches its memory: one mount of a MinIO AIStor Memory Bucket (a cortex) that the agent both works in and remembers through. This page is the operator reference for the file that configures that mount. A --config <FILE> YAML file is the canonical way to configure an AIStor Memory mount — anything you'd want to tune at mount time has a key on this page.

aimem my-cortex /workspace --config /etc/aimem/mount.yaml

The cortex and mountpoint are positional — they say which mount this invocation is for; signing credentials come from the environment (AIMEM_ACCESS_KEY / AIMEM_SECRET_KEY). Everything else, including the mandatory local: staging directory, lives in the YAML. A handful of the YAML keys are also exposed as CLI flags and env vars for one-off overrides (noted throughout this page), but the config file is the source of truth.

Every config file must declare its schema version as its first key: version: "1.0" (a quoted string — bare 1.0 parses as a float and is rejected). A file with a missing or unrecognized version is rejected at parse time. This build understands version 1.0.

AIStor Memory mounts only a Memory Bucket (cortex), never a plain S3 bucket. A mount therefore always needs an explicit endpoint (endpoint_url), real signing credentials (AIMEM_ACCESS_KEY / AIMEM_SECRET_KEY), and a target that the Memory API confirms is a cortex on a paid-tier server — otherwise it refuses to start. Create one first with aimem cortex create <name>. See the aimem reference page for the cortex, search, and secret command families. --config is mount-only — the management verbs (cortex, secret, search) take their own flags and ignore the mount config file.

Minimum configuration

# /etc/aimem/mount.yaml
version: "1.0"
local: /var/cache/aimem
endpoint_url:
  - http://aistor{1...4}:9000
region: us-east-1
agent: claude
metadata_ttl: indefinite

Mount it — the mandatory local staging store comes from the local: key in the YAML, so the command line only needs the cortex, the mountpoint, and --config:

aimem my-cortex /workspace --config /etc/aimem/mount.yaml

The staging store is required at every mount, but it can be supplied any one of three ways: the local: config key (shown above), the --local <DIR> CLI flag, or the AIMEM_LOCAL env var. If none of the three is present, AIStor Memory refuses to start.

CLI flags vs config-file keys

The config file is canonical, but a small set of everyday keys are also exposed as CLI flags (and env vars) for one-off overrides — local, endpoint_url, region, request_timeout, health_path, tls_ca_file, read_only, foreground, agent, metadata_ttl, log_directory, debug, no_log — plus the bucket/bucket/prefix/ mountpoint positionals. Everything else on this page is config-file only: the advanced tunables below have no CLI flag and are set only in the YAML, which keeps the everyday aimem --help surface small.

local is the mandatory one of that set: at least one of the local: config key, the --local <DIR> CLI flag, or the AIMEM_LOCAL env var must be present at every mount, or AIStor Memory refuses to start. When more than one is supplied, the CLI flag (or env var) wins over the config key.

The config-file-only keys are advanced tunables — the defaults are right for almost every deployment. Only set them if you know why you need to.

To mount a sub-prefix, use the bucket/prefix/ positional (or an s3://bucket/prefix/ URI) — there is no prefix key.

Recognised keys

The full key vocabulary, grouped by area. Every key is also shown in context with a YAML example in the sections further down.

Schema & staging

Key	What it is	Default
`version`	Config schema version. Required; must be `"1.0"` (quoted string). Missing or unrecognised ⇒ rejected at parse time.	—
`local`	Mandatory local staging + read-cache directory. Also settable via `--local <DIR>` / `AIMEM_LOCAL`; one of the three is required.	—

Connection & transport

Key	What it is	Default
`endpoint_url`	MinIO AIStor node URL(s). List several, or use a `{1...N}` brace range, for failover.	—
`region`	Region used for request signing (e.g. `us-east-1`).	`us-east-1`
`request_timeout`	Per-request deadline (seconds); retries on the next endpoint when exceeded.	`30` (multi-endpoint)
`tls_ca_file`	Extra CA bundle (PEM) for verifying endpoint TLS. Also `--tls-ca-file` / `AIMEM_TLS_CA_FILE`.	—
`insecure_skip_tls_verify`	Skip endpoint TLS certificate verification.	`false`
`virtual_host_style`	Use bucket-DNS (virtual-hosted) addressing. The default is path-style, which AIStor supports natively.	`false`
`user_agent_prefix`	Prepend a custom string to the `User-Agent` header.	—

Mount & FUSE

Key	What it is	Default
`read_only`	Mount in read-only mode.	`false`
`foreground`	Keep AIStor Memory in the foreground (don't daemonize).	`false`
`auto_unmount`	Automatically unmount when AIStor Memory exits.	`false`
`allow_root`	Standard FUSE access control.	`false`
`allow_other`	Standard FUSE access control.	`false`
`max_threads`	Maximum FUSE worker threads.	`16`
`uid`	Owner UID reported by `stat()`.	caller's UID
`gid`	Owner GID reported by `stat()`.	caller's GID
`dir_mode`	Directory permissions reported by `stat()` (octal).	`0755`
`file_mode`	File permissions reported by `stat()` (octal).	`0644`

Agent features

Key	What it is	Default
`agent`	`claude` · `codex` · `cursor` · `auto` — which vendor-memory paths are warmed into the cache.	—
`agent_manifest`	Path to a custom warmup manifest overriding the built-in per-agent memory paths.	—

Memory & metadata

Key	What it is	Default
`max_memory_target`	Soft cap (MiB) the prefetcher and buffer pool use to pace allocation.	95% of RAM (512 MiB floor)
`metadata_ttl`	How long the kernel caches FUSE metadata: `indefinite` · `minimal` · seconds.	`indefinite`
`negative_metadata_ttl`	TTL for negative (not-found) lookups: seconds · `indefinite` · `minimal`.	tracks `metadata_ttl`
`metadata_dir_ttl`	TTL for the directory-listing cache: seconds · `indefinite` · `minimal`.	off unless set

Transfer tuning

Key	What it is	Default
`part_size`	Part size for multi-part GET and PUT, in bytes.	16 MiB
`read_part_size`	Override GET part size only.	`part_size`
`write_part_size`	Override PUT part size only.	`part_size`
`upload_checksums`	`crc32c` · `off` — checksum algorithm sent on upload.	`crc32c`
`infer_content_type`	Guess and set `Content-Type` on upload from the file extension.	`false`
`storage_class`	Storage class used for new objects.	`STANDARD`
`io_retry_timeout`	Wall-clock budget (seconds) to ride through a transient backend failure on the data path; `0` fails fast.	`60`

Observability

Key	What it is	Default
`log_directory`	Write logs to files under this directory instead of stdout.	—
`trace_log`	Write a low-level trace log to this file path.	—
`log_metrics`	Emit metric records to the log stream.	`false`
`otlp_endpoint`	Export metrics over OTLP/HTTP.	—
`otlp_export_interval`	OTLP push interval (seconds).	`60`
`no_log`	Suppress logging entirely.	`false`
`debug`	`RUST_LOG=debug` shorthand.	`false`

Health checks

Key	What it is	Default
`health_path`	HTTP path polled per node to check liveness. Required to enable health checks.	—
`health_interval`	Seconds between health checks per node.	`5`
`health_timeout`	Seconds to wait for each health-check response.	`10`
`health_optimistic`	Poll only offline nodes; detect failures reactively for healthy ones.	`false`

Unknown keys are rejected at parse time, so typos surface as unknown field 'X' instead of being silently ignored.

Precedence

For any key that is both a CLI flag and a config key, an explicit CLI flag (or its env var, e.g. AIMEM_LOCAL, AIMEM_ACCESS_KEY) wins and the YAML value fills in only when the flag is absent. Boolean keys treat true as "on"; a YAML false is the same as omitting the key (it can never turn a CLI-enabled toggle off). For the repeated endpoint_url key, the YAML list applies only when no --endpoint-url is passed on the command line; a single CLI --endpoint-url replaces the whole list.

Endpoints and load balancing

AIStor Memory distributes requests across multiple MinIO AIStor nodes using round-robin load balancing. List each node under endpoint_url:

endpoint_url:
  - http://aistor1:9000
  - http://aistor2:9000
  - http://aistor3:9000
  - http://aistor4:9000

MinIO-style brace-range patterns are the recommended shorthand and expand to the same set:

endpoint_url:
  - http://aistor{1...4}:9000

Three dots are required ({1...4}, not {1..4}). Both forms work and can be combined when an endpoint set is heterogeneous.

Health checks

When a node becomes unresponsive, AIStor Memory can automatically remove it from the pool and restore it once it recovers. Set health_path to enable:

endpoint_url:
  - http://aistor{1...4}:9000
health_path: /minio/health/ready
health_interval: 5
health_timeout: 10
health_optimistic: false

These keys are documented in the Recognised keys table above. With health_optimistic, failures on healthy nodes are detected reactively via connectivity errors and request timeouts rather than periodic polling.

With health_path set, a node is also marked offline reactively — immediately on a request that fails with a connectivity error, not only on the periodic poll. Without health_path there is no offline tracking: a failed request is retried on the next endpoint and the node stays in the rotation.

Per-request timeout

request_timeout sets a deadline on each S3 request and retries on the next available endpoint when exceeded:

endpoint_url:
  - http://aistor{1...4}:9000
health_path: /minio/health/ready
request_timeout: 30

Only valid when two or more endpoints are configured. With health_path set, a node that causes a timeout is immediately marked offline until health checks confirm recovery; without it, the request is retried on the next endpoint but the node remains in the pool.

When multiple endpoints are configured and request_timeout is not set explicitly, AIStor Memory applies a default of 30 seconds so the multi-endpoint failover path actually engages.

Metadata TTL

metadata_ttl: indefinite # or `minimal`, or seconds (e.g. 60)
negative_metadata_ttl: 60 # seconds, or `indefinite` / `minimal`

Controls how long the kernel caches FUSE metadata. AIStor Memory's workspace mode assumes a single writer per mount (one agent per mount), so the default is indefinite — entries are not re-looked-up on each access.

Set to minimal (small but non-zero TTL) when other clients may be mutating the bucket under the mount, or to a specific number of seconds for a deterministic cache window. metadata_ttl: 0 is deprecated — interpreted as minimal and prints a warning.

Negative (not-found) lookups have no independent default: the negative-lookup TTL tracks metadata_ttl — indefinite in the default workspace mode. Set negative_metadata_ttl to override it, but note it only takes effect when metadata_ttl is also set explicitly; on the default (unset metadata_ttl) path the negative TTL simply follows the indefinite metadata TTL and negative_metadata_ttl is ignored.

FUSE / mount

read_only: false
auto_unmount: false
allow_root: false
allow_other: false
storage_class: STANDARD
max_threads: 16 # FUSE worker pool size
uid: 1000 # owner UID reported by stat()
gid: 1000 # owner GID reported by stat()
dir_mode: "0755" # directory permissions (quoted octal string)
file_mode: "0644" # file permissions (quoted octal string)

These keys (except read_only) are config-file only. To mount a sub-prefix, use the bucket/prefix/ positional — there is no prefix key. All keys are documented in the Recognised keys table above.

Memory target

max_memory_target: 4096 # MiB; soft cap on AIStor Memory's resident memory

max_memory_target is a soft cap (in MiB) used by the prefetcher and buffer pool to pace allocation and trigger backpressure. The default is 95% of total system memory with a 512 MiB floor — set this lower on shared hosts where other processes need headroom.

Upload checksums

upload_checksums: crc32c # or `off`

Objects are encrypted at rest by the bucket's default encryption; aimem does not set per-object server-side-encryption headers.

Client tunables

user_agent_prefix: "my-app/1.0 "
virtual_host_style: false # default: path-style, which AIStor supports natively
part_size: 16777216 # 16 MiB; shared GET + PUT chunk size
read_part_size: 16777216 # overrides part_size for GET only
write_part_size: 16777216 # overrides part_size for PUT only
io_retry_timeout: 60 # seconds to ride through a transient backend failure

These keys are documented in the Recognised keys table above.

Logging

debug: false
no_log: false
log_directory: /var/log/aimem
log_metrics: false
otlp_endpoint: http://otel-collector:4318
otlp_export_interval: 60
foreground: false

These keys are documented in the Recognised keys table above. In foreground mode, logs go to stdout.

Workspace-specific keys

These belong to AIStor Memory's agent-workspace product surface and are documented in /aimem:

agent — claude · codex · cursor · auto — selects which vendor-memory paths get warmed into the --local store on mount.

The local store itself — copy-on-write write staging plus the FUSE-passthrough read cache — is set with the mandatory local: config key, the --local <DIR> CLI flag, or the AIMEM_LOCAL env var. Exactly one of the three is required at every mount; the CLI flag/env var wins over the config key when more than one is given.

The AIStor Memory skill is delivered automatically — no config key. Every mount both prepends an in-memory preamble overlay to instruction files read from the mount (CLAUDE.md / AGENTS.md / .cursorrules) and installs the skill into $HOME/.agents/skills/aimem/ and $HOME/.claude/skills/aimem/. Both are automatic and on by default: disable the install with AIMEM_INSTALL_SKILL=0 (also skipped when $HOME is under the mount), disable the overlay with AIMEM_PREAMBLE_OVERLAY=0, and relocate the Claude target with CLAUDE_CONFIG_DIR. See the SKILLS section on the aimem reference page for details; the public repo copy is npx skills add minio/skills/aimem.

Secrets are a separate CLI surface, not a config-file key. aimem secret provision injects granted secrets into the agent as env vars from the cortex (Memory-API secrets endpoint, --cortex, the default) or, as a bridge, from a generic HTTP store (--store-endpoint) when secrets already live there; aimem secret put/get/list/delete manage secrets stored server-side in a cortex. Described on the aimem reference page.

fstab

When you want the mount to come up at boot, AIStor Memory can be invoked from /etc/fstab via mount.fuse3. Use the same YAML file as the single source of truth:

my-cortex /workspace fuse.aimem _netdev,config=/etc/aimem/mount.yaml 0 0

The local: key in the referenced YAML supplies the mandatory staging store. If you prefer to set it inline instead, the fstab -o surface accepts local=<dir> (and the legacy staging_dir=/staging-dir= spellings). See Operations → fstab for the recipe.

On this page