Skip to main content

Headless SDK Setup

A server or agent runtime has no human to click through a wallet or paste a key at a prompt. The Walrus Memory SDK initializes entirely from configuration, so you can drop it into a backend service, a cron job, or an autonomous agent. For the full write-confirm-recall loop that builds on this setup, see Agent Storage Loop.

Generate credentials once​

The SDK authenticates every request with an Ed25519 delegate key tied to a MemWalAccount object on Sui. Generate the account ID and delegate key once through the dashboard, then store them as secrets:

This is the only step that involves a browser. Your runtime never opens one.

Initialize from the environment​

Load the credentials from environment variables and construct the client at startup. Call health() to confirm the relayer is reachable before your service starts serving traffic:

import { MemWal } from "@mysten-incubation/memwal";

function requireEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing required env var: ${name}`);
  return value;
}

const memwal = MemWal.create({
  key: requireEnv("MEMWAL_PRIVATE_KEY"),
  accountId: requireEnv("MEMWAL_ACCOUNT_ID"),
  // Mainnet relayer. Use https://relayer-staging.memory.walrus.xyz for Testnet.
  serverUrl: "https://relayer.memory.walrus.xyz",
  namespace: "service-memory",
});

// Confirm the relayer is reachable at boot.
await memwal.health();
note

health() is an unauthenticated liveness and version check. It confirms the relayer is reachable, but it does not validate your delegate key or account ID. A bad key or account ID surfaces on the first authenticated call, such as remember or recall. If you want to validate credentials at boot, make a cheap authenticated call, for example a recall with a trivial query, and handle its error.

The MemWal.create config takes 4 fields:

PropertyTypeRequiredDescription
keystringYesEd25519 delegate private key in hex
accountIdstringYesMemWalAccount object ID on Sui
serverUrlstringNoRelayer URL for your network. Pass it explicitly so the target network is unambiguous
namespacestringNoDefault namespace, falls back to "default"
note

The SDK reads the delegate key from the key config field, not from any specific environment variable. The examples in these docs use both MEMWAL_PRIVATE_KEY and MEMWAL_KEY as the variable name for that value. Pick one name and use it consistently across your project.

warning

Recall is scoped per account plus namespace. Never hardcode an account ID copied from docs or another project, and never share one delegate key across tenants that should not read each other's memories. Load every credential from the environment.

When to use the manual client​

The default MemWal client lets the relayer handle embedding and Seal encryption on your behalf, which is the right choice for most runtimes. Use MemWalManual only when the runtime must hold its own keys and keep plaintext entirely client-side. With the manual client, the runtime embeds and Seal-encrypts locally, then the relayer uploads the resulting ciphertext to Walrus and stores the vector row, so the relayer never sees plaintext. It requires a few more fields, including a Sui key that authorizes Seal:

import { MemWalManual } from "@mysten-incubation/memwal/manual";

const manual = MemWalManual.create({
  key: requireEnv("MEMWAL_PRIVATE_KEY"),
  accountId: requireEnv("MEMWAL_ACCOUNT_ID"),
  packageId: requireEnv("MEMWAL_PACKAGE_ID"),
  serverUrl: "https://relayer.memory.walrus.xyz",
  // The Sui key authorizes Seal encryption and decryption. The relayer still
  // handles the Walrus upload, registration, search, and restore.
  suiPrivateKey: requireEnv("SUI_PRIVATE_KEY"),
  embeddingApiKey: requireEnv("OPENAI_API_KEY"),
  suiNetwork: "mainnet",
  namespace: "service-memory",
});

For the complete client-managed flow, see MemWalManual.

References​