Quick start

Give an agent its memory in five minutes — install AIStor Memory, create a cortex (a MinIO AIStor Memory Bucket), and mount it.

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 — and 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

Download the released binaries from the public CDN. The aimem binary is the mount client; the setuid aimem-fusermount helper lets it mount without root on hosts where you are not privileged.

Each binary is downloaded and verified against its published .sha256sum before install — a corrupted or truncated download is rejected (the aimem-fusermount helper is installed setuid root, so integrity matters).

set -euo pipefail   # abort before install if any download or checksum fails
VERSION=latest   # or pin a release, e.g. RELEASE.2026-06-01T00-00-00Z
BASE=https://dl.min.io/aistor/aimem/release/${VERSION}
ARCH=amd64       # or arm64 (arm64 needs glibc >= 2.39; amd64 runs on >= 2.34)

# Private, unpredictable dir: a shared /tmp/<name> path could be swapped by
# another local process between the checksum check and the setuid install.
TMPDIR="$(mktemp -d)"
trap 'rm -rf -- "$TMPDIR"' EXIT

# Download each binary and verify it against its published .sha256sum — a
# mismatch aborts here (set -e), so no corrupt setuid binary is installed.
for name in aimem aimem-fusermount; do
    curl -fsSL "${BASE}/${name}-linux-${ARCH}"          -o "${TMPDIR}/${name}"
    curl -fsSL "${BASE}/${name}-linux-${ARCH}.sha256sum" -o "${TMPDIR}/${name}.sum"
    echo "$(cut -d' ' -f1 "${TMPDIR}/${name}.sum")  ${TMPDIR}/${name}" | sha256sum -c -
done

# Install the mount client, and the setuid-root mount helper.
sudo install -m 0755                 "${TMPDIR}/aimem"            /usr/local/bin/aimem
sudo install -m 4755 -o root -g root "${TMPDIR}/aimem-fusermount" /usr/bin/aimem-fusermount

aimem --version

Set ARCH=arm64 above for arm64 hosts. When AIStor Memory runs as root (or with CAP_SYS_ADMIN), it mounts /dev/fuse directly and the aimem-fusermount helper is optional.

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, easiest 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 cortex create/mount needs a licensed deployment. See the CLI reference for every cortex verb.

Mount the cortex as a workspace

A mount is configured by a single --config <FILE> YAML — 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 open-for-write files; it is required (size it for the agent's working set — NVMe 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 keys are also settable as a CLI flag; only --local (AIMEM_LOCAL), --tls-ca-file (AIMEM_TLS_CA_FILE), and --region (AIMEM_REGION) additionally read an env var. When both are set, a CLI or env value overrides the config key. Many advanced tunables are --config-only (see the configuration reference) — and --config is the canonical interface.

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, build tools, 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:

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.
Installed skill (automatic). On every mount aimem 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.
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.

On this page