Configuration

This page lists every key in the mount configuration file. Pass the file to the mount with --config <FILE>:

aimem my-memory-bucket /workspace --config /etc/aimem/mount.yaml

• The Memory Bucket and the mountpoint are positional arguments.
• Signing credentials come from the environment (AIMEM_ACCESS_KEY and AIMEM_SECRET_KEY), never from the file.
• Everything else goes in the file, including the required local: staging directory. Some keys also have a CLI flag or environment variable for one-off changes; see CLI flags vs config-file keys.

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

Because local: is in the file, the command needs only the Memory Bucket, the mountpoint, and --config:

aimem my-memory-bucket /workspace --config /etc/aimem/mount.yaml

Every mount needs a staging directory. Set it with the local: key, the --local <DIR> flag, or the AIMEM_LOCAL environment variable.

Local store size

The local store holds two things: a staging file for each file open for writing, and a cache of recently read objects. By default, the cache grows until the filesystem under local is 95% full, as statfs reports it.

To cap both together, set local_size:

local_size: 10Gi

• Cached objects are evicted, least recently used first, to stay under 95% of the cap.
• A write that does not fit under the cap fails with ENOSPC. The file keeps every byte written before the failure, and the same descriptor can keep writing once there is room.

The value is in bytes, or a Kubernetes quantity: k, M, G, and T count in powers of 1000, and Ki, Mi, Gi, and Ti in powers of 1024. A fraction such as 1.5Gi rounds up to a whole byte. You can also set it with --local-size <SIZE> or AIMEM_LOCAL_SIZE.

Set local_size when local is on a filesystem that cannot report the directory's size. The usual case is a Kubernetes emptyDir with a sizeLimit: statfs reports the whole node disk, and kubelet evicts the pod once the directory passes the limit. Set local_size about 10% below the sizeLimit. The margin covers what the cap does not count, such as filesystem blocks, directories, and other files in the directory.

CLI flags vs config-file keys

These keys also have a CLI flag, and some have an environment variable: local, local_size, endpoint_url, region, request_timeout, health_path, tls_ca_file, tls_server_name, read_only, foreground, agent, session_file, bio_agent, bio_endpoint_file, bio_session_key, metadata_ttl, log_directory, debug, and no_log. The CLI reference lists the flags.

Every other key on this page is set only in the file.

To mount a sub-prefix, pass bucket/prefix/ (or s3://bucket/prefix/) as the bucket argument. There is no prefix key.

Recognised keys

The tables below list every key, by area. Later sections show most of them in YAML examples.

Schema & staging

Connection & transport

Mount & FUSE

Agent features

Memory & metadata

Transfer tuning

Observability

Health checks

health_interval, health_timeout, and health_optimistic are rejected without health_path.

An unknown key stops the mount with unknown field 'X', so a typo is never ignored.

Precedence

• For a key that is also a CLI flag, the flag (or its environment variable, such as AIMEM_LOCAL) wins. The file value applies only when the flag is not set.
• A boolean key in the file can only turn a setting on. A YAML false is the same as leaving the key out; it cannot turn off a flag set on the command line.
• endpoint_url in the file applies only when no --endpoint-url is passed. One --endpoint-url on the command line replaces the whole list.

Endpoints and load balancing

AIStor Memory spreads requests across AIStor nodes in turn (round-robin). List each node under endpoint_url:

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

A brace range is shorter and expands to the same list:

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

The range takes three dots ({1...4}, not {1..4}). You can mix both forms in one list.

Health checks

To take an unresponsive node out of the rotation and bring it back when it recovers, set health_path:

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

• With health_path set, a node is marked offline as soon as a request to it fails with a connection error, and also when a periodic check fails.
• With health_optimistic: true, only offline nodes are polled. Failures on healthy nodes are detected from connection errors and request timeouts.
• Without health_path, nodes are never marked offline. 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 request. When it passes, the request is retried on the next endpoint:

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

• It needs two or more endpoints.
• With two or more endpoints, the default is 30 seconds.
• With health_path set, a node that times out is marked offline until a health check succeeds. Without it, the node stays in the rotation.

Metadata TTL

metadata_ttl: indefinite # or `minimal`, or seconds (for example 60)
negative_metadata_ttl: 60 # seconds, or `indefinite` / `minimal`

metadata_ttl sets how long the kernel caches file metadata. A workspace assumes one writer per mount (one agent per mount), so the default is indefinite: the kernel does not look entries up again on each access.

• Set minimal (a short, non-zero TTL) when other clients may change the bucket while it is mounted.
• Set a number of seconds for a fixed cache window.
• metadata_ttl: 0 is deprecated. It is read as minimal and prints a warning.

"Not found" results follow metadata_ttl unless you set negative_metadata_ttl. negative_metadata_ttl takes effect only when you also set metadata_ttl. When metadata_ttl is not set, it is ignored.

FUSE / mount

read_only: false
auto_unmount: false
allow_root: false
allow_other: false
storage_class: STANDARD
max_threads: 16 # FUSE worker threads
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)

All of these except read_only are set only in the file.

Memory target

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

The prefetcher and buffer pool use max_memory_target to pace memory use and slow down when they reach it. The default is 95% of system memory, with a floor of 512 MiB. Set it lower on a shared host where other processes need memory.

Upload checksums

upload_checksums: crc32c # or `off`

The bucket's default encryption encrypts objects at rest. AIStor Memory does not set server-side encryption headers on each object.

Client tunables

user_agent_prefix: "my-app/1.0 "
virtual_host_style: false # default: path-style, which AIStor supports
part_size: 16777216 # 16 MiB, for GET and PUT
read_part_size: 16777216 # replaces part_size for GET only
write_part_size: 16777216 # replaces part_size for PUT only
io_retry_timeout: 60 # seconds to retry through a short backend failure

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

Logs go to syslog unless log_directory is set. In the foreground, logs also go to stdout. To set the log filter directly, use AIMEM_LOG; see Operations → Logging.

Workspace-specific keys

agent selects which agent's memory files (claude, codex, cursor, or auto) are warmed into the local store on mount. See How memory works for how warmup works.

The local store holds write staging and the read cache. Set it with the local: key, the --local <DIR> flag, or the AIMEM_LOCAL environment variable. One of the three is required, and the flag or environment variable wins over the key.

The AIStor Memory skill needs no key. On every mount, AIStor Memory:

• adds a short preamble, in memory, to instruction files read from the mount (CLAUDE.md, AGENTS.md, .cursorrules);
• installs the skill into $HOME/.agents/skills/aimem/ and $HOME/.claude/skills/aimem/.

To turn off the install, set AIMEM_INSTALL_SKILL=0. The install is also skipped when $HOME is inside the mount. To turn off the preamble, set AIMEM_PREAMBLE_OVERLAY=0. To install the Claude copy elsewhere, set CLAUDE_CONFIG_DIR. For agents outside the sandbox, install the public skill with npx skills add minio/skills/aimem. See the SKILLS section for details.

Secrets have no config key. aimem secret provision gives granted secrets to the agent as environment variables, from one source: --bucket for a Memory Bucket, or --store-endpoint for a generic HTTP secret store. aimem secret put, get, list, and delete manage secrets stored in a Memory Bucket. See the Vault and the CLI reference.

fstab

To mount at boot, add a line to /etc/fstab that points at the same YAML file:

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

The local: key in the file sets the staging directory. To set it in fstab instead, add local=<dir> (the older staging_dir= and staging-dir= also work). See Operations → fstab.