From eb4b206c5cca4f89e0eb770b7992e61ee6126e1f Mon Sep 17 00:00:00 2001 From: Aaron1924 Date: Wed, 25 Mar 2026 22:44:37 +0700 Subject: [PATCH 1/5] docs: update managed relayer docs --- docs/docs.json | 4 +- .../architecture/core-components.md | 2 +- .../architecture/data-flow-security-model.md | 4 +- docs/getting-started/choose-your-path.md | 22 +++++---- docs/getting-started/quick-start.md | 45 +++++++++++++------ docs/getting-started/what-is-memwal.md | 8 +++- docs/relayer/public-relayer.md | 12 ++--- docs/relayer/self-hosting.md | 4 +- docs/sdk/quick-start.md | 2 +- 9 files changed, 65 insertions(+), 38 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index 19194ada..412ff368 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -24,13 +24,13 @@ "links": [ { "label": "GitHub", - "href": "https://github.com/CommandOSSLabs/memwal" + "href": "https://github.com/MystenLabs/MemWal" } ] }, "footer": { "socials": { - "github": "https://github.com/CommandOSSLabs/memwal" + "github": "https://github.com/MystenLabs/MemWal" } }, "navigation": { diff --git a/docs/fundamentals/architecture/core-components.md b/docs/fundamentals/architecture/core-components.md index 28cd8cea..a831e7fe 100644 --- a/docs/fundamentals/architecture/core-components.md +++ b/docs/fundamentals/architecture/core-components.md @@ -66,7 +66,7 @@ This means Web2 developers can integrate MemWal without touching wallets, signin Because the relayer handles encryption and plaintext data, you are placing trust in the relayer operator. This is a deliberate trade-off for developer experience. If you need full control over that trust boundary, you can [self-host](/relayer/self-hosting) your own relayer, or use the [manual client flow](/sdk/usage) to handle encryption and embedding entirely on the client side (recommended for Web3-native users). See [Trust & Security Model](/fundamentals/architecture/data-flow-security-model) for details. -You can use the [public relayer](/relayer/public-relayer) to get started, [self-host](/relayer/self-hosting) your own, or use the manual client flow for full client-side control. +You can use the [managed relayer](/relayer/public-relayer) to get started, [self-host](/relayer/self-hosting) your own, or use the manual client flow for full client-side control. ## MemWal Smart Contract diff --git a/docs/fundamentals/architecture/data-flow-security-model.md b/docs/fundamentals/architecture/data-flow-security-model.md index 87ad249e..d17dd3d1 100644 --- a/docs/fundamentals/architecture/data-flow-security-model.md +++ b/docs/fundamentals/architecture/data-flow-security-model.md @@ -33,11 +33,11 @@ You have options depending on your trust requirements: | Option | Trust level | What the relayer sees | |--------|------------|----------------------| -| **Public relayer** | You trust the MemWal team | Plaintext content, embeddings, decrypted results | +| **Managed relayer** | You trust Walrus Foundation | Plaintext content, embeddings, decrypted results | | **Self-hosted relayer** | You trust your own infra | Same as above, but under your control | | **Manual client flow** | Minimal trust | Only encrypted payloads and pre-computed vectors — never plaintext | -- **Use the public relayer** — convenient for getting started and prototyping. You trust the MemWal team to operate it responsibly. +- **Use the managed relayer** — convenient for getting started and prototyping. You trust Walrus Foundation to operate it responsibly. - **Self-host your own relayer** — you control the infrastructure, so the trust boundary is entirely yours. No third party sees your data. - **Manual client flow** — use `MemWalManual` to handle encryption and embedding entirely on the client side. The relayer only sees encrypted payloads and vectors, never plaintext. This is recommended for Web3-native users who want full control over their data and are comfortable managing keys, signing, and SEAL operations directly. diff --git a/docs/getting-started/choose-your-path.md b/docs/getting-started/choose-your-path.md index 9cf14706..0bedb56b 100644 --- a/docs/getting-started/choose-your-path.md +++ b/docs/getting-started/choose-your-path.md @@ -5,7 +5,7 @@ title: "Choose Your Path" MemWal supports several integration modes depending on how much control you need. Pick the one that fits your use case. -These paths aren't mutually exclusive. You can combine them — for example, use the **Default SDK** with the **AI Middleware**, or start with the **Public Relayer** and move to **Self-Hosting** later. They all share the same backend and data layer. +These paths aren't mutually exclusive. You can combine them - for example, use the **Default SDK** with the **AI Middleware**, or start with the **Managed Relayer** and move to **Self-Hosting** later. They all share the same backend and data layer. ## 1. Default SDK @@ -17,20 +17,24 @@ Use `@mysten-incubation/memwal` when you want the fastest working integration. Go to: [SDK Overview](/sdk/overview) -## 2. Public Relayer +## 2. Managed Relayer -Use this when you want to evaluate MemWal without running the backend yourself. +Use a hosted relayer, or deploy your own [self-hosted relayer](/relayer/self-hosting) with access to a wallet funded with WAL and SUI. + + +Following endpoints are provided as public good by Walrus Foundation. + | Network | Relayer URL | -|---|---| -| **Testnet** (staging) | `https://relayer.staging.memwal.ai` | -| **Mainnet** (production) | `https://relayer.memwal.ai` | +| --- | --- | +| **Production** (mainnet) | `https://relayer.memwal.ai` | +| **Staging** (testnet) | `https://relayer.staging.memwal.ai` | -Go to: [Public Relayer](/relayer/public-relayer) +Go to: [Managed Relayer](/relayer/public-relayer) ## 3. Manual Client Flow -Use `@mysten-incubation/memwal/manual` when you want full client-side control over encryption and embeddings. Recommended for Web3-native users who want to minimize trust in the relayer — it never sees your plaintext data. +Use `@mysten-incubation/memwal/manual` when you want full client-side control over encryption and embeddings. Recommended for Web3-native users who want to minimize trust in the relayer - it never sees your plaintext data. - client handles embeddings and SEAL encryption locally - relayer only sees encrypted payloads and vectors @@ -45,6 +49,6 @@ Go to: [AI Integration](/sdk/usage/with-memwal) ## 5. Self-Host the Relayer -Use this when you need full control over the trust boundary — your infrastructure, your credentials, no third party sees your data. +Use this when you need full control over the trust boundary - your infrastructure, your credentials, no third party sees your data. Go to: [Self-Hosting](/relayer/self-hosting) diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md index 2742eec2..7e541071 100644 --- a/docs/getting-started/quick-start.md +++ b/docs/getting-started/quick-start.md @@ -7,11 +7,6 @@ The fastest way to get MemWal running is through the TypeScript SDK. ## Prerequisites - [Node.js](https://nodejs.org/) v18+ or [Bun](https://bun.sh/) v1+ -- A delegate key (Ed25519 private key in hex) -- A MemWalAccount object ID on Sui -- A relayer URL — use a [public relayer](/relayer/public-relayer) or your own [self-hosted relayer](/relayer/self-hosting) - - Production (mainnet): `https://relayer.memwal.ai` - - Staging (testnet): `https://relayer.staging.memwal.ai` ## Quick Start @@ -95,6 +90,38 @@ The fastest way to get MemWal running is through the TypeScript SDK. + + ### Generate your account ID and delegate key + + Create a MemWal account ID and delegate private key for your SDK client using one of the hosted endpoints below. + + + The following endpoints are provided as a public good by Walrus Foundation. + + + | App | URL | + | --- | --- | + | **MemWal Playground** | [memwal.ai](https://memwal.ai) | + | **Walrus-hosted Playground** | [memwal.wal.app](https://memwal.wal.app) | + + For the contract-based setup flow, see [Delegate Key Management](/contract/delegate-key-management) and [MemWal smart contract](/contract/overview). + + + + ### Choose a relayer + + Use a hosted relayer, or deploy your own [self-hosted relayer](/relayer/self-hosting) with access to a wallet funded with WAL and SUI: + + + Following endpoints are provided as public good by Walrus Foundation. + + + | Network | Relayer URL | + | --- | --- | + | **Production** (mainnet) | `https://relayer.memwal.ai` | + | **Staging** (testnet) | `https://relayer.staging.memwal.ai` | + + ### Configure the SDK @@ -110,14 +137,6 @@ The fastest way to get MemWal running is through the TypeScript SDK. namespace: "my-app", }); ``` - - - Use `https://relayer.memwal.ai` for production (mainnet) or `https://relayer.staging.memwal.ai` for staging (testnet). See [Public Relayer](/relayer/public-relayer) for details. - - - - If you are self-hosting and do not have `MEMWAL_ACCOUNT_ID` yet, see [Self-Hosting](/relayer/self-hosting) for the account-creation and delegate-key setup flow. - diff --git a/docs/getting-started/what-is-memwal.md b/docs/getting-started/what-is-memwal.md index d89fe1d3..120021e6 100644 --- a/docs/getting-started/what-is-memwal.md +++ b/docs/getting-started/what-is-memwal.md @@ -3,6 +3,10 @@ title: "What is MemWal?" description: "Persistent, verifiable memory for AI agents" --- + +MemWal is currently in beta and actively evolving. While fully usable today, we continue to refine the developer experience and operational guidance. We welcome feedback from early builders as we continue to improve the product. + + MemWal introduces a long-term, verifiable memory layer on Walrus, allowing agents to remember, share, and reuse information reliably. @@ -98,7 +102,7 @@ And many more — check out the example apps below to see MemWal in action. ## Example Apps -The repo ships with ready-to-run apps in the [`/apps`](https://github.com/CommandOSSLabs/memwal/tree/main/apps) directory: +The repo ships with ready-to-run apps in the [`/apps`](https://github.com/MystenLabs/MemWal/tree/main/apps) directory: - **Playground** — dashboard demo for MemWal - **Chatbot** — AI chat app with persistent memory across sessions @@ -120,7 +124,7 @@ See [Example Apps](/examples/example-apps) for short code examples from each app Quickstart, usage patterns, AI integration, and examples - Public relayer, installation and setup, self-hosting + Managed relayer, installation and setup, self-hosting Onchain ownership model, delegate key management, permissions diff --git a/docs/relayer/public-relayer.md b/docs/relayer/public-relayer.md index 56b11d86..25a239c2 100644 --- a/docs/relayer/public-relayer.md +++ b/docs/relayer/public-relayer.md @@ -1,10 +1,10 @@ --- -title: "Public Relayer" +title: "Managed Relayer" --- -The public relayer is a managed MemWal deployment for teams that want to get started without running infrastructure. If a public relayer endpoint is available for your environment, it gives you the fastest path to integration. +A managed relayer is a simpler experience for teams that want to get started without running infrastructure. If a managed relayer endpoint is available for your environment, it gives you the fastest path to integration. -## Endpoints +## Walrus Foundation hosted endpoints | Network | Relayer URL | |---|---| @@ -26,9 +26,9 @@ const memwal = MemWal.create({ ## What to Know -- **Shared App ID** - all users of the public relayer share the same MemWal package ID. Your data is isolated by your own `owner + namespace` (Memory Space), but the underlying deployment is shared. -- **Trust assumption** - the relayer sees plaintext during encryption and embedding. By using the public relayer, you're trusting the Mysten-hosted instance with that data. See [Trust & Security Model](/fundamentals/architecture/data-flow-security-model) for details. -- **Availability** - the public relayer is a managed beta service. There are no SLA guarantees. +- **Shared App ID** - all users of the managed relayer share the same MemWal package ID. Your data is isolated by your own `owner + namespace` (Memory Space), but the underlying deployment is shared. +- **Trust assumption** - the relayer sees plaintext during encryption and embedding. By using the managed relayer, you're trusting the Walrus Foundation-hosted instance with that data. See [Trust & Security Model](/fundamentals/architecture/data-flow-security-model) for details. +- **Availability** - the managed relayer is a managed beta service. There are no SLA guarantees. - **Storage costs** - the server wallet covers Walrus storage fees. Usage limits may apply during beta. If you need full control over the trust boundary or your own dedicated instance, see [Self-Hosting](/relayer/self-hosting). diff --git a/docs/relayer/self-hosting.md b/docs/relayer/self-hosting.md index d532429b..ce3292bd 100644 --- a/docs/relayer/self-hosting.md +++ b/docs/relayer/self-hosting.md @@ -4,7 +4,7 @@ title: "Self-Hosting" Self-hosting means running your own relayer — either pointing at an existing MemWal package ID or deploying an entirely new MemWal instance with your own contract, database, and server wallet. -The public relayer provided by Mysten is a reference implementation. You can also build your own implementation that fits the same API surface with custom logic. This guide covers how to run the reference implementation as your own self-hosted relayer. +The managed relayer provided by Walrus Foundation is a reference implementation. You can also build your own implementation that fits the same API surface with custom logic. This guide covers how to run the reference implementation as your own self-hosted relayer. ## When to Self-Host @@ -13,7 +13,7 @@ The most common reasons are removing the trust assumption on a third-party relay - **Control the trust boundary** — a self-hosted relayer keeps plaintext, encryption, and embedding under your own control - **Run your own MemWal instance** — deploy your own contract with a separate package ID, SEAL encryption keys, and data isolation - **Choose your own embedding provider** — use your own OpenAI-compatible API and credentials -- **Guarantee availability** — the public relayer is a beta service with no SLA +- **Guarantee availability** — the managed relayer is a beta service with no SLA ## What Runs diff --git a/docs/sdk/quick-start.md b/docs/sdk/quick-start.md index b76fcc6c..e07b1a85 100644 --- a/docs/sdk/quick-start.md +++ b/docs/sdk/quick-start.md @@ -73,7 +73,7 @@ yarn add ai zod | --- | --- | --- | --- | | `key` | `string` | Yes | Ed25519 private key in hex | | `accountId` | `string` | Yes | MemWalAccount object ID on Sui | -| `serverUrl` | `string` | No | Relayer URL — use `https://relayer.memwal.ai` (mainnet) or `https://relayer.staging.memwal.ai` (testnet) for the [public relayer](/relayer/public-relayer) | +| `serverUrl` | `string` | No | Relayer URL — use `https://relayer.memwal.ai` (mainnet) or `https://relayer.staging.memwal.ai` (testnet) for the [managed relayer](/relayer/public-relayer) | | `namespace` | `string` | No | Default namespace — falls back to `"default"` | ## First Memory From f4509d9f4396469b71926e14d95333cfa58e0707 Mon Sep 17 00:00:00 2001 From: ducnmm Date: Wed, 25 Mar 2026 11:31:20 +0700 Subject: [PATCH 2/5] fix: sync researcher lockfile specifier (workspace:*) --- apps/researcher/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/researcher/package.json b/apps/researcher/package.json index 0217aa35..72f75325 100644 --- a/apps/researcher/package.json +++ b/apps/researcher/package.json @@ -24,7 +24,7 @@ "@ai-sdk/openai": "^3.0.41", "@ai-sdk/provider": "^3.0.3", "@ai-sdk/react": "3.0.39", - "@mysten-incubation/memwal": "^0.0.1-dev.0", + "@mysten-incubation/memwal": "workspace:*", "@codemirror/lang-javascript": "^6.2.2", "@codemirror/lang-python": "^6.1.6", "@codemirror/state": "^6.5.0", From b6ddd6269abe3a723737abd381a1fb0e8179c6c4 Mon Sep 17 00:00:00 2001 From: ducnmm Date: Thu, 26 Mar 2026 01:41:20 +0700 Subject: [PATCH 3/5] feat(chatbot): add saveMemory AI tool for explicit memory saving --- apps/chatbot/app/(chat)/api/chat/route.ts | 3 ++ apps/chatbot/lib/ai/prompts.ts | 7 +++- apps/chatbot/lib/ai/tools/save-memory.ts | 48 +++++++++++++++++++++++ 3 files changed, 57 insertions(+), 1 deletion(-) create mode 100644 apps/chatbot/lib/ai/tools/save-memory.ts diff --git a/apps/chatbot/app/(chat)/api/chat/route.ts b/apps/chatbot/app/(chat)/api/chat/route.ts index b5115664..c4f6a14b 100644 --- a/apps/chatbot/app/(chat)/api/chat/route.ts +++ b/apps/chatbot/app/(chat)/api/chat/route.ts @@ -21,6 +21,7 @@ import { getLanguageModel, getMemWalModel } from "@/lib/ai/providers"; import { createDocument } from "@/lib/ai/tools/create-document"; import { getWeather } from "@/lib/ai/tools/get-weather"; import { requestSuggestions } from "@/lib/ai/tools/request-suggestions"; +import { saveMemory } from "@/lib/ai/tools/save-memory"; import { updateDocument } from "@/lib/ai/tools/update-document"; import { isProductionEnvironment } from "@/lib/constants"; import { @@ -170,6 +171,7 @@ export async function POST(request: Request) { "createDocument", "updateDocument", "requestSuggestions", + "saveMemory", ], providerOptions: isReasoningModel ? { @@ -183,6 +185,7 @@ export async function POST(request: Request) { createDocument: createDocument({ session, dataStream }), updateDocument: updateDocument({ session, dataStream }), requestSuggestions: requestSuggestions({ session, dataStream }), + saveMemory: saveMemory({ memwalKey, memwalAccountId }), }, experimental_telemetry: { isEnabled: isProductionEnvironment, diff --git a/apps/chatbot/lib/ai/prompts.ts b/apps/chatbot/lib/ai/prompts.ts index a68e59c3..a6c67f96 100644 --- a/apps/chatbot/lib/ai/prompts.ts +++ b/apps/chatbot/lib/ai/prompts.ts @@ -39,7 +39,12 @@ Do not update document right after creating it. Wait for user feedback or reques export const regularPrompt = `You are a friendly assistant! Keep your responses concise and helpful. -When asked to write, create, or help with something, just do it directly. Don't ask clarifying questions unless absolutely necessary - make reasonable assumptions and proceed with the task.`; +When asked to write, create, or help with something, just do it directly. Don't ask clarifying questions unless absolutely necessary - make reasonable assumptions and proceed with the task. + +You have access to the user's personal memory system powered by MemWal. Memories are automatically recalled and injected as context during conversations. + +Memory Tool: +- saveMemory({text}) - Save information to the user's personal memory on the blockchain. ONLY call this when the user EXPLICITLY asks to save or remember something. Do NOT call it proactively.`; export type RequestHints = { latitude: Geo["latitude"]; diff --git a/apps/chatbot/lib/ai/tools/save-memory.ts b/apps/chatbot/lib/ai/tools/save-memory.ts new file mode 100644 index 00000000..3cc728a6 --- /dev/null +++ b/apps/chatbot/lib/ai/tools/save-memory.ts @@ -0,0 +1,48 @@ +import { tool } from "ai"; +import { z } from "zod"; +import { MemWal } from "@mysten-incubation/memwal"; + +export const saveMemory = ({ + memwalKey, + memwalAccountId, +}: { + memwalKey?: string; + memwalAccountId?: string; +}) => + tool({ + description: + "Save information to the user's personal memory on the blockchain. ONLY use this tool when the user EXPLICITLY asks you to save or remember something (e.g., 'remember this', 'save this', 'lưu lại', 'nhớ giùm'). Do NOT use this tool proactively. Save the FULL, DETAILED content — do not summarize or shorten it.", + inputSchema: z.object({ + text: z + .string() + .describe( + "The full, detailed text to save to memory. Include all relevant details — do not summarize." + ), + }), + execute: async ({ text }) => { + const key = memwalKey || process.env.MEMWAL_KEY; + const accountId = memwalAccountId || process.env.MEMWAL_ACCOUNT_ID; + const serverUrl = process.env.MEMWAL_SERVER_URL || "http://localhost:8000"; + + if (!key || !accountId) { + return { + saved: false, + text, + error: "MemWal not configured — MEMWAL_KEY or MEMWAL_ACCOUNT_ID missing", + }; + } + + try { + const memwal = MemWal.create({ key, accountId, serverUrl }); + await memwal.remember(text); + return { saved: true, text }; + } catch (error) { + console.error("[Tool] saveMemory error:", error); + return { + saved: false, + text, + error: error instanceof Error ? error.message : "Failed to save memory", + }; + } + }, + }); From 101e99944219003e3f880906be22d705c10db547 Mon Sep 17 00:00:00 2001 From: ducnmm Date: Thu, 26 Mar 2026 01:52:00 +0700 Subject: [PATCH 4/5] fix(researcher): revert memwal dep to npm version --- apps/researcher/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/researcher/package.json b/apps/researcher/package.json index 72f75325..0217aa35 100644 --- a/apps/researcher/package.json +++ b/apps/researcher/package.json @@ -24,7 +24,7 @@ "@ai-sdk/openai": "^3.0.41", "@ai-sdk/provider": "^3.0.3", "@ai-sdk/react": "3.0.39", - "@mysten-incubation/memwal": "workspace:*", + "@mysten-incubation/memwal": "^0.0.1-dev.0", "@codemirror/lang-javascript": "^6.2.2", "@codemirror/lang-python": "^6.1.6", "@codemirror/state": "^6.5.0", From 94870602438f968895fc61db8f4bbd881eb3a411 Mon Sep 17 00:00:00 2001 From: ducnmm Date: Thu, 26 Mar 2026 09:18:07 +0700 Subject: [PATCH 5/5] feat(chatbot): add loading indicator + increase rate limit to 30/hr --- apps/chatbot/components/message.tsx | 22 +++++++++++++++++++++- apps/chatbot/components/messages.tsx | 15 +++++++++------ apps/chatbot/lib/ai/entitlements.ts | 4 ++-- 3 files changed, 32 insertions(+), 9 deletions(-) diff --git a/apps/chatbot/components/message.tsx b/apps/chatbot/components/message.tsx index bc6d268b..eb7ddfa8 100644 --- a/apps/chatbot/components/message.tsx +++ b/apps/chatbot/components/message.tsx @@ -66,7 +66,9 @@ const PurePreviewMessage = ({ > {message.role === "assistant" && (
- +
(p.type === "text" && p.text?.trim()) || ["tool-getWeather", "tool-createDocument", "tool-updateDocument", "tool-requestSuggestions"].includes(p.type)) ? "animate-pulse" : ""}> + +
)} @@ -104,6 +106,24 @@ const PurePreviewMessage = ({ )} + {/* Show "Thinking..." when assistant message is loading with no content */} + {message.role === "assistant" && + isLoading && + !message.parts?.some( + (p) => + (p.type === "text" && p.text?.trim()) || + ["tool-getWeather", "tool-createDocument", "tool-updateDocument", "tool-requestSuggestions"].includes(p.type) + ) && ( +
+ Thinking + + . + . + . + +
+ )} + {message.parts?.map((part, index) => { const { type } = part; const key = `message-${message.id}-part-${index}`; diff --git a/apps/chatbot/components/messages.tsx b/apps/chatbot/components/messages.tsx index c9581adb..9fb344eb 100644 --- a/apps/chatbot/components/messages.tsx +++ b/apps/chatbot/components/messages.tsx @@ -75,12 +75,15 @@ function PureMessages({ /> ))} - {status === "submitted" && - !messages.some((msg) => - msg.parts?.some( - (part) => "state" in part && part.state === "approval-responded" - ) - ) && } + {(status === "submitted" || status === "streaming") && + (() => { + const lastMsg = messages[messages.length - 1]; + // Show ThinkingMessage when: + // 1. Status is "submitted" (request sent, no response yet) AND last message is from user + // 2. Status is "streaming" but no assistant message exists yet + const lastIsUser = !lastMsg || lastMsg.role === "user"; + return lastIsUser; + })() && }
= { * For users without an account */ guest: { - maxMessagesPerHour: 10, + maxMessagesPerHour: 30, }, /* * For users with an account */ regular: { - maxMessagesPerHour: 10, + maxMessagesPerHour: 30, }, /*