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. 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.

The script below downloads each binary and verifies it against the published .sha256sum before installing it, so a corrupted or truncated download is rejected. Integrity matters here because the aimem-fusermount helper is installed setuid root.

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

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, 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.
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