What is AIStor Memory?
AIStor Memory gives AI agents a durable memory on MinIO AIStor. One mount of a Memory Bucket holds the agent's workspace, its long-term memory, and its secrets, in your storage and under your keys.
An agent starts each run with no past. It does not know which approach failed last time, which correction a person made, or what is still open. Without a durable record, teams rebuild that context from transcripts on every run.
AIStor Memory is the memory your agents keep. It stores the agent's work and knowledge on MinIO AIStor, in your storage and under your keys. When a sandbox is torn down, the files stay, and the next session mounts the same files byte for byte.
The agent uses one thing: a mount of a Memory Bucket. A Memory Bucket is an AIStor bucket built for agents. It is compressed, encrypted, and version-tracked, and it has its own Memory API. The agent works in the mount and remembers through it, and AIStor Memory teaches the agent how to use it.
$ export AIMEM_ENDPOINT_URL=https://aistor.example.com
$ export AIMEM_ACCESS_KEY=… AIMEM_SECRET_KEY=…
$ aimem create my-project
created Memory Bucket my-project (bucket my-project, uuid 7f3c…)
$ aimem my-project /workspace --config /etc/aimem/mount.yaml
bucket my-project is mounted at /workspace
$ ls /workspace
CLAUDE.md MEMORY.md src/ tests/ .aimem/AIStor Memory mounts only a Memory Bucket. Create one with
aimem create,
or convert an existing bucket with aimem convert.
You configure a mount with a YAML file passed as --config <FILE>. It sets
the local cache directory and the AIStor endpoint. Signing credentials always
come from the environment (AIMEM_ACCESS_KEY and AIMEM_SECRET_KEY), never
from a flag or a config key.
The Memory Bucket is a paid-tier AIStor feature. To create or mount one, you
need a licensed AIStor deployment. On a free-tier or unlicensed server, aimem bucket create fails the Memory API check. For everything a mount needs, see
Prerequisites.
Three forms of one memory
AIStor Memory keeps memory in three forms on one Memory Bucket. Each form has its own purpose and lifecycle, but they are not three separate systems.
- Workspace: active work. The agent works in real files with the tools it
already uses.
git, editors,sqlite, and build tools run unchanged. - Long-term memory: what the agent learned. Knowledge that shapes future
work, kept beside the data that produced it. It includes memory files such as
CLAUDE.md,AGENTS.md, andMEMORY.md; per-object annotations (.aimem/annot/…); object metadata and tags; server-side search; and the agent's biography, a record of what it did, as queryable tables. - Vault: authority to act. Secrets stored in the Memory Bucket (encrypted server-side) or in your own external store. They reach the agent as environment variables at launch and are never written to the mount.
The skill connects the three forms. On every mount, AIStor Memory installs
the aimem Agent Skill in the agent's home directory
and adds a short preamble to the instruction files the agent reads. The agent
starts out knowing how to use the Memory Bucket. Both steps are on by default
and you can turn them off. The preamble is skipped when the mount root is a git
repository. See SKILLS for the rules.
What the agent gets
| A durable workspace | The agent edits real files in place with git, editors, sqlite, and build tools, with no special API. When a file is closed or synced (close() or fsync()), the edit is saved to the Memory Bucket. Files survive sandbox teardown, and the next session mounts them byte for byte. |
| Memory warmed on mount | The memory files agents look for (CLAUDE.md, .claude/, AGENTS.md, .cursor/, MEMORY.md, …) are copied to local disk in the background, so the first read is usually local instead of an S3 fetch. --agent {claude,codex,cursor,auto} picks which files. |
| Writable annotations | The agent attaches notes to any object under .aimem/annot/…. The notes stay next to the data they describe and move with the Memory Bucket. Tech preview: enable it per AIStor deployment under MinIO support guidance, and avoid it with production data until GA. |
| Metadata & provenance | Each object's S3 user metadata (user.s3.meta.*) and tags (user.s3.tags.*) are readable as extended attributes (xattrs). ls loads them in advance, so the agent can check where data came from before it acts. |
| Server-side search | aimem search <bucket> -e <regex> runs RE2 regular expressions on the server, over the stored objects. Multiple -e patterns must all match. The agent searches the whole Memory Bucket without downloading it. |
| Agent biography | aimem bio serve runs an OpenTelemetry collector beside the agent. What the agent's harness already sends over standard OTLP is stored as Apache Iceberg tables in the same Memory Bucket, so a record of what each run did is kept with what it produced. Every Memory Bucket supports these tables, including one converted with aimem convert. |
| Automatic skills | Every mount teaches the agent how to use all of the above, with no flags. A preamble is added to instruction files read from the mount, and the aimem Agent Skill is installed in $HOME/.agents/skills/aimem/ and $HOME/.claude/skills/aimem/. See SKILLS. |
| A vault for secrets | Secrets live in the Memory Bucket (aimem secret put/get/list/delete, encrypted server-side), or in your own external store (HashiCorp Vault/OpenBao, a cloud secret manager). aimem secret provision passes them to the agent as environment variables at launch. They are never written to the mount, and the store credential never reaches the agent. |
Why AIStor Memory
| Your data | Memory is customer data. It lives in your own AIStor Memory Bucket, compressed, and encrypted with KMS when a KMS is configured (pin a key with aimem create --kms-key-id, or use the server default). You decide what to keep and what to delete. It is never held in a vendor's cloud. |
| Real files | AIStor Memory stores the actual bytes, not a rebuilt summary. No model sits on the write path: what the agent writes is what it reads back. |
| Beside the data | The source data and what the agent learns from it stay in the same store, under the same identity, audit, and lifecycle controls. |
| Portable | Change agents, models, or where they run. What they learned stays in your infrastructure. |
| Nothing extra to run | No vector store, graph engine, or metadata cluster. One static binary works against the object store you already run. |
| Automatic skills | The aimem skill reaches the agent in three ways: a preamble on instruction files, an install in the agent's home directory, and the public minio/skills repository (npx skills add minio/skills/aimem). The first two are on by default; SKILLS lists when they are skipped. |
| AIStor-native | Built for MinIO AIStor, with multiple endpoints and MinIO-style {1...4} brace ranges. AIStor Memory requires AIStor. |
Explore the docs
Quick start
Install the binary, create a Memory Bucket, and mount it in about five minutes.
aimem reference
The three forms of memory in full: workspace, long-term memory, skills, and the secrets vault.
Architecture
How the mount presents a Memory Bucket as files: the read and write paths and the local cache.
Integrations
How to use AIStor Memory with agent sandboxes such as Codespaces, E2B, Daytona, and OpenAI Codex.
Operations
Prerequisites, fstab, logging, OpenTelemetry metrics, and sandbox-provider setup.