The memory API

export AETHERFY_API_KEY="afy_live_your_key_here"

import hashlib
from aetherfy_memory import MemoryClient
 
# Placeholder embedder — deterministic, 384 dimensions, NOT semantic.
# Swap in a real model. See /examples/embeddings.
def embed(text: str) -> list[float]:
    h = hashlib.sha256(text.encode()).digest()
    return [(h[i % len(h)] / 255.0) for i in range(384)]
 
# Reads AETHERFY_API_KEY from the environment; workspace defaults to "auto".
memory = MemoryClient()
 
memory.create_namespace("customer-42")
ns = memory.namespace("customer-42")
 
# add() is keyword-only and returns the point id.
memory_id = ns.add(
    text="Lives in NYC",
    vector=embed("Lives in NYC"),
    metadata={"source": "onboarding-form"},
)
print(memory_id)  # a canonical hyphenated UUID string, e.g. generated by the SDK
print(type(memory_id).__name__)  # str
 
# Several at once, one round trip.
ids = ns.add_many([
    {"text": "Prefers email over phone", "vector": embed("Prefers email over phone")},
    {"text": "Renewal is in March", "vector": embed("Renewal is in March"),
     "metadata": {"source": "crm"}},
])
print(len(ids))  # 2
 
# search() is keyword-only in Python — `vector=` is required.
results = ns.search(vector=embed("where does the customer live?"), limit=3)
for r in results:
    print(r.id, r.payload)
# <uuid> {'text': 'Lives in NYC', 'metadata': {'source': 'onboarding-form'}}
 
print(ns.count())  # 3

import { createHash } from 'node:crypto';
import { MemoryClient } from 'aetherfy-vectors';
 
// Placeholder embedder — deterministic, 384 dimensions, NOT semantic.
// Swap in a real model. See /examples/embeddings.
function embed(text: string): number[] {
  const h = createHash('sha256').update(text).digest();
  return Array.from({ length: 384 }, (_, i) => h[i % h.length] / 255);
}
 
const memory = new MemoryClient();
 
async function main() {
  await memory.createNamespace('customer-42');
  const ns = await memory.namespace('customer-42');
 
  // add() takes a single options object and resolves to the point id.
  const memoryId = await ns.add({
    text: 'Lives in NYC',
    vector: embed('Lives in NYC'),
    metadata: { source: 'onboarding-form' },
  });
  console.log(memoryId);         // a canonical hyphenated UUID string
  console.log(typeof memoryId);  // string
 
  const ids = await ns.addMany([
    { text: 'Prefers email over phone', vector: embed('Prefers email over phone') },
    { text: 'Renewal is in March', vector: embed('Renewal is in March'),
      metadata: { source: 'crm' } },
  ]);
  console.log(ids.length); // 2
 
  // search() takes the vector POSITIONALLY in JavaScript.
  const results = await ns.search(embed('where does the customer live?'), { limit: 3 });
  for (const r of results) console.log(r.id, r.payload);
  // <uuid> { text: 'Lives in NYC', metadata: { source: 'onboarding-form' } }
 
  console.log(await ns.count()); // 3
}
 
main();

from aetherfy_memory import MemoryClient
 
# Threads default to 384 dimensions. Set this if your model differs.
memory = MemoryClient(thread_vector_size=1536)
memory.create_thread("conv-99")   # no vector_size here

import { MemoryClient } from 'aetherfy-vectors';
 
const memory = new MemoryClient({ threadVectorSize: 1536 });
await memory.createThread('conv-99'); // no options here

import hashlib
from aetherfy_memory import MemoryClient
 
def embed(text: str) -> list[float]:
    h = hashlib.sha256(text.encode()).digest()
    return [(h[i % len(h)] / 255.0) for i in range(384)]
 
memory = MemoryClient()
 
memory.create_thread("conv-99")
chat = memory.thread("conv-99")
 
chat.add(role="user", content="Can you reset my password?",
         vector=embed("Can you reset my password?"))
chat.add(role="assistant", content="I've sent a reset link to your email.",
         vector=embed("I've sent a reset link to your email."))
 
# Bulk append. Threads use append_many, NOT add_many.
chat.append_many([
    {"role": "user", "content": "Got it, thanks.",
     "vector": embed("Got it, thanks.")},
])
 
