Skip to content

api-reference.md

Latest commit

 

History

History
245 lines (171 loc) · 6.84 KB

api-reference.md

File metadata and controls

245 lines (171 loc) · 6.84 KB
title API Reference

See also:

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 http://localhost:8000 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(query, limit?, namespace?): Promise<RecallResult>

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

  • limit defaults to 10

Returns:

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

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 50

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.

Returns: { status: string, version: string }

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
  • sealKeyServers lets the client override the built-in SEAL key server object IDs
  • 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 MemWal
  • 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)

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