Integrations

Each agent runtime runs the agent in a sandbox that is deleted when the run ends, and everything the agent did is lost with it. AIStor Memory mounts an AIStor Memory Bucket in the sandbox. The agent works in that mount and keeps its memory there, so its work outlives the sandbox and the next sandbox mounts the same bucket.

One Memory Bucket holds three forms of memory:

• Workspace: the files the agent is working on, edited with the tools it already uses (git, editors, sqlite, build tools).
• Long-term memory: what the agent learned. This is the memory files agents look for (CLAUDE.md, AGENTS.md, MEMORY.md), writable per-object annotations, read-only object metadata and tags, and server-side search across the bucket.
• Vault: the secrets an approved agent needs, given to the agent when it starts and never written to the mount.

Choose an integration

Codex Cloud, the hosted offering, is not supported: its container-snapshot lifecycle does not work with a running FUSE process. Self-hosted Codex sandboxes are supported.

Before you mount

The mount command

Most integrations run the same command in the sandbox: the Memory Bucket, the mountpoint, and one --config YAML file that holds the settings. Credentials (AIMEM_ACCESS_KEY, AIMEM_SECRET_KEY, and the optional AIMEM_SESSION_TOKEN) stay in the environment, never in a flag, the YAML, or an image. Each integration's aimem-mount wrapper writes the config from the sandbox's environment variables, so the runtime only has to set those variables:

# /etc/aimem/mount.yaml — written by the wrapper from the sandbox env
version: "1.0"
endpoint_url: https://aistor.example.com # from $AIMEM_ENDPOINT
local: /var/cache/aimem
agent: auto # from $AIMEM_AGENT
foreground: true

aimem "${AIMEM_BUCKET}" "${AIMEM_MOUNTPOINT:-/workspace}" --config /etc/aimem/mount.yaml

The version: "1.0" key is required and must be a quoted string. Some YAML keys also have a flag, and a few have an AIMEM_* environment variable, for sandboxes that carry no config file. For example, set the staging directory with --local "${AIMEM_LOCAL}" or AIMEM_LOCAL. Keys such as allow_other, uid, and gid exist only in the file. See Quick start and Configuration for all settings.

The integrations differ only in how the binary gets into the sandbox (an image, a devcontainer, or a host install) and how the environment variables are set.

The staging directory is required

AIStor Memory writes each open file to a local staging directory and uploads it to the bucket when the file is closed. This is what lets git, editors, sqlite, and other tools work on object storage. mmap and copy_file_range return ENOSYS, but the kernel falls back to read and write on the staged file, so tools that map memory still work.

aimem does not choose a staging directory for you. Set it with the local: key in the --config file, the --local <DIR> flag, or the AIMEM_LOCAL environment variable. If you set more than one, the flag or environment variable wins. Size it for the files the agent has open for writing at once; NVMe is recommended. See How memory works.

What the agent gets

• A durable workspace. The agent's files are stored in the Memory Bucket, so you can resume the same workspace in a later session.

• Memory ready at mount. CLAUDE.md, .claude/, AGENTS.md, .cursorrules, and similar files are copied to local disk when the bucket is mounted, so the agent's first read is fast.

• Secrets at launch. aimem secret provision fetches the granted secrets and starts the agent with them as environment variables. It reads them from the Memory Bucket (--bucket) or from an HTTP secret store such as HashiCorp Vault or OpenBao (--store-endpoint). The source credential stays with the launcher and is removed from the agent's environment, and aimem stores no secrets locally.

• The aimem skill. Each mount teaches the agent how to use all of the above, with no flags:

  1. Instruction files (CLAUDE.md, AGENTS.md, .cursorrules) read from the mount start with a short AIStor Memory usage preamble, added in memory only. It is skipped when the mount root is a git repository. To turn it off, set AIMEM_PREAMBLE_OVERLAY=0.
  2. The skill is installed in $HOME/.agents/skills/aimem/ (Codex CLI, Cursor, Gemini CLI, Copilot) and $HOME/.claude/skills/aimem/ (Claude Code). The install works offline and never overwrites existing files. To turn it off, set AIMEM_INSTALL_SKILL=0.
  3. For an agent that runs outside the sandbox, run npx skills add minio/skills/aimem, which installs the skill from github.com/minio/skills.

  See How memory works for details.