api-reference.md

title	API Reference
description	Complete API reference for the Walrus Memory SDK, including method signatures, config fields, and return types for MemWal, MemWalManual, withMemWal, account management, and utility functions.
keywords	Walrus Memory MemWal API reference method signatures SDK methods config
goal	description requires Look up the exact method signature, parameter types, return type, and thrown errors for any Walrus Memory SDK method or config field before writing code that calls it. has_frontmatter label title description keywords Has required frontmatter fields min_words label 300 Needs more content depth has_questions label true Needs questions for AI search visibility has_answer label true Needs answer summary for AI citation
questions	What are the method signatures for the Walrus Memory SDK? What config options does MemWal.create accept? What does the recall method return in Walrus Memory?
answer	The Walrus Memory SDK API includes MemWal (remember, recall, analyze, restore, health, rememberBulk, and more), MemWalManual (rememberManual, recallManual, restore), withMemWal (AI SDK middleware), account management utilities (createAccount, addDelegateKey, removeDelegateKey, generateDelegateKey), and utility functions for delegate key operations.

See also:

• Configuration
• Relayer API

MemWal.create(config)

MemWal.create(config: MemWalConfig): MemWal

Config:

Property	Type	Required	Default	Notes
key	string	Yes	—	Ed25519 delegate private key in hex
accountId	string	Yes	—	MemWalAccount object ID on Sui
serverUrl	string	No	https://relayer.memory.walrus.xyz	Relayer URL
namespace	string	No	"default"	Default namespace for memory isolation

For the full config surface, see Configuration.

MemWal Methods

remember(text, namespace?): Promise<RememberAcceptedResult>

Submit one memory through the relayer. The method returns after the relayer creates a background job; embedding, SEAL encryption, Walrus upload, and vector indexing continue asynchronously.

Returns:

{
  job_id: string; // Polling id
  status: string; // Usually "running"
}

rememberAndWait(text, namespace?, opts?): Promise<RememberResult>

Submit one memory and poll until the background job completes.

Returns:

{
  id: string;        // Stable job id/vector row id
  job_id: string;    // Polling id
  blob_id: string;   // Walrus blob ID
  owner: string;     // Owner Sui address
  namespace: string; // Namespace used
}

waitForRememberJob(jobId, opts?): Promise<RememberResult>

Poll a previously accepted remember job until it reaches done or failed.

rememberBulk(items): Promise<RememberBulkAcceptedResult>

Submit up to 20 memories in one request and return the accepted job IDs immediately.

Returns:

{
  job_ids: string[];
  total: number;
  status: string; // Usually "running"
}

rememberBulkAndWait(items, opts?): Promise<RememberBulkResult>

Submit a bulk remember request and wait until every job reaches a terminal state.

recall(params): Promise<RecallResult>

Search for memories matching a natural language query, scoped to owner + namespace.

• Preferred form: recall({ query, limit?, topK?, namespace?, maxDistance? })
• limit defaults to 10; topK is an alias and wins when both are set
• Legacy positional forms still work: recall(query), recall(query, limit), recall(query, limit, namespace), and recall(query, options)
• maxDistance filters weak matches client-side by dropping results where distance >= maxDistance

Returns:

{
  results: Array<{
    blob_id: string;   // Walrus blob ID
    text: string;      // Decrypted plaintext
    distance: number;  // Cosine distance (lower = more similar)
  }>;
  total: number;
}

distance is cosine distance — lower is more similar.

analyze(text, namespace?): Promise<AnalyzeResult>

Extract memorable facts from text using an LLM, then return accepted background jobs for storing each fact.

Returns:

{
  job_ids: string[];
  facts: Array<{
    text: string;     // Extracted fact
    id: string;       // Same value as job_id
    job_id: string;   // Polling id
  }>;
  fact_count: number;
  status: string;     // Usually "pending"
  owner: string;
}

Use analyzeAndWait(text, namespace?, opts?) to wait for every extracted fact job to finish and return per-job storage results.

