Quick start

This page takes you from nothing to a mounted Memory Bucket in about five minutes. You install the aimem client, create a Memory Bucket on MinIO AIStor, and mount it. The agent then works in that mount and keeps its memory there. What it writes is stored in your AIStor, under your keys, and outlives any sandbox. The next session mounts the same files.

The mount holds memory in three forms: a Workspace for active work, Long-term memory for what the agent learned, and a Vault for the secrets it needs to act.

Prerequisites

• A running MinIO AIStor deployment on a licensed (paid) tier. The Memory Bucket needs the AIStor Memory API, which free-tier servers do not have.
• An access key and secret key with permission to create and use buckets. A mount needs real credentials and an explicit endpoint URL. For the full list of checks a mount runs, see Prerequisites.
• Linux with the kernel FUSE device (/dev/fuse) available (Ubuntu 24.04+, CentOS Stream 10+, SLES 15 SP6+). AIStor Memory uses /dev/fuse directly through its own setuid helper, aimem-fusermount. It does not need libfuse.

Install

Install from a package, or download the binary on its own. On a host you administer, the package is simpler. It contains the aimem mount client, the setuid aimem-fusermount helper that lets an unprivileged user mount, and aimem-bio, which aimem bio runs.

From a package

The package names without a version always serve the current release.

ARCH=amd64   # or arm64 (arm64 needs glibc >= 2.39; amd64 runs on >= 2.34)
BASE=https://dl.min.io/aistor/aimem/release/linux-${ARCH}

# Debian, Ubuntu
curl -fsSLO "${BASE}/aimem.deb"
sudo apt-get install -y ./aimem.deb

# RHEL, Rocky, Fedora
curl -fsSLO "${BASE}/aimem.rpm"
sudo dnf install -y ./aimem.rpm

# Alpine
curl -fsSLO "${BASE}/aimem.apk"
sudo apk add --allow-untrusted ./aimem.apk

aimem --version

The package installs aimem in /usr/local/bin, sets the setuid bit on /usr/bin/aimem-fusermount, and adds an example systemd mount unit, disabled, at /etc/systemd/system/mnt-aimem.mount. To install an exact release instead, use the versioned file name from that release's notes, for example aimem_20260818072209.0.0_amd64.deb.

The binary on its own

Download aimem and check it against its published .sha256sum before you install it. The script stops if the download is corrupt or incomplete.

set -euo pipefail   # stop before install if the download or checksum fails
ARCH=amd64          # or arm64
BASE=https://dl.min.io/aistor/aimem/release/linux-${ARCH}

# Use a private temporary directory, so no other process can swap the file
# between the checksum check and the install.
TMPDIR="$(mktemp -d)"
trap 'rm -rf -- "$TMPDIR"' EXIT

curl -fsSL "${BASE}/aimem" -o "${TMPDIR}/aimem"
curl -fsSL "${BASE}/aimem.sha256sum" -o "${TMPDIR}/aimem.sum"

# The checksum file names the versioned file, so check the hash against the
# local path. A mismatch stops the script here.
echo "$(cut -d' ' -f1 "${TMPDIR}/aimem.sum")  ${TMPDIR}/aimem" | sha256sum -c -

sudo install -m 0755 "${TMPDIR}/aimem" /usr/local/bin/aimem

aimem --version

${BASE}/aimem always serves the current release. To pin an exact build, add archive/ to the path and the release tag to the file name: ${BASE}/archive/aimem.RELEASE.2026-08-20T10-21-09Z. Its .sha256sum, .minisig, and .asc files are in the same place. Always pin from archive/: ${BASE} holds only the newest release, so a versioned name there stops working when the next release ships.

The mount helper

aimem-fusermount lets an unprivileged user mount. The packages above include it, and you can also download it on its own:

set -euo pipefail
ARCH=amd64          # or arm64
BASE=https://dl.min.io/aistor/aimem/release/linux-${ARCH}

TMPDIR="$(mktemp -d)"
trap 'rm -rf -- "$TMPDIR"' EXIT

curl -fsSL "${BASE}/aimem-fusermount" -o "${TMPDIR}/aimem-fusermount"
curl -fsSL "${BASE}/aimem-fusermount.sha256sum" -o "${TMPDIR}/helper.sum"

