Quick start

This is the five-minute path to give an agent its memory. You install the client, create a cortex (a MinIO AIStor Memory Bucket), and mount it. From then on the agent both works in and remembers through that one mount. Everything it writes persists to your AIStor, with your keys, and outlives any sandbox: the next session re-mounts the same state at full fidelity. The one 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.

The steps below are the mechanics of getting there.

Prerequisites

• A running MinIO AIStor deployment.
• An access key + secret key with the appropriate bucket permissions.
• Linux with the kernel FUSE device (/dev/fuse) available (Ubuntu 24.04+, CentOS Stream 10+, SLES 15 SP6+). AIStor Memory mounts over /dev/fuse directly through its own setuid aimem-fusermount helper — it does not link against libfuse.

Install

Install from a package, or download the binary on its own. The package is the simpler route on a host you administer: it carries the aimem mount client, the setuid aimem-fusermount helper that lets an unprivileged user mount, and the aimem-bio sibling that aimem bio runs.

From a package

The unversioned package names 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 a disabled example systemd mount unit at /etc/systemd/system/mnt-aimem.mount. To pin 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 verify it against its published .sha256sum before installing, so a corrupted or truncated download is rejected.

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

# Private, unpredictable dir: a shared /tmp/<name> path could be swapped by
# another local process 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 published checksum names the versioned file (aimem.RELEASE.<tag>), so
# check the hash against the local path. A mismatch aborts here (set -e).
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 append the release tag to the file name: ${BASE}/archive/aimem.RELEASE.2026-08-20T10-21-09Z, alongside its .sha256sum, .minisig, and .asc. Pin from archive/ rather than from ${BASE} directly: the unversioned directory holds only the newest release, so a versioned name there stops resolving once the next release ships.

The mount helper

aimem-fusermount lets an unprivileged user mount. It ships in the packages above, and it is also published as a standalone download:

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 published checksum names the versioned file, so check the hash against
# the local path. This helper installs setuid root, so a corrupt or truncated
# download must never reach the install step below — a mismatch aborts 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 mounts /dev/fuse directly.

Create a Memory Bucket

AIStor Memory mounts only a Memory Bucket (a cortex) — a plain bucket is refused at mount. Create one first (or convert a bucket you already have). The management verbs share one set of connection flags, 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 cortex create my-project
# or upgrade an existing regular bucket in place:
# aimem cortex convert my-project --note "migrated to cortex"

A cortex is a first-class AIStor bucket built for agents — compressed, encrypted, and version-tracked — with a native Memory API. The Memory API is a paid-tier AIStor feature, so creating or mounting a cortex needs a licensed deployment. See the CLI reference for every cortex verb.

Mount the cortex as a workspace

You configure a mount with a single --config <FILE> YAML file — the canonical mount interface. Bucket and mountpoint are positional; every tunable lives in the file.

Write the config once. Stash it somewhere reviewable (/etc/aimem/ is a good home):

# /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 the on-disk staging directory for files opened for writing, and it is required. Size it for the agent's working set; NVMe is recommended. With everything in the file, only credentials and the positionals 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 / AIMEM_SESSION_TOKEN) are environment-only — never a flag, never in the YAML. Most everyday config keys can also be set as a CLI flag. Only --local (AIMEM_LOCAL), --tls-ca-file (AIMEM_TLS_CA_FILE), and --region (AIMEM_REGION) additionally read an env var. Where a setting is given in more than one place, the CLI or env value overrides the config key. Many advanced tunables are --config-only (see the configuration reference).

The bucket (my-project) and the mountpoint (/workspace) are positional — they say which mount this invocation is for. Everything else lives in the YAML.

The mount is now ready for an agent to write into. Workspace mode is always on: every file opened for writing is staged on fast local storage, and the agent's tools work as they would on local disk. git, editors, sqlite, and build tools all run unchanged, editing files in place. Staged contents upload to the cortex atomically on close(). Memory-mapped I/O and copy_file_range return ENOSYS, so the kernel transparently falls back to read/write. Hard links are unsupported (link() returns EPERM).

Why YAML

The same defaults live in one reviewable file: source-controllable, diffable, easy to ship via configuration management, and impossible to fat-finger at 2 AM when the only difference between a working and a broken mount is a typo in a 200-character shell invocation. Multiple mounts on the same host share the file; per-host overrides go in a sibling YAML.

For the full set of recognised keys — endpoints, health-check tuning, metadata TTL, FUSE knobs, logging — see Configuration.

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

Every mount teaches the operating agent how to use it — no flags, in three tiers:

1. Read-time preamble (automatic). Instruction files read from the mount (CLAUDE.md / AGENTS.md / .cursorrules) are served with an in-memory preamble prepended. It never touches the stored object. Disabled when the mount root is a git repo; opt out with AIMEM_PREAMBLE_OVERLAY=0.

2. Installed skill (automatic). On every mount, AIStor Memory installs the aimem skill into $HOME/.agents/skills/aimem/ (Codex CLI, Cursor, Gemini CLI, Copilot) and $HOME/.claude/skills/aimem/ (Claude Code; honors CLAUDE_CONFIG_DIR). Each holds SKILL.md plus references/{navigation,workspace,memory,metadata,annotations,search}.md. Create-only and offline; skipped when $HOME is under the mount; opt out with AIMEM_INSTALL_SKILL=0.

3. Public skill. For agents whose reasoning runs outside the sandbox (e.g. the OpenAI Agents SDK), add it host-side:

   npx skills add minio/skills/aimem

Read aimem reference → SKILLS for the full description of each tier.

Unmount

umount /workspace

If aimem daemonized, umount triggers a clean shutdown. The foreground process also responds to SIGINT and SIGTERM.

What's next

• aimem reference — workspace mode, agent-memory warmup, SKILLS, secrets.
• CLI reference — every command surface: aimem cortex (create / convert / list / get / delete / credentials), aimem search (server-side regex over data at rest), aimem secret (provision / put / get / list / delete).
• Configuration — full YAML key reference: multi-endpoint, health checks, per-request timeout, metadata TTL, FUSE / S3 tunables.
• Operations — per-sandbox-provider recipes, fstab, logging, metrics.