Memory Bucket API

A Memory Bucket is a bucket that AIStor serves through the Memory API. The Memory API is the third AIStor API family, alongside the Object Store (S3) and Tables APIs. The aimem commands bucket, secret, and search are clients of this API. The mount reads and writes ordinary S3 objects in the same bucket.

You do not need to call this API to use aimem. This page is a reference for the requests the mount and the commands send.

The Memory Bucket storage contract

AIStor applies a storage contract to every write to a Memory Bucket, whether the write comes through the Memory API or a plain S3 PutObject:

• Hidden. A Memory Bucket does not appear in a regular mc ls alias/ listing, like a Tables warehouse bucket. It is still a real bucket that replication and root can see.
• Always compressed. Every object is compressed (minlz), whatever its content type.
• Encrypted at rest when a KMS is configured. With a KMS, AIStor creates the Memory Bucket with default SSE encryption, so every object is encrypted with the KMS at rest and decrypted on read. Without a KMS, objects are compressed but stored unencrypted, and the server logs a warning. SSE-C is rejected: objects are encrypted with the Memory Bucket's own key, not a customer-supplied one.
• Always stamped. The server adds memory metadata to every object on each write, as ordinary user metadata (x-amz-meta-mem-cortex, x-amz-meta-mem-format).
• Created new or upgraded. You normally create a Memory Bucket through the Memory API. You can also upgrade an existing bucket in place (upgradeExisting: true or aimem convert). The upgrade does not compress, encrypt, or stamp objects written before it. Instead, the Memory Bucket records upgraded: true. You cannot downgrade a Memory Bucket.

Root credentials can still GET and PUT objects in a Memory Bucket over plain S3. The storage contract still applies to those writes.

The Memory Bucket

A Memory Bucket is the top-level container, like a Tables warehouse. It holds everything an agent keeps: workspace files at the root, secrets under .secrets/, and the search and structured-memory features described below.

Because a Memory Bucket takes the Tables warehouse role, it is also an Iceberg warehouse. Structured memory (records and events stored as tables through aimem bio) works on any Memory Bucket, new or converted. You do not set up a separate warehouse. aimem bio runs a separate aimem-bio binary (see the CLI reference).

API endpoints

All Memory API requests use the /_mem/v1 path prefix and SigV4 authorization. Each operation has its own memory:* IAM policy action, so you can grant access to a Memory Bucket to credentials other than the owner's.

Memory Bucket

CreateCortex takes a JSON body. Set upgradeExisting: true to convert an existing bucket. Omit kmsKeyId to use the server default key (SSE-S3) instead of a specific SSE-KMS key:

{
  "name": "project-memory",
  "kmsKeyId": "optional-kms-key",
  "upgradeExisting": false
}

ListCortexes returns results sorted by name and cached for about 1 second. It supports ?search=<substr> and pagination with ?pageToken= and ?pageSize= (default 100, maximum 1000). When more results remain, the response includes a nextPageToken.

Secrets (the Vault form)

Secret values live under the Memory Bucket's reserved .secrets/ prefix. Each file is envelope-encrypted with the KMS. A plain S3 GET returns ciphertext; an authorized Memory API GetSecret returns the plaintext, decrypted by the server.

Search over a Memory Bucket

Search runs RE2 regular expressions on the server, over the objects stored in a Memory Bucket. The server decrypts and decompresses each object in place, skips blocks that cannot match, and returns only the matches. An agent can search its long-term memory without downloading the Memory Bucket.

How aimem verbs map to the API

The workspace makes no Memory API calls. Mounted files are ordinary S3 objects with path-shaped keys at the root of the Memory Bucket.

Data layout

In a Memory Bucket, workspace files sit at the root. Three prefixes are reserved: only the Memory API manages them, and direct S3 writes to them are rejected.

project-memory/
├── <workspace files…>   workspace: plain path-shaped keys at the root
├── .cortex/             reserved: Memory Bucket write-path policy (replicated)
├── .secrets/<name>      reserved: Secrets API — envelope ciphertext
└── .mem/                reserved: future Memory API use

Because .mem/ is reserved now, a workspace file can never conflict with future Memory API use of that prefix.