for msg in chat.history(limit=20):
    print(msg.role, "|", msg.content)
# user | Can you reset my password?
# assistant | I've sent a reset link to your email.
# user | Got it, thanks.
 
# Newest first.
for msg in chat.history(limit=1, order="desc"):
    print(msg.role, "|", msg.content)
# user | Got it, thanks.
 
# Stream the whole thread without choosing a limit.
for msg in chat.iter_history(order="asc"):
    print(msg.role)
 
# Threads are searchable like namespaces.
hits = chat.search(vector=embed("password"), limit=2)
for h in hits:
    print(h.id)

import { createHash } from 'node:crypto';
import { MemoryClient } from 'aetherfy-vectors';
 
function embed(text: string): number[] {
  const h = createHash('sha256').update(text).digest();
  return Array.from({ length: 384 }, (_, i) => h[i % h.length] / 255);
}
 
const memory = new MemoryClient();
 
async function main() {
  await memory.createThread('conv-99');
  const chat = await memory.thread('conv-99');
 
  await chat.add({ role: 'user', content: 'Can you reset my password?',
                   vector: embed('Can you reset my password?') });
  await chat.add({ role: 'assistant', content: "I've sent a reset link to your email.",
                   vector: embed("I've sent a reset link to your email.") });
 
  // Bulk append. Threads use appendMany, NOT addMany.
  await chat.appendMany([
    { role: 'user', content: 'Got it, thanks.', vector: embed('Got it, thanks.') },
  ]);
 
  for (const msg of await chat.history({ limit: 20 })) {
    console.log(msg.role, '|', msg.content);
  }
  // user | Can you reset my password?
  // assistant | I've sent a reset link to your email.
  // user | Got it, thanks.
 
  for (const msg of await chat.history({ limit: 1, order: 'desc' })) {
    console.log(msg.role, '|', msg.content);
  }
  // user | Got it, thanks.
 
  for await (const msg of chat.iterHistory({ order: 'asc' })) {
    console.log(msg.role);
  }
 
  const hits = await chat.search(embed('password'), { limit: 2 });
  for (const h of hits) console.log(h.id);
}
 
main();

# Python — `vector` MUST be a keyword. search(embed("x")) raises TypeError.
results = ns.search(
    vector=embed("query text"),
    limit=10,
    offset=0,
    filter={"must": [{"key": "metadata.source", "match": {"value": "crm"}}]},
    with_payload=True,
    with_vectors=False,
    score_threshold=None,
    search_params=None,
)

// JavaScript — vector first, everything else in one options object.
const results = await ns.search(embed('query text'), {
  limit: 10,
  offset: 0,
  filter: { must: [{ key: 'metadata.source', match: { value: 'crm' } }] },
  withPayload: true,
  withVectors: false,
});

from aetherfy_memory import MemoryClient
 
memory = MemoryClient()
 
if not memory.namespace_exists("customer-42"):
    memory.create_namespace("customer-42")
 
print([n for n in memory.list_namespaces()])
print(memory.delete_namespace("customer-42"))

import { MemoryClient } from 'aetherfy-vectors';
 
const memory = new MemoryClient();
 
async function main() {
  if (!(await memory.namespaceExists('customer-42'))) {
    await memory.createNamespace('customer-42');
  }
  console.log(await memory.listNamespaces());
  console.log(await memory.deleteNamespace('customer-42'));
}
 
main();

^[a-zA-Z0-9][a-zA-Z0-9._-]{0,254}$

# Raises ValueError immediately — no request is sent.
ns.add(text="hello", vector=embed("hello"), metadata={"text": "shadow"})

// Throws TypeError immediately — no request is sent.
await ns.add({ text: 'hello', vector: embed('hello'), metadata: { text: 'shadow' } });

from aetherfy_memory import MemoryClient
from aetherfy_memory.exceptions import NamespaceAlreadyExistsError
 
memory = MemoryClient()
try:
    memory.create_namespace("customer-42")
except NamespaceAlreadyExistsError:
    pass

import { MemoryClient, NamespaceAlreadyExistsError } from 'aetherfy-vectors';
 
const memory = new MemoryClient();
try {
  await memory.createNamespace('customer-42');
} catch (e) {
  if (!(e instanceof NamespaceAlreadyExistsError)) throw e;
}