Skip to main content
The relayer is the backend that turns SDK calls into memory operations. Using a delegate key signed by the client, it handles the critical workflows — embedding, encryption, storage, and search — on behalf of the user.

​
What It Does

  • Authenticates requests by verifying Ed25519 signatures against onchain delegate keys, then resolving the owner and account context
  • Generates embeddings for text using an OpenAI-compatible API (default model: text-embedding-3-small, 1536 dimensions)
  • Encrypts and decrypts data through the SEAL sidecar, bound to the owner’s address and the MemWal package ID
  • Uploads and downloads encrypted blobs to Walrus, with the server wallet covering storage costs
  • Stores and searches vectors in PostgreSQL (pgvector), scoped by memory space (owner + namespace)
  • Orchestrates higher-level flows like analyze (LLM-based fact extraction using gpt-4o-mini) and ask (memory-augmented Q&A)
  • Restores memory spaces by querying onchain blobs, decrypting, re-embedding, and re-indexing anything missing from the local database
  • Cleans up expired blobs reactively — when Walrus returns 404 during recall, the relayer deletes the stale vector entries from the database

​
Architecture

The relayer is a Rust service (Axum) that manages a TypeScript sidecar process for SEAL and Walrus operations that require the @mysten/seal and @mysten/walrus SDKs. The sidecar is started automatically when the Rust server boots and communicates over HTTP on localhost:9000 (configurable via SIDECAR_URL). If the sidecar fails to start, the relayer exits immediately.

​
Key Pool

For the analyze endpoint (which stores multiple facts concurrently), the relayer supports a pool of Sui private keys (SERVER_SUI_PRIVATE_KEYS). Each concurrent Walrus upload uses a different key from the pool in round-robin order, bypassing per-signer serialization and enabling parallel uploads.

​
Single-Instance Design

Each relayer deployment is tied to a single MemWal package ID (MEMWAL_PACKAGE_ID). The package ID is used for SEAL encryption key derivation and Walrus blob metadata. Queries in the vector database are scoped by owner + namespace, while the package ID provides cross-deployment isolation at the encryption layer.
The current relayer does not support multi-tenancy across multiple package IDs. If you deploy a separate MemWal contract, you need to run a separate relayer instance with its own database.

​
Trust Boundary

In the default SDK path, the relayer sees plaintext data because it handles encryption and embedding on your behalf. This is a deliberate trade-off for developer experience — it means Web2 developers don’t need to manage cryptographic operations. If you need to minimize this trust, you can self-host the relayer or use the manual client flow to handle encryption and embedding entirely on the client side. See Trust & Security Model for the full breakdown.