Super Intelligence Memory

Super Intelligence Memory gives your AI agents long-term memory on AIOZ Storage. You save short statements in plain language with Record, and later ask questions in plain language with Recall. AIOZ Storage returns the saved statements that are closest in meaning to your question. You do not create embeddings, vector indexes, or vectors yourself.

This page covers the official SDKs for Go, JavaScript/TypeScript, and Python. All three call the same two API operations: Record and Recall.

How it works

The first Record in a bucket creates the memory index for you automatically.

Before you start

You need three things.

1. Access keys

Create an access key ID and secret access key in the AIOZ Storage dashboard (opens in a new tab). Every request is signed with AWS Signature Version 4 (service name s3vectors). There is no login step and no token to refresh.

2. A memory-managed vector bucket

Record and Recall only work on a vector bucket that was created with memoryManaged set to true. The SDKs cannot create this bucket, so create it once with a signed request:

curl --aws-sigv4 "aws:amz:us-east-1:s3vectors" \
  --user "$ACCESS_KEY_ID:$SECRET_ACCESS_KEY" \
  -X POST https://vector-api.aiozstorage.network/CreateVectorBucket \
  -H "Content-Type: application/json" \
  -d '{"vectorBucketName": "my-memory-bucket", "memoryManaged": true}'

A memory-managed bucket is dedicated to memory. Regular PutVectors and DeleteVectors calls on it are rejected with bucket is managed by the memory feature; use /Record instead.

3. Endpoint and region

Install

Go

go get github.com/AIOZStorage/super-intelligence-memory-go

Requires Go 1.25 or later. The package name is superintelligencememory, which is different from the last part of the module path, so import it with that name as shown in the quick start below.

JavaScript / TypeScript

npm install @aiozstorage/super-intelligence-memory

Python

pip install super-intelligence-memory

Requires Python 3.10 or later. Import it as super_intelligence_memory.

Quick start

Each example saves one statement, then asks a question about it.

Go

package main
 
import (
	"context"
	"fmt"
	"log"
	"net/http"
	"time"
 
	superintelligencememory "github.com/AIOZStorage/super-intelligence-memory-go"
)
 