# The helper is installed setuid root, so a corrupt download must never reach
# the install step. A checksum mismatch stops the script here.
echo "$(cut -d' ' -f1 "${TMPDIR}/helper.sum")  ${TMPDIR}/aimem-fusermount" | sha256sum -c -

sudo install -m 4755 -o root -g root "${TMPDIR}/aimem-fusermount" /usr/bin/aimem-fusermount

You do not need the helper when AIStor Memory runs as root or with CAP_SYS_ADMIN. It then uses /dev/fuse directly.

If a mount fails with not running as root, the helper did not get root privileges. Check three things:

• The helper is owned by root with the setuid bit set. ls -l shows -rwsr-xr-x root root. Run the sudo install command above to fix it.
• The helper is not on a filesystem mounted nosuid. The kernel ignores the setuid bit there. /usr/bin is not mounted nosuid on standard systems.
• The process does not have no_new_privs set. A container started with allowPrivilegeEscalation: false sets it, and the helper cannot work there. Run AIStor Memory as root with CAP_SYS_ADMIN instead, or use the CSI driver.

Create a Memory Bucket

AIStor Memory mounts only a Memory Bucket and refuses a plain bucket. Create one, or convert a bucket you already have. The Memory Bucket commands share one set of connection settings, which are easiest to set in the environment:

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

aimem create my-project
# or convert an existing bucket in place:
# aimem convert my-project --note "migrated to Memory Bucket"

A Memory Bucket is an AIStor bucket built for agents. It is compressed, version-tracked, and encrypted when AIStor has a KMS, and has its own Memory API. See the CLI reference for every bucket command.

Mount the Memory Bucket as a workspace

You configure a mount with one YAML file, passed as --config <FILE>. The bucket and the mount point go on the command line; every other setting goes in the file.

Write the file once and keep it somewhere you can review, such as /etc/aimem/:

# /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

version: "1.0" is required and must be a quoted string. local: is also required: it is the local staging directory for files opened for writing. Size it for the agent's working set; NVMe is recommended.

Then mount. Only the credentials, the bucket, and the mount point stay on the command line:

export AIMEM_ACCESS_KEY=your-access-key
export AIMEM_SECRET_KEY=your-secret-key

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

Credentials (AIMEM_ACCESS_KEY, AIMEM_SECRET_KEY, and AIMEM_SESSION_TOKEN) come only from the environment, never from a flag or the YAML file. Most everyday config keys also have a CLI flag. Only five of those flags also read an environment variable: --local (AIMEM_LOCAL), --local-size (AIMEM_LOCAL_SIZE), --tls-ca-file (AIMEM_TLS_CA_FILE), --tls-server-name (AIMEM_TLS_SERVER_NAME), and --region (AIMEM_REGION). When a setting is given in more than one place, the CLI or environment value wins over the config key. Many advanced settings exist only in the config file. See Configuration for every key.

The mount is now ready. Every file opened for writing is staged on local storage, so git, editors, sqlite, and build tools work as they do on local disk. When a file is closed, its contents upload to the Memory Bucket as one atomic write. Memory-mapped I/O and copy_file_range return ENOSYS, and the kernel falls back to read and write. Hard links are not supported (link() returns EPERM).

Work with your data

ls /workspace
cat /workspace/CLAUDE.md
$EDITOR /workspace/src/lib.rs
git -C /workspace status

How the agent learns the mount

You do not need to do anything. On every mount, AIStor Memory adds a short preamble to the instruction files the agent reads from the mount (CLAUDE.md, AGENTS.md, .cursorrules) and installs the aimem skill in the agent's home directory. Turn these off with AIMEM_PREAMBLE_OVERLAY=0 and AIMEM_INSTALL_SKILL=0.

If the agent's reasoning runs outside the sandbox, as with the OpenAI Agents SDK, install the skill on the host:

npx skills add minio/skills/aimem

See SKILLS for the details of each step.

Unmount

umount /workspace

If aimem runs in the background, umount shuts it down cleanly. A process in the foreground also stops cleanly on SIGINT or SIGTERM.

What's next

• How memory works: the workspace, memory warmup, skills, and secrets.
• CLI reference: every command, including aimem create, aimem search (server-side regex search), and aimem secret.
• Configuration: every YAML key, including multiple endpoints, health checks, timeouts, metadata TTL, and FUSE and S3 settings.
• Operations: sandbox-provider setup, fstab, logging, and metrics.