AIStor Memory — memory for AI agents
The memory your AI agents keep — a durable, customer-owned record of prior work on MinIO AIStor. One mount of a Memory Bucket (a cortex) gives an agent a workspace, long-term memory, and a vault for secrets. Your storage, your keys, portable across agents and models.
An agent begins each run with no past. A capable model gives it raw ability, but every runtime arrives without the working knowledge your organization has already earned — which approach failed, which correction a person supplied, what remains unresolved. Without a durable record, teams rebuild that context from transcripts every time, paying for knowledge they already created.
AIStor Memory is the memory your agents keep. It gives an agent continuity: a durable, customer-owned record of the work that came before, on MinIO AIStor. The sandbox is disposable — when it's torn down, the files and the knowledge stay in the durable cortex, and the next session re-mounts the same state at full fidelity: the real files, byte-for-byte, not a summary.
It is one thing the agent uses: a mount of an AIStor Memory Bucket (a cortex) that the agent both works in and remembers through. Everything persists to AIStor — your storage, your keys — and AIStor Memory teaches the agent, automatically, how to use it.
$ export AIMEM_ENDPOINT_URL=https://aistor.example.com
$ export AIMEM_ACCESS_KEY=… AIMEM_SECRET_KEY=…
$ aimem cortex create my-project
created cortex 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 cortex. Create one first with
aimem cortex create, or
convert an existing bucket with aimem cortex convert.
A --config <FILE> YAML file is the canonical mount interface. It sets the
local cache directory and the AIStor endpoint. Signing credentials always come
from the environment (AIMEM_ACCESS_KEY / AIMEM_SECRET_KEY), never from a
flag or a config key.
A Memory Bucket (cortex) is a paid-tier AIStor capability. To create and mount
one, you need a licensed AIStor deployment reachable over the Memory API. On a
free-tier or unlicensed server, the first aimem cortex create fails the
Memory-API check.
Three forms of one memory
Anything an agent needs to keep is memory. AIStor Memory holds it in three forms on one customer-owned cortex — each with its own purpose and lifecycle, not three separate systems.
- Workspace — active work. The agent works in real files with the tools it
already uses —
git, editors,sqlite, build tools all run unchanged. Its files survive sandbox teardown because they live in the durable cortex, not in session residue. - Long-term memory — what the agent learned. Durable knowledge that shapes
future work, kept beside the data that formed it. It takes five forms: the
memory files agents already look for (
CLAUDE.md,AGENTS.md,MEMORY.md), warmed on mount; writable per-object annotations (.aimem/annot/…) for reasoned notes co-located with the bytes; read-only object metadata and tags as provenance; server-side search across the whole cortex; and structured memory as queryable tables in the same cortex (experimental). - Vault — authority to act. Secrets held in the cortex (encrypted server-side) or provisioned from your own external store, leased into the agent as environment variables at launch — never written to the mount.
Tying the three together is the skill — the teaching layer. On every mount,
AIStor Memory installs the aimem Agent Skill into the
agent's home and prepends a short orientation preamble to the instruction files
the agent reads. The model arrives already knowing how to work in the cortex,
with no action from you.
Both behaviours are on by default and can be turned off, and the preamble is skipped on git-repo mounts. See SKILLS for the exact rules.
Why memory belongs here
- Sovereign customer data. Memory is customer data, not disposable model
output. It lives in a MinIO AIStor cortex you already run — compressed, and
KMS-encrypted when a KMS is configured (pin the key with
aimem cortex create --kms-key-id, or take the server default) — with a lifecycle you control: curate, retain, or delete. - Real files, not a rebuilt summary. AIStor Memory stores the actual bytes — a file the agent can open, with no model on the write path. What the agent writes is what it reads back, byte for byte.
- No separate database to run. No vector store, no graph engine, no metadata cluster — one static binary against the object store you already operate.
- Beside the data that formed it. The evidence stays in AIStor; the meaning the agent derives from it stays in the same governed store, with the same identity, audit, and lifecycle — references and provenance, not a copy in someone else's index.
- Portable. Change agents, models, or where they run as often as you like. The experience they earned stays in your infrastructure and belongs to you.
What the agent gets
| A durable workspace | The agent works in real files with the tools it already uses: git, editors, sqlite, and build tools all run unchanged, editing in place with no special API. Once saved (on close() / fsync()), edits are real files in the cortex. They survive sandbox teardown, and the next session re-mounts them byte-for-byte. |
| Memory warmed on mount | The memory files agents look for (CLAUDE.md, .claude/, AGENTS.md, .cursor/, MEMORY.md, …) are warmed onto local disk in the background, so a first-touch read is usually local rather than an S3 fetch. --agent {claude,codex,cursor,auto} picks the warm set. |
| Writable annotations | Per-object memory: the agent attaches reasoned notes to any object under .aimem/annot/…, co-located with the bytes they describe and travelling with the cortex — memory about a specific piece of data. |
| Metadata & provenance | Each object's S3 user metadata (user.s3.meta.*) and tags (user.s3.tags.*) are read as xattrs, pre-warmed by ls — the provenance the agent reasons over before it acts. |
| Server-side search | aimem search <cortex> -e <regex> runs RE2 regex matching (multiple -e patterns are ANDed) entirely server-side over the objects at rest — matching across the whole cortex, with the agent never downloading it. |
| Structured memory (experimental) | Records and events kept as queryable Apache Iceberg tables in the same cortex (aimem bio), so a run's activity becomes durable, queryable memory alongside the files. Every cortex is warehouse-enabled automatically — including a bucket converted with aimem cortex convert. |
| Automatic skills | Every mount teaches the agent how to use all of the above — no flags. A read-time awareness preamble is prepended to instruction files read from the mount, and the aimem Agent Skill is installed into $HOME/.agents/skills/aimem/ and $HOME/.claude/skills/aimem/. See SKILLS. |
| A vault for secrets | Secrets live in the cortex by default (aimem secret put/get/list/delete, encrypted server-side over the Memory API), or are leased from your own external store (HashiCorp Vault/OpenBao, a cloud manager) when they already live there. aimem secret provision injects them as env vars at launch. They are never written to the mount, and the store credential never reaches the agent. |
Why AIStor Memory
| Sovereign | Memory is customer data — it lives in your own MinIO AIStor cortex, compressed and KMS-encrypted when a KMS is configured, with a lifecycle you control. Never held in a vendor's cloud. |
| Real files | The actual bytes, not a rebuilt summary. What the agent writes is what it reads back, byte for byte — no model on the write path, nothing to reconstruct. |
| Portable | Change agents, models, or where they run as often as you like. The experience they earned stays put in your infrastructure and belongs to you. |
| Nothing extra to run | No vector store, no graph engine, no metadata cluster — one static binary against the object store you already operate. |
| Automatic skills | The aimem skill reaches the agent through three tiers: a read-time preamble on instruction files, an install into the agent's home, and the public minio/skills repo (npx skills add minio/skills/aimem). The first two are automatic, so the model arrives oriented. |
| AIStor-native | Built for MinIO AIStor — multi-endpoint transport, MinIO-style {1...4} brace ranges. AIStor Memory needs AIStor. |
Explore the docs
Quick start
Install the binary, mount a bucket, and run your first agent against it — five minutes from scratch.
aimem reference
The three forms of memory — workspace, long-term memory (warmup, annotations, metadata, search), and the secrets vault — the full feature surface.
Architecture
How the mount presents your cortex as files — the read and write data path, local cache, and the synthetic namespace behind memory features.
Integrations
How agent sandboxes — Codespaces, E2B, Daytona, OpenAI Codex — use AIStor Memory end-to-end.
Operations
fstab integration, logging, OpenTelemetry metrics, sandbox-provider conventions.
References
- MinIO AIStor — the object store AIStor Memory is built on.