func main() {
	ctx := context.Background()
 
	opts := superintelligencememory.
		DefaultApiClientOptions().
		BaseURL("https://vector-api.aiozstorage.network").
		HTTPClient(&http.Client{Timeout: 15 * time.Second}).
		Credentials("YOUR_ACCESS_KEY_ID", "YOUR_SECRET_ACCESS_KEY").
		Region("us-east-1")
 
	client, err := superintelligencememory.NewApiClient(ctx, opts)
	if err != nil {
		log.Fatal(err)
	}
 
	// Save a statement.
	rec, err := client.Memory.RecordWithContext(ctx, superintelligencememory.RecordRequest{
		VectorBucketName: superintelligencememory.PtrString("my-memory-bucket"),
		Statement:        superintelligencememory.PtrString("Deploys are frozen in December."),
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("saved:", rec.GetMemoryId())
 
	// Ask a question.
	res, err := client.Memory.RecallWithContext(ctx, superintelligencememory.RecallRequest{
		VectorBucketName: superintelligencememory.PtrString("my-memory-bucket"),
		Question:         superintelligencememory.PtrString("When can't we ship?"),
		Limit:            superintelligencememory.PtrInt32(3),
	})
	if err != nil {
		log.Fatal(err)
	}
	for _, m := range res.GetResults() {
		fmt.Printf("%.2f  %s\n", m.GetSimilarity(), m.GetStatement())
	}
}

Request structs are passed by value, and their fields are pointers. Use the Ptr* helpers (PtrString, PtrInt32, PtrBool) to fill them. client.Memory also has Record and Recall methods that do not take a context.

JavaScript / TypeScript

import SuperIntelligenceMemory = require('@aiozstorage/super-intelligence-memory');
 
const client = new SuperIntelligenceMemory({
  baseUri: 'https://vector-api.aiozstorage.network',
  accessKeyId: 'YOUR_ACCESS_KEY_ID',
  secretAccessKey: 'YOUR_SECRET_ACCESS_KEY',
  region: 'us-east-1',
});
 
(async () => {
  // Save a statement.
  const rec = await client.memory.record({
    vectorBucketName: 'my-memory-bucket',
    statement: 'Deploys are frozen in December.',
  });
  console.log('saved:', rec.memoryId);
 
  // Ask a question.
  const res = await client.memory.recall({
    vectorBucketName: 'my-memory-bucket',
    question: "When can't we ship?",
    limit: 3,
  });
  for (const m of res.results ?? []) {
    console.log(m.similarity, m.statement);
  }
})();

Python

from super_intelligence_memory import ApiClient, Configuration
from super_intelligence_memory.api import MemoryApi
from super_intelligence_memory.models import RecallRequest, RecordRequest
 
cfg = Configuration(
    host="https://vector-api.aiozstorage.network",
    access_key_id="YOUR_ACCESS_KEY_ID",
    secret_access_key="YOUR_SECRET_ACCESS_KEY",
    region="us-east-1",
)
 
with ApiClient(cfg) as api_client:
    memory = MemoryApi(api_client)
 
    # Save a statement.
    rec = memory.record(RecordRequest(
        vector_bucket_name="my-memory-bucket",
        statement="Deploys are frozen in December.",
    ))
    print("saved:", rec.memory_id)
 
    # Ask a question.
    res = memory.recall(RecallRequest(
        vector_bucket_name="my-memory-bucket",
        question="When can't we ship?",
        limit=3,
    ))
    for m in res.results or []:
        print(m.similarity, m.statement)

API reference

Both operations are POST requests with a JSON body. The SDKs build and sign these requests for you.

Record

Saves one statement in a bucket's memory. POST /Record

Response:

Recall

Finds the saved statements closest in meaning to a question. POST /Recall

Response:

Each item in results:

Good to know

Recall always returns the closest matches

Recall does not filter out weak matches. If the bucket has any memories, you get back up to limit results, even when none of them answers the question. found is false only when the bucket has no memories yet.

Decide in your own code what counts as a good match. Compare similarity across results, and test with your own data to pick a cut-off. Similarity scores are relative, so a fixed number that works for one kind of text may not work for another.

Record is not safe to repeat

Every successful Record creates a new memory with a new memoryId. If you send the same statement twice, you store it twice. For this reason the SDKs do not retry Record requests automatically. If a Record call fails with a network error or timeout, check whether the memory was saved before you try again.

A miss is not an error

Recall returns HTTP 200 with found: false when nothing matches. Only failures raise errors.

Do not follow redirects

The signature is tied to the exact request. The SDKs do not follow redirects, so a 3xx response is reported as an error instead.

Errors

Every error response has the same JSON body:

{
  "__type": "ValidationException",
  "message": "limit must be between 1 and 100"
}

Handle errors in code

Go

A failed call returns *superintelligencememory.AgentMemoryAPIError:

_, err := client.Memory.RecordWithContext(ctx, req)
var apiErr *superintelligencememory.AgentMemoryAPIError
if errors.As(err, &apiErr) {
	fmt.Println(apiErr.Type, apiErr.Message)
}

JavaScript / TypeScript

A failed call rejects with SuperIntelligenceMemory.ApiVideoError. code is the HTTP status, and problemDetails holds the error body:

try {
  await client.memory.record({ vectorBucketName: 'my-memory-bucket', statement: '' });
} catch (e) {
  if (e instanceof SuperIntelligenceMemory.ApiVideoError) {
    console.error(e.code, e.problemDetails);
  }
}

Python

A failed call raises ApiException. Read the error body from data:

from super_intelligence_memory.exceptions import ApiException
 
try:
    memory.record(RecordRequest(vector_bucket_name="my-memory-bucket", statement=""))
except ApiException as exc:
    print(exc.status, exc.data.type, exc.data.message)

Issues

bucket is not memory-managed

The bucket was created without memoryManaged: true. Create a new bucket with that setting. See Before you start.

unknown access key

Check that the access key ID is correct and belongs to the account that owns the bucket.

Signature errors after adding a trailing slash

Set the base URL without a trailing slash, for example https://vector-api.aiozstorage.network, and let the SDK build the request path. A doubled slash in the path makes the signature check fail.

embedding service unavailable

This is temporary. Wait a moment and call Recall again. For Record, check whether the statement was already saved before you retry.