restore(namespace, limit?): Promise<RestoreResult>

Rebuild missing indexed entries for one namespace from Walrus. Incremental — only re-indexes blobs that aren't already in the local database.

• limit defaults to 10

Returns:

{
  restored: number;   // Entries newly indexed
  skipped: number;    // Entries already in DB
  total: number;      // Total blobs found on-chain
  namespace: string;
  owner: string;
}

health(): Promise<HealthResult>

Check relayer health. Does not require authentication — a successful response confirms the relayer is reachable, not that your key/accountId are valid. A signed call (e.g. remember(), recall()) can still fail with 401 immediately after a passing health().

Returns: { status: string, version: string, relayerVersion?: string, apiVersion?: string, minSupportedSdk?: ... }

compatibility(): Promise<RelayerVersionMetadata>

Fetch and validate the relayer compatibility contract from /version. Protected SDK calls run this check before signing the first request and raise MemWalCompatibilityError when the SDK/relayer pair is unsupported.

getPublicKeyHex(): Promise<string>

Return the hex-encoded public key for the current delegate key.

Lower-level methods

These exist on the MemWal class for advanced use cases:

Method	Description
rememberManual({ blobId, vector, namespace? })	Register a pre-uploaded blob ID with a pre-computed vector
recallManual({ vector, limit?, namespace? })	Search with a pre-computed query vector (returns blob IDs, no decryption)
embed(text)	Generate an embedding vector for text (no storage)

MemWalManual

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

See MemWalManual usage for the full setup and flow details.

rememberManual(text, namespace?): Promise<RememberManualResult>

Embed locally, SEAL encrypt locally, send encrypted payload + vector to relayer for Walrus upload and vector registration.

recallManual(query, limit?, namespace?): Promise<RecallManualResult>

Embed locally, search via relayer, download from Walrus, SEAL decrypt locally. Returns decrypted text results.

restore(namespace, limit?): Promise<RestoreResult>

Same as MemWal.restore() — delegates to the relayer.

isWalletMode: boolean

Whether this client uses a connected wallet signer (vs. raw keypair).

Config notes

• suiNetwork defaults to mainnet
• sealServerConfigs lets the client configure independent or committee SEAL servers; committee entries require aggregatorUrl
• sealKeyServers remains supported as a legacy independent key server object ID override
• All @mysten/* peer dependencies are loaded dynamically — only needed if you use MemWalManual

withMemWal

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

Wraps a Vercel AI SDK model with automatic memory recall and save.

Before generation:

• Reads the last user message
• Runs recall() against Walrus Memory
• Filters by minimum relevance (minRelevance, default 0.3)
• Injects matching memories into the prompt as a system message

After generation:

• Optionally runs analyze() on the user message (fire-and-forget)
• Saves extracted facts asynchronously

Options (extends MemWalConfig):

Option	Default	Description
maxMemories	5	Max memories to inject per request
autoSave	true	Auto-save new facts from conversation
minRelevance	0.3	Minimum similarity score (0–1) to include a memory
debug	false	Enable debug logging

See Configuration for all options.

Account Management

import {
  createAccount,
  addDelegateKey,
  removeDelegateKey,
  generateDelegateKey,
} from "@mysten-incubation/memwal/account";

Function	Description
generateDelegateKey()	Generate a new Ed25519 keypair (returns privateKey, publicKey, suiAddress)
createAccount(opts)	Create a new MemWalAccount on-chain (one per Sui address)
addDelegateKey(opts)	Add a delegate key to an account (owner only)
removeDelegateKey(opts)	Remove a delegate key from an account (owner only)

addDelegateKey and removeDelegateKey require the shared registryId alongside the package and account IDs.

Utility Functions

import { delegateKeyToSuiAddress, delegateKeyToPublicKey } from "@mysten-incubation/memwal";

Function	Description
delegateKeyToSuiAddress(privateKeyHex)	Derive the Sui address from a delegate private key
delegateKeyToPublicKey(privateKeyHex)	Get the 32-byte public key from a delegate private key