Walrus Memory

Walrus Memory

Source constraint: All information in this skill is sourced from the Walrus Memory documentation and the MystenLabs/MemWal repository. When extending this skill, only pull from these sources.

Walrus Memory gives AI agents persistent, portable memory built on Walrus (decentralized storage) and Sui (onchain access control). The relayer (or the client, in the manual flow) encrypts each memory with Seal, stores it as a blob on Walrus, and indexes it with vector embeddings for semantic search. The owner controls who can read and write, with delegate keys enabling shared agent access.

Common integration mistakes:

1. Forgetting to generate an account ID and delegate key. You need both before the SDK works. Generate them at memory.walrus.xyz.
2. Not awaiting async remember jobs. remember() returns immediately with a job ID. The upload runs in the background. Use waitForRememberJob() or rememberAndWait() to confirm storage.
3. Omitting the namespace. Without it, everything goes to "default". Set a namespace per product surface to isolate memories.
4. Using the wrong relayer URL. Production (mainnet) is https://relayer.memory.walrus.xyz. Staging (testnet) is https://relayer-staging.memory.walrus.xyz.

Reference files

ts-sdk — TypeScript SDK Reference

Path: ts-sdk.md Load when: writing TypeScript code with @mysten-incubation/memwal, using MemWal, MemWalManual, or withMemWal, calling remember/recall/analyze/restore, or debugging SDK errors. Covers: Installation, three entry points (MemWal, MemWalManual, withMemWal), configuration, full API (remember, rememberAndWait, rememberBulk, recall with RecallParams, analyze, restore, health), lower-level methods, account management, AI middleware integration with Vercel AI SDK.

python-sdk — Python SDK Reference

Path: python-sdk.md Load when: writing Python code with the memwal PyPI package, using MemWal, MemWalSync, or with_memwal_langchain/with_memwal_openai middleware. Covers: Installation, async vs sync clients, env presets (prod/staging), RecallParams, ask method, LangChain and OpenAI middleware, Colab notebook.

mcp — MCP Server Reference

Path: mcp.md Load when: setting up Walrus Memory in Cursor, Claude Desktop, Claude Code, Codex, or another MCP client. Also when configuring the memwal-mcp package, debugging login/auth issues, or using Streamable HTTP transport. Covers: Installation via npx, login flow, client configs (Cursor, Claude Desktop, Claude Code, Codex), eight MCP tools, auth-required mode, default namespace, environment switching, Streamable HTTP setup.

Related skills

Routing guide

Skill Content

Key concepts

• Memory space. The isolated unit of storage, uniquely defined by owner address + namespace + app ID (package ID). Memories in one space never mix with another. Use namespaces to separate concerns (for example, personal, work, research).

• Four core operations.

  • Remember — store a memory with semantic embedding. Async: returns a job ID immediately.
  • Recall — search for memories by natural language query. Returns matches ranked by cosine distance.
  • Analyze — extract structured facts from text using an LLM. Each fact is stored as a separate memory.
  • Ask — recall + LLM reasoning. Query your memories and get an AI-generated answer. Available through the Python SDK, the relayer HTTP API (POST /api/ask), and not yet wrapped by the TypeScript SDK.

• Owner and delegates. The owner is the Sui wallet that created the account. Delegates are Ed25519 keypairs granted access by the owner. Delegates can store, recall, and decrypt, but cannot manage keys or transfer ownership. Access is enforced by a Move smart contract on Sui.

• Encryption. The relayer encrypts all memory content with Seal before it reaches Walrus; in the manual client flow the client encrypts instead, so the relayer never sees plaintext. Only the owner and authorized delegates can decrypt.

• Forget and delete. POST /api/forget deletes the vector index rows for a namespace; the encrypted Walrus blobs persist, so restore can re-index them later. For permanent blob deletion, deployments with the Security Delete API enabled offer a wallet-authenticated flow that prepares sponsored Sui deletion transactions; see Delete memories programmatically and the dashboard guide Delete old memories.

• Relayer. A backend service (Rust + TypeScript sidecar) that handles embedding, encryption, Walrus upload, and vector search behind a REST API. The managed relayer is provided by Walrus Foundation. You can also self-host.

• Restore. If the vector database is lost, the restore flow rebuilds it from Walrus by rediscovering blobs on-chain, decrypting, re-embedding, and re-indexing. Walrus is the permanent source of truth.

Architecture

Your App → SDK → Relayer → { Seal encrypt, Walrus upload, pgvector index }
                         ← { pgvector search, Walrus download, Seal decrypt }

Six components:

1. SDK (TypeScript or Python) — signs requests, calls relayer
2. Relayer (Rust + TS sidecar) — embedding, encryption, storage, search
3. Smart contract (memwal::account on Sui) — ownership, delegate keys, Seal access
4. Indexer — syncs contract events to PostgreSQL for fast lookups
5. Walrus — decentralized storage for encrypted blobs
6. PostgreSQL + pgvector — vector embeddings for semantic search

Choose your integration path

Account setup

1. Go to memory.walrus.xyz (mainnet) or staging.memory.walrus.xyz (testnet)
2. Connect your Sui wallet
3. Create a Walrus Memory account (one per Sui address)
4. Generate a delegate key (Ed25519 keypair)
5. Use the key (private key hex) and accountId (Sui object ID) in the SDK

Relayer endpoints

Contract IDs

Rate limits (managed relayer)

Point costs: remember/bulk = 10, analyze = 5, remember = 5, restore / remember/manual = 3, ask = 2, everything else (recall, recall/manual, and so on) = 1.

Rules

1. Generate account ID and delegate key first. The SDK will not work without them. Use the dashboard at memory.walrus.xyz.
2. Set a namespace explicitly. Without one, all memories go to "default". Separate by product surface, environment, or domain.
3. remember() is async. It returns a job ID immediately. Use rememberAndWait() or poll with waitForRememberJob() to confirm storage.
4. Use the correct relayer URL for your network. Mainnet: relayer.memory.walrus.xyz. Testnet: relayer-staging.memory.walrus.xyz.
5. Delegate keys are not wallets. They are Ed25519 keypairs authorized by the owner. They can store and recall but cannot manage the account.
6. All content is encrypted. The relayer encrypts with Seal by default. Use MemWalManual if you need the relayer to never see plaintext.
7. Walrus is the source of truth. If the database is lost, restore() rebuilds it from Walrus. The database is an operational cache.
8. Max 20 delegate keys per account.

Common mistakes

• Calling recall immediately after remember without waiting. The remember job is async. Wait for it to complete before recalling, or the memory will not appear in results.
• Using remember for many small facts from a paragraph. Use analyze instead. It extracts individual facts and stores each one separately for more precise recall.
• Hardcoding the relayer URL without matching the network. Mainnet accounts do not work on the staging relayer and vice versa.
• Not closing the Python client. Call await memwal.close() when done to clean up the HTTP client.
• Running MCP login in a non-interactive shell. The login command opens a browser. Run it in a real terminal with TTY, not inside an IDE's embedded terminal.
• Expecting restore() to process all blobs at once. It has a configurable limit (default: 10). Call it multiple times to restore a large memory space.