From 80d36d5f163d781a2fd44f4a3aac6f1b57913aec Mon Sep 17 00:00:00 2001
From: Daniel Lam <daniellamhoang@gmail.com>
Date: Tue, 24 Mar 2026 17:26:34 +0700
Subject: [PATCH 01/16] add demo dropdown nav to landing page header

Reads VITE_DEMO_URLS (comma-separated Label|URL pairs) and renders
a dropdown menu in the landing page nav bar when configured.
---
 apps/app/.env.example              |  4 ++
 apps/app/src/config.ts             |  6 +++
 apps/app/src/index.css             | 84 ++++++++++++++++++++++++++++++
 apps/app/src/pages/LandingPage.tsx | 42 ++++++++++++++-
 4 files changed, 135 insertions(+), 1 deletion(-)

diff --git a/apps/app/.env.example b/apps/app/.env.example
index bcb651fd..8eaaa605 100644
--- a/apps/app/.env.example
+++ b/apps/app/.env.example
@@ -16,6 +16,10 @@ VITE_MEMWAL_SERVER_URL=http://localhost:8000
 # Docs URL (separate deployment)
 VITE_DOCS_URL=http://localhost:5174
 
+# Demo app links (comma-separated, format: Label|URL)
+# Example: VITE_DEMO_URLS=Chat Demo|https://chat.example.com,Agent Demo|https://agent.example.com
+VITE_DEMO_URLS=
+
 # ══════════════════════════════════════════════════════════════
 # ▷ INACTIVE: MAINNET  (uncomment below, comment out TESTNET above)
 # ══════════════════════════════════════════════════════════════
diff --git a/apps/app/src/config.ts b/apps/app/src/config.ts
index 4f510690..b14f7734 100644
--- a/apps/app/src/config.ts
+++ b/apps/app/src/config.ts
@@ -14,4 +14,10 @@ export const config = {
         .split(',').map(s => s.trim()).filter(Boolean) as string[],
     sidecarUrl: import.meta.env.VITE_SIDECAR_URL as string || 'http://localhost:9000',
     docsUrl: import.meta.env.VITE_DOCS_URL as string || '',
+    demoUrls: (import.meta.env.VITE_DEMO_URLS as string || '')
+        .split(',').map(s => s.trim()).filter(Boolean)
+        .map(entry => {
+            const [label, url] = entry.split('|').map(s => s.trim())
+            return url ? { label, url } : { label: label, url: label }
+        }),
 } as const
diff --git a/apps/app/src/index.css b/apps/app/src/index.css
index 80ae5753..abd7d38d 100644
--- a/apps/app/src/index.css
+++ b/apps/app/src/index.css
@@ -515,6 +515,90 @@ h1, h2, h3 {
   box-shadow: 1px 1px 0 #000000;
 }
 
+/* ── Demo Dropdown ── */
+
+.lp-demo-dropdown {
+  position: relative;
+}
+
+.lp-demo-trigger {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  background: none;
+  border: 2px solid #000000;
+  border-radius: 12px;
+  padding: 10px 18px;
+  font-size: 0.92rem;
+  font-weight: 700;
+  font-family: var(--font-sans);
+  cursor: pointer;
+  transition: transform 0.15s, box-shadow 0.15s;
+  box-shadow: 3px 3px 0 #000000;
+  color: #000000;
+  background: #ffffff;
+}
+
+.lp-demo-trigger:hover {
+  transform: translate(-2px, -2px);
+  box-shadow: 5px 5px 0 #000000;
+}
+
+.lp-demo-trigger:active {
+  transform: translate(2px, 2px);
+  box-shadow: 1px 1px 0 #000000;
+}
+
+.lp-demo-chevron {
+  transition: transform 0.2s;
+}
+
+.lp-demo-chevron.open {
+  transform: rotate(180deg);
+}
+
+.lp-demo-menu {
+  position: absolute;
+  top: calc(100% + 8px);
+  right: 0;
+  min-width: 200px;
+  background: #ffffff;
+  border: 2px solid #000000;
+  border-radius: 12px;
+  box-shadow: 4px 4px 0 #000000;
+  padding: 6px;
+  z-index: 100;
+  animation: lp-dropdown-in 0.15s ease-out;
+}
+
+@keyframes lp-dropdown-in {
+  from {
+    opacity: 0;
+    transform: translateY(-4px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.lp-demo-item {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 10px 14px;
+  color: #000000;
+  text-decoration: none;
+  font-size: 0.88rem;
+  font-weight: 600;
+  border-radius: 8px;
+  transition: background 0.1s;
+}
+
+.lp-demo-item:hover {
+  background: #E8FF75;
+}
+
 /* ── Hero ── */
 
 .lp-hero {
diff --git a/apps/app/src/pages/LandingPage.tsx b/apps/app/src/pages/LandingPage.tsx
index 2b9b6296..80ba3715 100644
--- a/apps/app/src/pages/LandingPage.tsx
+++ b/apps/app/src/pages/LandingPage.tsx
@@ -9,7 +9,8 @@ import {
     useWallets,
 } from '@mysten/dapp-kit'
 import { isEnokiWallet, type EnokiWallet, type AuthProvider } from '@mysten/enoki'
-import { Github } from 'lucide-react'
+import { ChevronDown, Github } from 'lucide-react'
+import { useRef, useState, useEffect } from 'react'
 import { useNavigate } from 'react-router-dom'
 import { config } from '../config'
 import memwalLogo from '../assets/memwal-logo.svg'
@@ -29,6 +30,19 @@ export default function LandingPage() {
 
     const navigate = useNavigate()
     const hasEnokiConfig = config.enokiApiKey && config.googleClientId
+    const demoUrls = config.demoUrls
+    const [demoOpen, setDemoOpen] = useState(false)
+    const demoRef = useRef<HTMLDivElement>(null)
+
+    useEffect(() => {
+        const handleClickOutside = (e: MouseEvent) => {
+            if (demoRef.current && !demoRef.current.contains(e.target as Node)) {
+                setDemoOpen(false)
+            }
+        }
+        document.addEventListener('mousedown', handleClickOutside)
+        return () => document.removeEventListener('mousedown', handleClickOutside)
+    }, [])
 
     const handleConnect = () => {
         if (currentAccount) {
@@ -49,6 +63,32 @@ export default function LandingPage() {
                     </a>
 
                     <div className="lp-nav-links">
+                        {demoUrls.length > 0 && (
+                            <div className="lp-demo-dropdown" ref={demoRef}>
+                                <button
+                                    className="lp-demo-trigger"
+                                    onClick={() => setDemoOpen(o => !o)}
+                                >
+                                    Demo <ChevronDown size={14} className={`lp-demo-chevron${demoOpen ? ' open' : ''}`} />
+                                </button>
+                                {demoOpen && (
+                                    <div className="lp-demo-menu">
+                                        {demoUrls.map(({ label, url }) => (
+                                            <a
+                                                key={url}
+                                                href={url}
+                                                target="_blank"
+                                                rel="noopener noreferrer"
+                                                className="lp-demo-item"
+                                                onClick={() => setDemoOpen(false)}
+                                            >
+                                                {label} <span className="lp-arrow">↗</span>
+                                            </a>
+                                        ))}
+                                    </div>
+                                )}
+                            </div>
+                        )}
                         {currentAccount ? (
                             <button className="lp-nav-cta" onClick={() => navigate('/dashboard')}>
                                 Playground <span className="lp-arrow">↗</span>

From ec0a613dc70c01c0c2bac4d96b3888faf1e7b047 Mon Sep 17 00:00:00 2001
From: 1924 <email@address.com>
Date: Tue, 24 Mar 2026 17:28:12 +0700
Subject: [PATCH 02/16] Make Walrus epoch defaults network-aware

---
 docs/reference/environment-variables.md   |  1 +
 services/server/scripts/sidecar-server.ts | 11 ++++++++++-
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/docs/reference/environment-variables.md b/docs/reference/environment-variables.md
index ab4b171a..88768fa8 100644
--- a/docs/reference/environment-variables.md
+++ b/docs/reference/environment-variables.md
@@ -47,6 +47,7 @@ These are not all enforced at boot, but most real deployments need them.
 - The relayer uses them for `remember`, `recall`, `analyze`, `ask`, and restore re-indexing.
 - `SEAL_KEY_SERVERS` is required for the sidecar SEAL encrypt and decrypt path.
 - `SUI_NETWORK` now drives the default RPC URL, Walrus endpoints, Walrus package ID, and upload relay selection.
+- The sidecar `POST /walrus/upload` route defaults Walrus storage epochs by network: `50` on `testnet`, `2` on `mainnet`, unless the request explicitly passes `epochs`.
 - `MEMWAL_PACKAGE_ID` and `MEMWAL_REGISTRY_ID` are server env vars. Do not replace them with `VITE_*` app env vars.
 - For testnet, use `MEMWAL_PACKAGE_ID=0xcf6ad755a1cdff7217865c796778fabe5aa399cb0cf2eba986f4b582047229c6` and `MEMWAL_REGISTRY_ID=0xe80f2feec1c139616a86c9f71210152e2a7ca552b20841f2e192f99f75864437`.
 - Without `OPENAI_API_KEY`, the server can fall back to mock embeddings. That is useful for local testing, not for normal production behavior.
diff --git a/services/server/scripts/sidecar-server.ts b/services/server/scripts/sidecar-server.ts
index b0fc727a..e326fc76 100644
--- a/services/server/scripts/sidecar-server.ts
+++ b/services/server/scripts/sidecar-server.ts
@@ -51,6 +51,8 @@ const WALRUS_UPLOAD_RELAY_URL = process.env.WALRUS_UPLOAD_RELAY_URL || (
         : "https://upload-relay.mainnet.walrus.space"
 );
 
+const DEFAULT_WALRUS_EPOCHS = SUI_NETWORK === "testnet" ? 50 : 2;
+
 const suiClient = new SuiJsonRpcClient({
     url: getJsonRpcFullnodeUrl(SUI_NETWORK),
     network: SUI_NETWORK,
@@ -415,7 +417,14 @@ app.post("/seal/decrypt-batch", async (req, res) => {
 // ============================================================
 app.post("/walrus/upload", async (req, res) => {
     try {
-        const { data, privateKey, owner, namespace, packageId, epochs = 2 } = req.body;
+        const {
+            data,
+            privateKey,
+            owner,
+            namespace,
+            packageId,
+            epochs = DEFAULT_WALRUS_EPOCHS,
+        } = req.body;
         if (!data || !privateKey) {
             return res.status(400).json({ error: "Missing required fields: data, privateKey" });
         }

From 9625311b7890b64cdf9ca15fbd6cad981865eefe Mon Sep 17 00:00:00 2001
From: Daniel Lam <daniellamhoang@gmail.com>
Date: Tue, 24 Mar 2026 17:34:47 +0700
Subject: [PATCH 03/16] chore: update dockerfile app

---
 apps/app/Dockerfile | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/apps/app/Dockerfile b/apps/app/Dockerfile
index 4bc5d12c..f7f8fd18 100644
--- a/apps/app/Dockerfile
+++ b/apps/app/Dockerfile
@@ -35,6 +35,7 @@ ARG VITE_SUI_NETWORK=mainnet
 ARG VITE_ENOKI_API_KEY
 ARG VITE_GOOGLE_CLIENT_ID
 ARG VITE_DOCS_URL
+ARG VITE_DEMO_URLS
 
 ENV VITE_MEMWAL_SERVER_URL=$VITE_MEMWAL_SERVER_URL
 ENV VITE_MEMWAL_PACKAGE_ID=$VITE_MEMWAL_PACKAGE_ID
@@ -43,6 +44,7 @@ ENV VITE_SUI_NETWORK=$VITE_SUI_NETWORK
 ENV VITE_ENOKI_API_KEY=$VITE_ENOKI_API_KEY
 ENV VITE_GOOGLE_CLIENT_ID=$VITE_GOOGLE_CLIENT_ID
 ENV VITE_DOCS_URL=$VITE_DOCS_URL
+ARG VITE_DEMO_URLS=$VITE_DEMO_URLS
 
 RUN pnpm --filter @memwal/app build
 

From 0bdd51712397f5cc35bc48d01edc5ac1c1e45f47 Mon Sep 17 00:00:00 2001
From: ducnmm <mauduckiengiang@gmail.com>
Date: Tue, 24 Mar 2026 17:44:01 +0700
Subject: [PATCH 04/16] feat(sdk): auto-increment prerelease versions for
 dev/staging branches

---
 .github/workflows/release-sdk.yml | 57 ++++++++++++++++++++++---------
 packages/sdk/package.json         |  4 +--
 2 files changed, 42 insertions(+), 19 deletions(-)

diff --git a/.github/workflows/release-sdk.yml b/.github/workflows/release-sdk.yml
index 65659e03..fc10ea61 100644
--- a/.github/workflows/release-sdk.yml
+++ b/.github/workflows/release-sdk.yml
@@ -8,7 +8,6 @@ on:
       - dev
     paths:
       - 'packages/sdk/**'
-      - '.changeset/**'
       - '.github/workflows/release-sdk.yml'
   workflow_dispatch:
 
@@ -47,34 +46,58 @@ jobs:
         run: pnpm build:sdk
 
       # ── main branch → stable release (latest) ──
-      - name: Create Release PR or Publish to npm
+      - name: Publish stable release
         if: github.ref == 'refs/heads/main'
-        uses: changesets/action@v1
-        with:
-          title: 'chore: version packages'
-          commit: 'chore: version packages'
-          publish: pnpm changeset publish
+        run: |
+          BASE_VERSION=$(node -p "require('./packages/sdk/package.json').version")
+          npm view @mysten/memwal@$BASE_VERSION version 2>/dev/null \
+            && echo "Version $BASE_VERSION already published, skipping" && exit 0
+          cd packages/sdk && npm publish --access public
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
-      # ── staging branch → release candidate (rc tag) ──
+      # ── staging branch → release candidate (rc tag, auto-increment) ──
       - name: Publish staging release candidate
         if: github.ref == 'refs/heads/staging'
         run: |
-          PKG_VERSION=$(node -p "require('./packages/sdk/package.json').version")
-          npm view @mysten/memwal@$PKG_VERSION version 2>/dev/null && echo "Version $PKG_VERSION already published, skipping" && exit 0
-          cd packages/sdk && npm publish --tag rc --access public
+          BASE_VERSION=$(node -p "require('./packages/sdk/package.json').version")
+          LATEST=$(npm view @mysten/memwal versions --json 2>/dev/null \
+            | node -p "
+                const versions = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
+                const nums = (Array.isArray(versions) ? versions : [versions])
+                  .filter(v => v.startsWith('${BASE_VERSION}-rc.'))
+                  .map(v => +v.split('-rc.')[1])
+                  .sort((a,b) => b - a);
+                nums.length ? nums[0] : -1;
+              " || echo "-1")
+          NEXT=$((LATEST + 1))
+          NEW_VERSION="${BASE_VERSION}-rc.${NEXT}"
+          echo "Publishing @mysten/memwal@${NEW_VERSION}"
+          cd packages/sdk
+          npm version $NEW_VERSION --no-git-tag-version
+          npm publish --tag rc --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
-      # ── dev branch → prerelease (dev tag) ──
+      # ── dev branch → prerelease (dev tag, auto-increment) ──
       - name: Publish dev prerelease
         if: github.ref == 'refs/heads/dev'
         run: |
-          PKG_VERSION=$(node -p "require('./packages/sdk/package.json').version")
-          npm view @mysten/memwal@$PKG_VERSION version 2>/dev/null && echo "Version $PKG_VERSION already published, skipping" && exit 0
-          cd packages/sdk && npm publish --tag dev --access public
+          BASE_VERSION=$(node -p "require('./packages/sdk/package.json').version")
+          LATEST=$(npm view @mysten/memwal versions --json 2>/dev/null \
+            | node -p "
+                const versions = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
+                const nums = (Array.isArray(versions) ? versions : [versions])
+                  .filter(v => v.startsWith('${BASE_VERSION}-dev.'))
+                  .map(v => +v.split('-dev.')[1])
+                  .sort((a,b) => b - a);
+                nums.length ? nums[0] : -1;
+              " || echo "-1")
+          NEXT=$((LATEST + 1))
+          NEW_VERSION="${BASE_VERSION}-dev.${NEXT}"
+          echo "Publishing @mysten/memwal@${NEW_VERSION}"
+          cd packages/sdk
+          npm version $NEW_VERSION --no-git-tag-version
+          npm publish --tag dev --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
diff --git a/packages/sdk/package.json b/packages/sdk/package.json
index 3b822cf2..3132a82b 100644
--- a/packages/sdk/package.json
+++ b/packages/sdk/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@mysten/memwal",
-    "version": "0.0.1-dev.0",
+    "version": "0.0.1",
     "description": "MemWal — Privacy-first AI memory SDK with Ed25519 delegate key auth",
     "type": "module",
     "main": "./dist/index.js",
@@ -75,7 +75,7 @@
         "ed25519",
         "tee"
     ],
-    "license": "MIT",
+    "license": "Apache-2.0",
     "publishConfig": {
         "access": "public",
         "registry": "https://registry.npmjs.org/"

From 5e53bdc57c48fc54df28aef01ce85bcf203c4591 Mon Sep 17 00:00:00 2001
From: ducnmm <mauduckiengiang@gmail.com>
Date: Tue, 24 Mar 2026 17:46:15 +0700
Subject: [PATCH 05/16] fix(sdk): use node -e instead of npm version to avoid
 workspace conflicts

---
 .github/workflows/release-sdk.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/release-sdk.yml b/.github/workflows/release-sdk.yml
index fc10ea61..9823aac2 100644
--- a/.github/workflows/release-sdk.yml
+++ b/.github/workflows/release-sdk.yml
@@ -74,7 +74,7 @@ jobs:
           NEW_VERSION="${BASE_VERSION}-rc.${NEXT}"
           echo "Publishing @mysten/memwal@${NEW_VERSION}"
           cd packages/sdk
-          npm version $NEW_VERSION --no-git-tag-version
+          node -e "const p=require('./package.json');p.version='${NEW_VERSION}';require('fs').writeFileSync('./package.json',JSON.stringify(p,null,4)+'\n')"
           npm publish --tag rc --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
@@ -97,7 +97,7 @@ jobs:
           NEW_VERSION="${BASE_VERSION}-dev.${NEXT}"
           echo "Publishing @mysten/memwal@${NEW_VERSION}"
           cd packages/sdk
-          npm version $NEW_VERSION --no-git-tag-version
+          node -e "const p=require('./package.json');p.version='${NEW_VERSION}';require('fs').writeFileSync('./package.json',JSON.stringify(p,null,4)+'\n')"
           npm publish --tag dev --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

From 326810edab6d51cb4cbfe5533bd7fc90efa55bb1 Mon Sep 17 00:00:00 2001
From: 1924 <email@address.com>
Date: Tue, 24 Mar 2026 17:44:15 +0700
Subject: [PATCH 06/16] Document network-specific Walrus epoch defaults

---
 docs/relayer/self-hosting.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/relayer/self-hosting.md b/docs/relayer/self-hosting.md
index 7121f330..912b3b19 100644
--- a/docs/relayer/self-hosting.md
+++ b/docs/relayer/self-hosting.md
@@ -73,6 +73,7 @@ curl http://localhost:8000/health
 - `SIDECAR_URL` defaults to `http://localhost:9000`
 - `SUI_NETWORK` defaults to `mainnet`
 - `SUI_RPC_URL`, Walrus endpoints, and `WALRUS_PACKAGE_ID` fall back to network defaults based on `SUI_NETWORK`
+- The sidecar Walrus upload route defaults storage `epochs` by network: `50` on `testnet`, `2` on `mainnet` (unless the request passes `epochs`)
 
 ### Server Keys
 

From b9331850472be2fcc5d0963e6fa1ee8ec06ca7be Mon Sep 17 00:00:00 2001
From: Aaron <93565802+Aaron1924@users.noreply.github.com>
Date: Tue, 24 Mar 2026 20:26:37 +0700
Subject: [PATCH 07/16] Revise environment variable section and title

Updated environment variable documentation and corrected section title.
---
 docs/relayer/self-hosting.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/docs/relayer/self-hosting.md b/docs/relayer/self-hosting.md
index 912b3b19..06b7ca79 100644
--- a/docs/relayer/self-hosting.md
+++ b/docs/relayer/self-hosting.md
@@ -81,16 +81,18 @@ curl http://localhost:8000/health
 - `SERVER_SUI_PRIVATE_KEYS` is a comma-separated key pool for parallel Walrus uploads
 - if both are set, the key pool takes priority for uploads
 
-## Testnet Contract IDs
+## Package Contract IDs
 
 ```env
-SUI_NETWORK=testnet
+SUI_NETWORK=testnet|mainnet
 MEMWAL_PACKAGE_ID=0xcf6ad755a1cdff7217865c796778fabe5aa399cb0cf2eba986f4b582047229c6
 MEMWAL_REGISTRY_ID=0xe80f2feec1c139616a86c9f71210152e2a7ca552b20841f2e192f99f75864437
 ```
 
 For SEAL key server object IDs on testnet, see https://seal-docs.wal.app/Pricing.
 
+Using official key server of SDK is recommended. 
+
 <Note>
 `VITE_MEMWAL_PACKAGE_ID` and `VITE_MEMWAL_REGISTRY_ID` are frontend env vars for the app or playground — not for the relayer.
 </Note>

From f0d2dae1f492f48c7db1693783d5d12e6d48e399 Mon Sep 17 00:00:00 2001
From: Daniel Lam <daniellamhoang@gmail.com>
Date: Tue, 24 Mar 2026 20:08:38 +0700
Subject: [PATCH 08/16] docs: use placeholders instead of process.env in quick
 start

Replace process.env references with <your-...> placeholders to match
the convention used throughout the rest of the documentation.
---
 docs/getting-started/quick-start.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md
index 1527227a..12c85d0c 100644
--- a/docs/getting-started/quick-start.md
+++ b/docs/getting-started/quick-start.md
@@ -102,9 +102,9 @@ The fastest way to get MemWal running is through the TypeScript SDK.
     import { MemWal } from "@mysten/memwal";
 
     const memwal = MemWal.create({
-      key: process.env.MEMWAL_PRIVATE_KEY!,
-      accountId: process.env.MEMWAL_ACCOUNT_ID!,
-      serverUrl: process.env.MEMWAL_SERVER_URL,
+      key: "<your-ed25519-private-key>",
+      accountId: "<your-memwal-account-id>",
+      serverUrl: "https://your-relayer-url.com",
       namespace: "my-app",
     });
     ```

From 09fdb93300de3b334b40526551338594a6addcb2 Mon Sep 17 00:00:00 2001
From: Daniel Lam <daniellamhoang@gmail.com>
Date: Tue, 24 Mar 2026 20:28:45 +0700
Subject: [PATCH 09/16] docs: add public relayer URLs for production and
 staging

Add the public relayer endpoints (https://relayer.memwal.ai for
production/mainnet, https://relayer.staging.memwal.ai for
staging/testnet) across quick start, choose your path, public relayer,
and SDK quick start pages for discoverability.
---
 docs/getting-started/choose-your-path.md |  5 +++++
 docs/getting-started/quick-start.md      | 14 +++++++++++---
 docs/relayer/public-relayer.md           | 10 ++++------
 docs/sdk/quick-start.md                  |  2 +-
 4 files changed, 21 insertions(+), 10 deletions(-)

diff --git a/docs/getting-started/choose-your-path.md b/docs/getting-started/choose-your-path.md
index 3772057d..731ebcba 100644
--- a/docs/getting-started/choose-your-path.md
+++ b/docs/getting-started/choose-your-path.md
@@ -21,6 +21,11 @@ Go to: [SDK Overview](/sdk/overview)
 
 Use this when you want to evaluate MemWal without running the backend yourself.
 
+| Network | Relayer URL |
+|---|---|
+| **Testnet** (staging) | `https://relayer.staging.memwal.ai` |
+| **Mainnet** (production) | `https://relayer.memwal.ai` |
+
 Go to: [Public Relayer](/relayer/public-relayer)
 
 ## 3. Manual Client Flow
diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md
index 12c85d0c..e1e46bf3 100644
--- a/docs/getting-started/quick-start.md
+++ b/docs/getting-started/quick-start.md
@@ -9,7 +9,9 @@ The fastest way to get MemWal running is through the TypeScript SDK.
 - [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 if one is available to you, or your own local or self-hosted relayer
+- 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
 
@@ -104,12 +106,18 @@ The fastest way to get MemWal running is through the TypeScript SDK.
     const memwal = MemWal.create({
       key: "<your-ed25519-private-key>",
       accountId: "<your-memwal-account-id>",
-      serverUrl: "https://your-relayer-url.com",
+      serverUrl: "https://relayer.memwal.ai",
       namespace: "my-app",
     });
     ```
 
-    If you are self-hosting the relayer and do not have `MEMWAL_ACCOUNT_ID` yet, see [Self-Hosting](/relayer/self-hosting) for the account-creation and delegate-key setup flow after the relayer starts.
+    <Tip>
+    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.
+    </Tip>
+
+    <Note>
+    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.
+    </Note>
   </Step>
 
   <Step>
diff --git a/docs/relayer/public-relayer.md b/docs/relayer/public-relayer.md
index 5d02bb50..5efb9de4 100644
--- a/docs/relayer/public-relayer.md
+++ b/docs/relayer/public-relayer.md
@@ -6,12 +6,10 @@ The public relayer is a managed MemWal deployment for teams that want to get sta
 
 ## Endpoints
 
-| | Value |
+| Network | Relayer URL |
 |---|---|
-| **Relayer URL** | Provided by the relayer operator |
-| **Package ID** | Provided by the relayer operator |
-
-If you do not have these values yet, use a local or [self-hosted relayer](/relayer/self-hosting) instead.
+| **Production** (mainnet) | `https://relayer.memwal.ai` |
+| **Staging** (testnet) | `https://relayer.staging.memwal.ai` |
 
 ## Minimal Config
 
@@ -21,7 +19,7 @@ import { MemWal } from "@mysten/memwal";
 const memwal = MemWal.create({
   key: "<your-ed25519-private-key>",
   accountId: "<your-memwal-account-id>",
-  serverUrl: "https://your-relayer-url.com",
+  serverUrl: "https://relayer.memwal.ai",
   namespace: "demo",
 });
 ```
diff --git a/docs/sdk/quick-start.md b/docs/sdk/quick-start.md
index a3abb84b..43408fea 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 |
+| `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) |
 | `namespace` | `string` | No | Default namespace — falls back to `"default"` |
 
 ## First Memory

From 7496e303e1525d43a97662b04cd956b23744212d Mon Sep 17 00:00:00 2001
From: Aaron1924 <planh21@clc.fitus.edu.vn>
Date: Tue, 24 Mar 2026 20:47:11 +0700
Subject: [PATCH 10/16] docs: update self-hosting network env vars

---
 docs/relayer/self-hosting.md | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/docs/relayer/self-hosting.md b/docs/relayer/self-hosting.md
index 06b7ca79..d941f325 100644
--- a/docs/relayer/self-hosting.md
+++ b/docs/relayer/self-hosting.md
@@ -82,11 +82,18 @@ curl http://localhost:8000/health
 - if both are set, the key pool takes priority for uploads
 
 ## Package Contract IDs
-
+### TESTNET
 ```env
-SUI_NETWORK=testnet|mainnet
+SUI_NETWORK=testnet
 MEMWAL_PACKAGE_ID=0xcf6ad755a1cdff7217865c796778fabe5aa399cb0cf2eba986f4b582047229c6
 MEMWAL_REGISTRY_ID=0xe80f2feec1c139616a86c9f71210152e2a7ca552b20841f2e192f99f75864437
+
+```
+### MAINNET
+```env
+SUI_NETWORK=mainnet
+MEMWAL_PACKAGE_ID=0xcee7a6fd8de52ce645c38332bde23d4a30fd9426bc4681409733dd50958a24c6
+MEMWAL_REGISTRY_ID=0x0da982cefa26864ae834a8a0504b904233d49e20fcc17c373c8bed99c75a7edd
 ```
 
 For SEAL key server object IDs on testnet, see https://seal-docs.wal.app/Pricing.

From 9ffe7e5a84915a2a185d8881317fe9d346f3c409 Mon Sep 17 00:00:00 2001
From: Aaron1924 <planh21@clc.fitus.edu.vn>
Date: Tue, 24 Mar 2026 21:24:56 +0700
Subject: [PATCH 11/16] docs: add example apps guide and remove duplicate basic
 usage

---
 docs/docs.json                         | 11 ++++
 docs/examples/basic-usage.md           | 70 ---------------------
 docs/examples/example-apps.md          | 84 ++++++++++++++++++++++++++
 docs/getting-started/what-is-memwal.md |  3 +
 docs/sdk/basic-usage.md                | 47 --------------
 docs/sdk/example-map.md                |  2 +-
 6 files changed, 99 insertions(+), 118 deletions(-)
 delete mode 100644 docs/examples/basic-usage.md
 create mode 100644 docs/examples/example-apps.md
 delete mode 100644 docs/sdk/basic-usage.md

diff --git a/docs/docs.json b/docs/docs.json
index bf64dd91..3f7e4995 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -48,6 +48,17 @@
           }
         ]
       },
+      {
+        "tab": "Examples",
+        "groups": [
+          {
+            "group": "Examples",
+            "pages": [
+              "examples/example-apps"
+            ]
+          }
+        ]
+      },
       {
         "tab": "Fundamentals",
         "groups": [
diff --git a/docs/examples/basic-usage.md b/docs/examples/basic-usage.md
deleted file mode 100644
index a05a559b..00000000
--- a/docs/examples/basic-usage.md
+++ /dev/null
@@ -1,70 +0,0 @@
----
-title: "Basic Usage"
----
-
-## Installation
-
-```bash
-pnpm add @mysten/memwal
-```
-
-## Initialize
-
-```typescript
-import { MemWal } from "@mysten/memwal";
-
-const memwal = MemWal.create({
-  key: process.env.MEMWAL_PRIVATE_KEY!,
-  accountId: process.env.MEMWAL_ACCOUNT_ID!,
-  serverUrl: process.env.MEMWAL_SERVER_URL,
-  namespace: "my-app",
-});
-```
-
-## Store a Memory
-
-```typescript
-const result = await memwal.remember("User prefers dark mode and works in TypeScript.");
-console.log("Blob ID:", result.blob_id);
-```
-
-## Recall Memories
-
-```typescript
-const results = await memwal.recall("What do we know about this user?", 10);
-
-for (const memory of results.results) {
-  console.log(memory.text, `(distance: ${memory.distance})`);
-}
-```
-
-## Analyze Text
-
-Extract structured facts from longer text and store each as a separate memory.
-
-```typescript
-const analyzed = await memwal.analyze(
-  "I live in Hanoi, prefer dark mode, and usually work late at night."
-);
-
-console.log(`Extracted ${analyzed.total} facts:`);
-for (const fact of analyzed.facts) {
-  console.log(`- ${fact.text}`);
-}
-```
-
-## Restore a Namespace
-
-Rebuild missing indexed entries from Walrus if your local database is incomplete.
-
-```typescript
-const restored = await memwal.restore("my-app", 50);
-console.log(`Restored ${restored.restored} memories, skipped ${restored.skipped}`);
-```
-
-## Health Check
-
-```typescript
-const health = await memwal.health();
-console.log(health.status); // "ok"
-```
diff --git a/docs/examples/example-apps.md b/docs/examples/example-apps.md
new file mode 100644
index 00000000..2a6c7da8
--- /dev/null
+++ b/docs/examples/example-apps.md
@@ -0,0 +1,84 @@
+---
+title: "Example Apps"
+description: "Short examples showing how each demo app uses MemWal."
+---
+
+The repo includes ready-to-run apps in `apps/` that show different MemWal integration patterns.
+This page focuses on app-level patterns,the basic SDK flow covered in [Quick Start](/sdk/quick-start) and [MemWal Usage](/sdk/usage/memwal).
+
+## Run Locally
+
+```bash
+pnpm dev:app
+pnpm dev:chatbot
+pnpm dev:noter
+pnpm dev:researcher
+```
+
+## [App](https://github.com/MystenLabs/MemWal/tree/main/apps/app)
+
+Onboarding app, account dashboard, playground, and interactive demo for MemWal.
+
+```ts
+const memwal = MemWal.create({
+  key: delegateKey,
+  accountId: accountObjectId,
+  serverUrl,
+  namespace,
+});
+
+await memwal.remember(rememberText);
+await memwal.recall(recallQuery, 5);
+await memwal.analyze(analyzeText);
+```
+
+This app covers the full getting-started flow in one place. It signs users in, sets up delegate keys, shows SDK credentials, and includes a live playground for `remember()`, `recall()`, `analyze()`, `restore()`, AI middleware, and manual mode.
+
+## [Chatbot](https://github.com/MystenLabs/MemWal/tree/main/apps/chatbot)
+
+AI chat app with persistent memory across sessions.
+
+```ts
+import { withMemWal } from "@mysten/memwal/ai";
+
+const model = withMemWal(baseModel, {
+  key,
+  accountId,
+  serverUrl,
+  maxMemories: 5,
+  autoSave: true,
+});
+```
+
+This app shows AI middleware integration in a production-style chat app. The UI can enable MemWal, collect a delegate key and account ID, and pass them to the chat API. The server wraps the selected model with `withMemWal`, so recall happens before generation and new context can be auto-saved after each turn.
+
+## [Noter](https://github.com/MystenLabs/MemWal/tree/main/apps/noter)
+
+Note-taking app that stores insights as encrypted, searchable memory.
+
+```ts
+export const extractMemories = async (text: string): Promise<string[]> => {
+  const memwal = getMemWalClient();
+  const result = await memwal.analyze(text);
+  return (result.facts ?? []).map((f) => f.text);
+};
+```
+
+This app shows note-to-memory extraction. Noter keeps a shared server-side MemWal client, lets the user configure the key and account at runtime, and uses `analyze()` to turn note content into structured facts that can be reused by the editor and AI features.
+
+## [Researcher](https://github.com/MystenLabs/MemWal/tree/main/apps/researcher)
+
+Research assistant that saves and recalls findings across sessions.
+
+```ts
+const fullText =
+  `Sprint Report: ${title}\n\n` +
+  `${content}\n\n` +
+  `References:\n${references}\n\n` +
+  `Sources: ${sourceList}`;
+
+await memwal.remember(fullText);
+const { results } = await memwal.recall(query, 5);
+```
+
+This app shows long-form research memory and session rehydration. Researcher saves each sprint as a structured report in MemWal, then generates recall queries from sprint metadata, pulls back the most relevant findings, and rebuilds context for a fresh session.
diff --git a/docs/getting-started/what-is-memwal.md b/docs/getting-started/what-is-memwal.md
index 15454af2..96039af3 100644
--- a/docs/getting-started/what-is-memwal.md
+++ b/docs/getting-started/what-is-memwal.md
@@ -100,10 +100,13 @@ And many more — check out the example apps below to see MemWal in action.
 
 The repo ships with ready-to-run apps in the [`/apps`](https://github.com/CommandOSSLabs/memwal/tree/main/apps) directory:
 
+- **App** — dashboard demo for zkLogin, delegate-key setup, and account management
 - **Chatbot** — AI chat app with persistent memory across sessions
 - **Noter** — note-taking tool that stores knowledge as encrypted memory
 - **Researcher** — research assistant that builds and recalls a knowledge base
 
+See [Example Apps](/examples/example-apps) for short code examples from each app.
+
 ## Explore the Docs
 
 <CardGroup cols={2}>
diff --git a/docs/sdk/basic-usage.md b/docs/sdk/basic-usage.md
deleted file mode 100644
index 4d88389f..00000000
--- a/docs/sdk/basic-usage.md
+++ /dev/null
@@ -1,47 +0,0 @@
----
-title: "Basic Usage"
----
-
-## Use This When
-
-- you want the shortest working MemWal example
-- you are using the default relayer-backed SDK
-
-## Code
-
-```ts
-import { MemWal } from "@mysten/memwal";
-
-const memwal = MemWal.create({
-  key: process.env.MEMWAL_PRIVATE_KEY!,
-  accountId: process.env.MEMWAL_ACCOUNT_ID!,
-  serverUrl: process.env.MEMWAL_SERVER_URL,
-  namespace: "demo",
-});
-
-await memwal.health();
-
-const stored = await memwal.remember(
-  "User prefers dark mode and works in TypeScript."
-);
-
-const recalled = await memwal.recall(
-  "What do we know about this user?",
-  5
-);
-
-console.log(stored.blob_id);
-console.log(recalled.results);
-```
-
-## What You Should See
-
-- `health()` succeeds
-- `remember()` returns a `blob_id`
-- `recall()` returns plaintext results for the same namespace
-
-## Read Next
-
-- [Advanced Usage](/sdk/advanced-usage)
-- [SDK Usage](/sdk/usage)
-- [SDK API Reference](/reference/sdk-api)
diff --git a/docs/sdk/example-map.md b/docs/sdk/example-map.md
index 998b47a6..5e5d552a 100644
--- a/docs/sdk/example-map.md
+++ b/docs/sdk/example-map.md
@@ -4,6 +4,6 @@ title: "Example Map"
 
 ## Start Here
 
-- [Basic Usage](/sdk/basic-usage): initialize the SDK, store one memory, recall it
+- [Quick Start](/sdk/quick-start): install the SDK and store your first memory
 - [Advanced Usage](/sdk/advanced-usage): manual methods, `analyze()`, and AI middleware
 - [Research App Example](/sdk/research-app-example): application-level pattern for structured memory

From 5e483f9f7b694ba43f5fa853c97cbb8c26d4ae37 Mon Sep 17 00:00:00 2001
From: Aaron1924 <planh21@clc.fitus.edu.vn>
Date: Tue, 24 Mar 2026 21:59:14 +0700
Subject: [PATCH 12/16] docs: sync docs folder with dev

---
 docs/contract/delegate-key-management.md      |  85 +++++-
 docs/contract/overview.md                     |  91 +++++-
 docs/contract/ownership-and-permissions.md    |  42 ++-
 docs/contributing/run-docs-locally.md         |   2 +-
 docs/contributing/run-repo-locally.md         |   5 +-
 docs/docs.json                                |  46 ++-
 docs/examples/basic-usage.md                  |  65 -----
 docs/examples/example-apps.md                 |  84 ++++++
 docs/favicon.ico                              | Bin 0 -> 32038 bytes
 .../architecture/core-components.md           |  15 +-
 .../architecture/data-flow-security-model.md  |  17 ++
 .../architecture/how-storage-works.md         |  51 +++-
 docs/fundamentals/concepts/memory-space.md    |   9 +-
 .../concepts/ownership-and-access.md          |   5 +-
 docs/getting-started/choose-your-path.md      |  13 +-
 docs/getting-started/quick-start.md           |  36 ++-
 docs/getting-started/what-is-memwal.md        |  13 +-
 docs/indexer/database-sync.md                 |  82 +++++-
 docs/indexer/onchain-events.md                |  20 +-
 docs/indexer/purpose.md                       |  51 +++-
 docs/logo-dark.svg                            |  13 +
 docs/logo-light.svg                           |  13 +
 docs/reference/configuration.md               |   3 +-
 docs/reference/environment-variables.md       |   3 +-
 docs/reference/relayer-api.md                 |  91 ------
 docs/reference/sdk-api.md                     | 101 -------
 docs/relayer/api-reference.md                 | 263 ++++++++++++++++++
 docs/relayer/installation-and-setup.md        | 106 -------
 docs/relayer/overview.md                      |  97 ++++---
 docs/relayer/public-relayer.md                |  41 ++-
 docs/relayer/self-hosting.md                  | 173 ++++++------
 docs/sdk/ai-integration.md                    |   5 +-
 docs/sdk/api-reference.md                     | 205 ++++++++++++++
 docs/sdk/basic-usage.md                       |  46 ---
 docs/sdk/example-map.md                       |   2 +-
 docs/sdk/examples.md                          |  72 +++++
 docs/sdk/overview.md                          |  22 +-
 docs/sdk/quick-start.md                       | 113 +++++---
 docs/sdk/usage.md                             | 140 +---------
 docs/sdk/usage/memwal-manual.md               | 100 +++++++
 docs/sdk/usage/memwal.md                      |  60 ++++
 docs/sdk/usage/with-memwal.md                 |  51 ++++
 42 files changed, 1607 insertions(+), 845 deletions(-)
 delete mode 100644 docs/examples/basic-usage.md
 create mode 100644 docs/examples/example-apps.md
 create mode 100644 docs/logo-dark.svg
 create mode 100644 docs/logo-light.svg
 delete mode 100644 docs/reference/relayer-api.md
 delete mode 100644 docs/reference/sdk-api.md
 create mode 100644 docs/relayer/api-reference.md
 delete mode 100644 docs/relayer/installation-and-setup.md
 create mode 100644 docs/sdk/api-reference.md
 delete mode 100644 docs/sdk/basic-usage.md
 create mode 100644 docs/sdk/examples.md
 create mode 100644 docs/sdk/usage/memwal-manual.md
 create mode 100644 docs/sdk/usage/memwal.md
 create mode 100644 docs/sdk/usage/with-memwal.md

diff --git a/docs/contract/delegate-key-management.md b/docs/contract/delegate-key-management.md
index 2f26ee77..d8ceacdb 100644
--- a/docs/contract/delegate-key-management.md
+++ b/docs/contract/delegate-key-management.md
@@ -2,21 +2,84 @@
 title: "Delegate Key Management"
 ---
 
-Delegate keys are lightweight Ed25519 keys used for SDK authentication.
+Delegate keys are lightweight Ed25519 keys used for SDK authentication. They are registered onchain in a `MemWalAccount` and verified by the relayer on every request.
 
 ## Why They Exist
 
-- apps need a usable key for API calls
-- users should not hand over the owner wallet for day-to-day memory access
+- Apps need a usable key for API calls without exposing the owner wallet
+- Users should not hand over the owner wallet for day-to-day memory access
+- Different apps or devices can each have their own delegate key with a descriptive label
 
-## Main Lifecycle
+## Lifecycle
 
-- create a delegate key
-- register the public key onchain
-- use the private key in the SDK
-- revoke the delegate key when it should stop working
+### 1. Generate a delegate keypair
 
-## Practical Result
+Use the SDK's `generateDelegateKey()` helper to create a new Ed25519 keypair:
 
-Removing a delegate key from the onchain account should prevent future relayer access from that
-key.
+```ts
+import { generateDelegateKey } from "@mysten/memwal/account";
+
+const delegate = await generateDelegateKey();
+// delegate.privateKey — hex string, store securely
+// delegate.publicKey — 32-byte Uint8Array
+// delegate.suiAddress — derived Sui address (0x...)
+```
+
+### 2. Register the public key onchain
+
+Only the account owner can add delegate keys:
+
+```ts
+import { addDelegateKey } from "@mysten/memwal/account";
+
+await addDelegateKey({
+  packageId: "0x...",
+  accountId: "0x...",
+  publicKey: delegate.publicKey,
+  label: "MacBook Pro",
+  suiPrivateKey: "suiprivkey1...", // or walletSigner
+});
+```
+
+### 3. Use the private key in the SDK
+
+```ts
+import { MemWal } from "@mysten/memwal";
+
+const memwal = MemWal.create({
+  key: delegate.privateKey,
+  accountId: "0x...",
+});
+```
+
+### 4. Revoke the delegate key
+
+Removing a delegate key prevents future relayer access from that key:
+
+```ts
+import { removeDelegateKey } from "@mysten/memwal/account";
+
+await removeDelegateKey({
+  packageId: "0x...",
+  accountId: "0x...",
+  publicKey: delegate.publicKey,
+  suiPrivateKey: "suiprivkey1...", // or walletSigner
+});
+```
+
+## Limits
+
+- Each account supports up to **20 delegate keys**
+- Each delegate key must be a valid 32-byte Ed25519 public key
+- Duplicate keys are rejected (error code 0)
+- Only the account owner can add or remove delegate keys
+
+## Account Deactivation
+
+An account owner can deactivate (freeze) their account. When deactivated:
+
+- SEAL decryption access is denied for all keys (owner and delegates)
+- Delegate keys cannot be added or removed
+- The owner can reactivate the account at any time
+
+This is useful as an emergency kill switch if a key is compromised.
diff --git a/docs/contract/overview.md b/docs/contract/overview.md
index ad43c613..b505fac5 100644
--- a/docs/contract/overview.md
+++ b/docs/contract/overview.md
@@ -2,15 +2,90 @@
 title: "Smart Contract Overview"
 ---
 
-The smart contract defines the onchain account model for MemWal.
+The smart contract (`memwal::account`) defines the onchain account model for MemWal. It is a Move module deployed on Sui.
 
-## Current Focus
+## What It Manages
 
-- who owns a MemWal account
-- which delegate keys are allowed to act through the relayer
-- how application access is separated from wallet ownership
+- **Ownership** — who owns a MemWal account
+- **Delegate keys** — which Ed25519 keys are authorized to act through the relayer
+- **SEAL access control** — who can decrypt encrypted memories via `seal_approve`
+- **Account lifecycle** — activation and deactivation (freeze/unfreeze)
 
-## Key Object
+The contract does not store memory content — it only manages identity, permissions, and access control.
 
-The docs refer to the onchain account model as `MemWalAccount`, which holds ownership and
-delegate-key data.
+## Key Objects
+
+### `AccountRegistry`
+
+A shared object created at module publish time. It tracks all MemWalAccount objects and prevents duplicate account creation (one account per Sui address).
+
+### `MemWalAccount`
+
+A shared object representing a single user's account. It stores:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `owner` | `address` | The Sui wallet address that owns this account |
+| `delegate_keys` | `vector<DelegateKey>` | List of authorized Ed25519 delegate keys |
+| `created_at` | `u64` | Timestamp when the account was created (epoch ms) |
+| `active` | `bool` | Whether the account is active (false = frozen) |
+
+### `DelegateKey`
+
+A struct stored inside `MemWalAccount.delegate_keys`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `public_key` | `vector<u8>` | Ed25519 public key (32 bytes) |
+| `sui_address` | `address` | Sui address derived from this Ed25519 key |
+| `label` | `String` | Human-readable label (e.g., "MacBook Pro") |
+| `created_at` | `u64` | Timestamp when the key was added (epoch ms) |
+
+## Limits
+
+- **Maximum delegate keys per account**: 20
+
+## Error Codes
+
+| Code | Name | Description |
+|------|------|-------------|
+| 0 | `EDelegateKeyAlreadyExists` | Key already registered in this account |
+| 1 | `EDelegateKeyNotFound` | Key not found when trying to remove |
+| 2 | `ETooManyDelegateKeys` | Account has reached the 20-key limit |
+| 3 | `EAccountAlreadyExists` | Address already has an account |
+| 4 | `ENotOwner` | Caller is not the account owner |
+| 5 | `EInvalidPublicKeyLength` | Public key is not exactly 32 bytes |
+| 6 | `EAccountDeactivated` | Account is frozen — operation denied |
+| 100 | `ENoAccess` | SEAL access denied — caller is neither owner nor delegate |
+
+## Entry Functions
+
+| Function | Description |
+|----------|-------------|
+| `create_account(registry, clock)` | Create a new MemWalAccount (one per address) |
+| `add_delegate_key(account, public_key, sui_address, label, clock)` | Add a delegate key (owner only) |
+| `remove_delegate_key(account, public_key)` | Remove a delegate key (owner only) |
+| `deactivate_account(account)` | Freeze the account — SEAL access denied, keys locked (owner only) |
+| `reactivate_account(account)` | Unfreeze the account (owner only) |
+| `seal_approve(id, account)` | SEAL policy — authorizes owner or delegate key holder to decrypt |
+
+## View Functions
+
+| Function | Description |
+|----------|-------------|
+| `is_delegate(account, public_key)` | Check if a public key is an authorized delegate |
+| `is_delegate_address(account, addr)` | Check if a Sui address is an authorized delegate |
+| `owner(account)` | Get the owner address |
+| `delegate_count(account)` | Get the number of delegate keys |
+| `has_account(registry, addr)` | Check if an address already has an account |
+| `is_active(account)` | Check if the account is active |
+
+## Events
+
+| Event | Emitted when |
+|-------|-------------|
+| `AccountCreated` | A new account is created |
+| `DelegateKeyAdded` | A delegate key is added to an account |
+| `DelegateKeyRemoved` | A delegate key is removed from an account |
+| `AccountDeactivated` | An account is frozen |
+| `AccountReactivated` | A frozen account is unfrozen |
diff --git a/docs/contract/ownership-and-permissions.md b/docs/contract/ownership-and-permissions.md
index 68c36936..278c31fd 100644
--- a/docs/contract/ownership-and-permissions.md
+++ b/docs/contract/ownership-and-permissions.md
@@ -4,16 +4,46 @@ title: "Ownership and Permissions"
 
 ## Owner
 
-The owner wallet controls the MemWal account model onchain.
+The owner is the Sui wallet address that created the `MemWalAccount`. The owner has full control:
+
+- Add and remove delegate keys
+- Deactivate (freeze) and reactivate the account
+- Decrypt any memory encrypted under their address via SEAL
+
+Each Sui address can only create **one** MemWalAccount (enforced by the `AccountRegistry`).
 
 ## Delegate
 
-The delegate key authenticates API calls through the relayer.
+A delegate key authenticates API calls through the relayer. Delegates can:
+
+- Store memories (`remember`, `analyze`)
+- Recall memories (`recall`)
+- Restore namespaces (`restore`)
+- Decrypt SEAL-encrypted content (via `seal_approve`)
+
+Delegates **cannot**:
+
+- Add or remove other delegate keys
+- Deactivate or reactivate the account
+- Transfer ownership
+
+## SEAL Access Control
+
+The contract's `seal_approve` function is the SEAL policy that controls who can decrypt memories. Access is granted if the caller is:
+
+1. **The data owner** — the key ID ends with the BCS-encoded owner address and the caller is the account owner
+2. **A registered delegate** — the caller's Sui address is in the account's `delegate_keys` list
+
+The account must also be **active** (not frozen). If the account is deactivated, all SEAL access is denied.
 
 ## Permission Boundary
 
-The docs should treat these as separate layers:
+These are separate layers that work together:
+
+| Layer | Controls | Enforced by |
+|-------|----------|-------------|
+| **Owner** | Account control — keys, activation, ownership | Sui smart contract |
+| **Delegate** | Application access — read/write memory | Sui smart contract + relayer verification |
+| **Relayer** | Backend execution — encryption, storage, search | Server-side auth middleware |
 
-- owner-level account control
-- delegate-level application access
-- relayer-level backend execution
+The relayer verifies every request against the onchain contract before executing any operation. Even if the relayer is compromised, it cannot forge delegate permissions or change ownership — those are cryptographically enforced onchain.
diff --git a/docs/contributing/run-docs-locally.md b/docs/contributing/run-docs-locally.md
index 18443bf3..52edd9dd 100644
--- a/docs/contributing/run-docs-locally.md
+++ b/docs/contributing/run-docs-locally.md
@@ -9,7 +9,7 @@ pnpm install
 pnpm dev:docs
 ```
 
-This starts the Docusaurus site using the docs in this repository.
+This starts the Mintlify site using the docs in this repository.
 
 ## Build the Docs
 
diff --git a/docs/contributing/run-repo-locally.md b/docs/contributing/run-repo-locally.md
index ac7ca7b4..7d5bae4e 100644
--- a/docs/contributing/run-repo-locally.md
+++ b/docs/contributing/run-repo-locally.md
@@ -7,7 +7,7 @@ This monorepo contains:
 - TypeScript applications under `apps/`
 - the SDK under `packages/sdk`
 - Rust backend services under `services/`
-- Docusaurus docs under `docs/`
+- Mintlify docs under `docs/`
 
 ## Common Local Entry Points
 
@@ -37,5 +37,4 @@ For relayer-oriented local work you will typically need:
 
 If you want to run the backend locally, start with the Relayer docs:
 
-- [Installation and Setup](/relayer/installation-and-setup)
-- [Operate Your Own Relayer](/relayer/self-hosting)
+- [Self-Hosting](/relayer/self-hosting)
diff --git a/docs/docs.json b/docs/docs.json
index 7d0d6890..3f7e4995 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -3,30 +3,34 @@
   "theme": "mint",
   "name": "MemWal",
   "description": "Privacy-preserving decentralized memory protocol for humans and AI agents",
+  "logo": {
+    "light": "/logo-light.svg",
+    "dark": "/logo-dark.svg"
+  },
   "favicon": "/favicon.ico",
   "colors": {
     "primary": "#191a23",
-    "light": "#98efe4",
+    "light": "#E8FF75",
     "dark": "#191a23"
   },
   "appearance": {
     "default": "system"
   },
   "banner": {
-    "content": "**MemWal is in active beta.** APIs and features may evolve between releases.",
+    "content": "MemWal is in beta with ongoing improvements to APIs and features based on developer feedback.",
     "dismissible": false
   },
   "navbar": {
     "links": [
       {
         "label": "GitHub",
-        "href": "https://github.com/CommandOSSLabs/personal-data-wallet"
+        "href": "https://github.com/CommandOSSLabs/memwal"
       }
     ]
   },
   "footer": {
     "socials": {
-      "github": "https://github.com/CommandOSSLabs/personal-data-wallet"
+      "github": "https://github.com/CommandOSSLabs/memwal"
     }
   },
   "navigation": {
@@ -44,6 +48,17 @@
           }
         ]
       },
+      {
+        "tab": "Examples",
+        "groups": [
+          {
+            "group": "Examples",
+            "pages": [
+              "examples/example-apps"
+            ]
+          }
+        ]
+      },
       {
         "tab": "Fundamentals",
         "groups": [
@@ -70,14 +85,17 @@
           {
             "group": "SDK",
             "pages": [
-              "sdk/overview",
               "sdk/quick-start",
-              "sdk/usage",
-              "sdk/ai-integration",
-              "sdk/basic-usage",
-              "sdk/advanced-usage",
-              "sdk/research-app-example",
-              "sdk/example-map"
+              {
+                "group": "Usage",
+                "root": "sdk/usage",
+                "pages": [
+                  "sdk/usage/memwal",
+                  "sdk/usage/memwal-manual",
+                  "sdk/usage/with-memwal"
+                ]
+              },
+              "sdk/api-reference"
             ]
           }
         ]
@@ -90,8 +108,8 @@
             "pages": [
               "relayer/overview",
               "relayer/public-relayer",
-              "relayer/installation-and-setup",
-              "relayer/self-hosting"
+              "relayer/self-hosting",
+              "relayer/api-reference"
             ]
           }
         ]
@@ -128,8 +146,6 @@
           {
             "group": "Reference",
             "pages": [
-              "reference/sdk-api",
-              "reference/relayer-api",
               "reference/configuration",
               "reference/environment-variables"
             ]
diff --git a/docs/examples/basic-usage.md b/docs/examples/basic-usage.md
deleted file mode 100644
index ff584bef..00000000
--- a/docs/examples/basic-usage.md
+++ /dev/null
@@ -1,65 +0,0 @@
-# Basic Usage
-
-## Installation
-
-First, install the MemWal SDK:
-
-```bash
-pnpm add @cmdoss/memwal
-```
-
-## Initialize
-
-```typescript
-import { MemWal } from '@cmdoss/memwal'
-
-const memwal = new MemWal({
-  network: 'testnet',
-  packageId: '0xcf6ad755a1cdff7217865c796778fabe5aa399cb0cf2eba986f4b582047229c6',
-  registryId: '0xe80f2feec1c139616a86c9f71210152e2a7ca552b20841f2e192f99f75864437',
-})
-```
-
-## Connect Wallet
-
-```typescript
-// Using Enoki zkLogin (Google)
-await memwal.connectEnoki()
-
-// Or using Sui wallet
-await memwal.connectWallet()
-```
-
-## Store Memory
-
-```typescript
-const memory = await memwal.addMemory({
-  content: 'Your memory content here',
-  metadata: {
-    type: 'note',
-    tags: ['important', 'work']
-  }
-})
-
-console.log('Memory ID:', memory.id)
-```
-
-## Search Memories
-
-```typescript
-const results = await memwal.search('search query', {
-  limit: 10
-})
-
-results.forEach(memory => {
-  console.log(memory.content)
-})
-```
-
-## Get All Memories
-
-```typescript
-const allMemories = await memwal.getMemories()
-
-console.log(`Found ${allMemories.length} memories`)
-```
diff --git a/docs/examples/example-apps.md b/docs/examples/example-apps.md
new file mode 100644
index 00000000..2a6c7da8
--- /dev/null
+++ b/docs/examples/example-apps.md
@@ -0,0 +1,84 @@
+---
+title: "Example Apps"
+description: "Short examples showing how each demo app uses MemWal."
+---
+
+The repo includes ready-to-run apps in `apps/` that show different MemWal integration patterns.
+This page focuses on app-level patterns,the basic SDK flow covered in [Quick Start](/sdk/quick-start) and [MemWal Usage](/sdk/usage/memwal).
+
+## Run Locally
+
+```bash
+pnpm dev:app
+pnpm dev:chatbot
+pnpm dev:noter
+pnpm dev:researcher
+```
+
+## [App](https://github.com/MystenLabs/MemWal/tree/main/apps/app)
+
+Onboarding app, account dashboard, playground, and interactive demo for MemWal.
+
+```ts
+const memwal = MemWal.create({
+  key: delegateKey,
+  accountId: accountObjectId,
+  serverUrl,
+  namespace,
+});
+
+await memwal.remember(rememberText);
+await memwal.recall(recallQuery, 5);
+await memwal.analyze(analyzeText);
+```
+
+This app covers the full getting-started flow in one place. It signs users in, sets up delegate keys, shows SDK credentials, and includes a live playground for `remember()`, `recall()`, `analyze()`, `restore()`, AI middleware, and manual mode.
+
+## [Chatbot](https://github.com/MystenLabs/MemWal/tree/main/apps/chatbot)
+
+AI chat app with persistent memory across sessions.
+
+```ts
+import { withMemWal } from "@mysten/memwal/ai";
+
+const model = withMemWal(baseModel, {
+  key,
+  accountId,
+  serverUrl,
+  maxMemories: 5,
+  autoSave: true,
+});
+```
+
+This app shows AI middleware integration in a production-style chat app. The UI can enable MemWal, collect a delegate key and account ID, and pass them to the chat API. The server wraps the selected model with `withMemWal`, so recall happens before generation and new context can be auto-saved after each turn.
+
+## [Noter](https://github.com/MystenLabs/MemWal/tree/main/apps/noter)
+
+Note-taking app that stores insights as encrypted, searchable memory.
+
+```ts
+export const extractMemories = async (text: string): Promise<string[]> => {
+  const memwal = getMemWalClient();
+  const result = await memwal.analyze(text);
+  return (result.facts ?? []).map((f) => f.text);
+};
+```
+
+This app shows note-to-memory extraction. Noter keeps a shared server-side MemWal client, lets the user configure the key and account at runtime, and uses `analyze()` to turn note content into structured facts that can be reused by the editor and AI features.
+
+## [Researcher](https://github.com/MystenLabs/MemWal/tree/main/apps/researcher)
+
+Research assistant that saves and recalls findings across sessions.
+
+```ts
+const fullText =
+  `Sprint Report: ${title}\n\n` +
+  `${content}\n\n` +
+  `References:\n${references}\n\n` +
+  `Sources: ${sourceList}`;
+
+await memwal.remember(fullText);
+const { results } = await memwal.recall(query, 5);
+```
+
+This app shows long-form research memory and session rehydration. Researcher saves each sprint as a structured report in MemWal, then generates recall queries from sprint metadata, pulls back the most relevant findings, and rebuilds context for a fresh session.
diff --git a/docs/favicon.ico b/docs/favicon.ico
index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..4c43716e789d21f675d08ee0e496c96ec4f2250b 100644
GIT binary patch
literal 32038
zcmeHQ>u(iB6kikmfJSI3FS)newznc}DMH(nN?U88(n~GS7E_BTMK1IKeWPMT5Wy&q
z1XKcOLJS}QV*H>+BgiK~X?TeE2r5X$aw!l$s3<;;=gi){-Cbw)-sL6AX>z)|voq(+
z&ir=f%sI2?YT9jDKdqoZ!=p#@7in6FrfHd(`t=*hn%0DA9#8l>PSX;Cnihvg${*~f
zX?quGnjgy`3vCG!rHj7;{b2sz4rf70fAzqO-LFBaF9}8r9^^=AX{k{A!A><ViJYeM
zUqH_EDUN(qaz_{C!@QFRUCC2Er=)HoFF!x`KjWX@e;)s$j?p~+^Zdv2KkGkkbS&2Y
zSpQ}HpVvRCHJ(#Cum5=c%j<u(f4I>%T<2x`58Hp({=@bkw*RpGhy5Rp7-0J!+yB`9
z$M!!rIyT$?*#5`%Keqol+4)rW*#5`%KeqqfME1WsZ*Be8f5rRX0*>pd>plK;z&TJ+
zJA{P&FWEaBk`fXeDK*6>_WyNY85KW!`htsJLiW_jj(k;eGbiN1{8L>q%d*Qhu3LUN
z1yZ`Cr$6}C7D&$>3nMc}Ia205xlp@jm(D9(R?62Tuc7Bt$e&%~$X6vdXIcP)C-%$h
zZjuqL4wYM9foK$1y%fq`c-oNyYnMgkW0zC4V-r+tTII-BCAWP2N~qkn!L>|#9Y$u{
z1xm_Fhq4!!K=V)ELd&n;LCYlxQ99DXA5TEZ;%2=sop_q=jVmvO;8!2%yjA?|GQ;xb
zpX`F%>Ic+yH_1^xALdbwFO=>ZHWW&iErQm|-$&hNOE@cPo(sMqgB^LA<<UD6{Q5vt
z-m*1iefMD)GqEscS!TJG^FfI)LP5TvgJIIrPH6o-hUdqADq1*KuaAPCT~0=R&ec7C
zNrAHNc3H}62fL<k=n!}PPtWhB|MRc1|4Xhx|MT-J-y!aQ#=ooapWlBT|9JdYj;9vA
z1LvJgp8u{=|Ka)Hj;U*T&GSFc|2+S@SpTyA!}<^FKdk>a*c8n3^Ua|DnPUO)`K{Li
z6ej{hOK7u@B5@*ocwzgK*<jmoe|%u=v&u1_?8g<GS4Xk$hM=kUa~K<#2uX<p9mkF&
zw5u9^HuB#{>!gb1AWP@^V;ge&UonmtKa3yQxDsm`<A?DRD^_Ir7(a|387^W?WBf3F
zV#SIqALEDdBf~|kX^bDnPpnvx<zxIXeq^|aHI4DZ_=y!OvV4pmclb%XmiF5aMC{Mx
zZ;|Y|^$i;mwm)NDv~$Ysd?x$nzyv8DgE!fy{b?!T?;Ls+{N(YJgC`E)etkRbhpC&_
zU<~8{WaEB*E0sY`RXI$5{UxzS=AUK5ym0^YoTDGYy>0d4TMGIvz{<yTJ+%z-YOA2;
z?X58Hn~x>+vDdHfn)Yg22=^|HE*uZjwyXpCj+bosGAe)hd7y7KEM-l+Xb*Jmj0%`@
zY@Z_^!5if?oH+s|Pc}ow_#7oqnJly4O`IcMgnt6RKXCFTl&yM3_iqrsBz`@@L`GgV
zw&y3vM};v16Cv@v#)NsZbYF*pr%aA4&36a-S492Qa;g5bk6l)t(#WThG2U(cABpO#
zQOPr>bN#vf&3JHo&iG;cxW$Y)KjVk-W5$EqbH)$j$1P^e`TtA!v26$9%NyJRv`@=}
zRDcxOr-i@yWB)U+aog~_)uIKDK@zQN!)q5hFYauFwm*NctY2yE(ir*-vhFLu{E~fG
zxK5yNyrZvijJ3{LVENqsj6Z(=c>Lk<m**e-_w#uE{lDuUhOZ$6ZGW7BLe#&!@$tg1
zK(<zILVQ^N>IwTK^!#LlZVVlVtl|k64@uA8=XXdH_SV1}(!Xfmd!G#ZdFyZ8An0;8
zwETP$iaQ!a{BD10G7!;kIhH)tB4XLJVxCBT)D;`f9EEXHCRy_9<$OT#ou;gNPQ*fq
zlrdzPj)hHgz@Vb$AXIMO05kXQ7O{~iJ`$aiPlIBm82QApu};|a$u~jy>_p`%Hm<Uk
zG08G`k?yKf0wfO~1~u<)hfcVN?ba)Z&gnNT>DyL%7mfVXN9oyjL;dMPnEyf~e_y!^
z`1~uvW%|k)<&C2;&Qaf`cs)?_&Njiz(94Nm^{!V%-9-NydO7+LD9)4-)5^$i9I4-_
z{UiJ(z6i^`>mq*z%a7LX#(i%8>wtg8pXD7lux2{i?EyFXn(P#0mhd1&>=gK$#P&a$
zw<xX}#X$28=#M_@GBIC?d9df0@b8jumE!;9&8)&0WZf2f1((0Y+7ERMV=km)C!7~L
z41G5^JT4BhD<-2Zb6U*ZP3Mk_xzsyg0C@V}4tWn%3VT-vmNDjY(gCV>Zidq3kBhw%
zrOTfX^D?DZ?bryDmb620djnEE+`n>h<R0B8qBv)181uC5$Q~hccGvsh_os;YF+B(M
zi0(rui(+f`!o&OCgp?6p;fE)^gNWvS%3pU_FaPMl_k@l`I?1SUV=U!oVtI<eY1S9i
e<p;v3Y%Gs@j3J-Or%-v*IPq_nw~q&Ium1*+ceZH&

literal 0
HcmV?d00001

diff --git a/docs/fundamentals/architecture/core-components.md b/docs/fundamentals/architecture/core-components.md
index a1e73db0..28cd8cea 100644
--- a/docs/fundamentals/architecture/core-components.md
+++ b/docs/fundamentals/architecture/core-components.md
@@ -38,6 +38,7 @@ The TypeScript SDK is the main entry point for developers. It wraps all MemWal o
 ```ts
 const memwal = MemWal.create({
   key: process.env.MEMWAL_PRIVATE_KEY!,
+  accountId: process.env.MEMWAL_ACCOUNT_ID!,
   serverUrl: process.env.MEMWAL_SERVER_URL,
   namespace: "my-app",
 });
@@ -58,7 +59,7 @@ This means Web2 developers can integrate MemWal without touching wallets, signin
 - Encrypts and decrypts memory payloads
 - Uploads and downloads blobs to/from Walrus
 - Stores and searches vector metadata in the indexed database
-- Scopes all operations to `owner + namespace + app_id`
+- Scopes all operations to `owner + namespace` (with SEAL encryption bound to the app's package ID)
 - Can sponsor transaction and storage fees for user requests
 
 <Note>
@@ -101,11 +102,17 @@ Walrus is an external protocol — MemWal uses it as infrastructure, not as some
 
 ## Indexed Database
 
-PostgreSQL with pgvector serves as the local search and sync layer.
+PostgreSQL with the [pgvector](https://github.com/pgvector/pgvector) extension serves as the local search and sync layer.
+
+**Key tables:**
+- `vector_entries` — stores 1536-dimensional embeddings linked to Walrus blob IDs, with an HNSW index for fast cosine similarity search
+- `delegate_key_cache` — caches delegate key → account mappings for fast auth
+- `accounts` — synced by the indexer for account lookups
+- `indexer_state` — tracks the indexer's event polling cursor
 
 **Responsibilities:**
 - Stores vector embeddings for semantic search during recall
 - Caches account and delegate data synced by the indexer
-- Scopes all queries to `owner + namespace + app_id`
+- Scopes all queries to `owner + namespace` (package ID provides cross-deployment isolation via SEAL)
 
-This is an operational component — it makes recall fast and keeps onchain lookups efficient, but the encrypted source of truth always lives on Walrus.
+This is an operational component — it makes recall fast and keeps onchain lookups efficient, but the encrypted source of truth always lives on Walrus. If the database is lost, the [restore flow](/sdk/usage/memwal) can rebuild it from Walrus.
diff --git a/docs/fundamentals/architecture/data-flow-security-model.md b/docs/fundamentals/architecture/data-flow-security-model.md
index 1ec3e15a..87ad249e 100644
--- a/docs/fundamentals/architecture/data-flow-security-model.md
+++ b/docs/fundamentals/architecture/data-flow-security-model.md
@@ -31,6 +31,12 @@ This means the **relayer operator can see your data in transit**. This is simila
 
 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 |
+| **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.
 - **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.
@@ -59,6 +65,17 @@ flowchart LR
 - **Offchain (operator trust)**: encryption, embedding, search — handled by the relayer and indexed database
 - **Decentralized (durable)**: encrypted memory payloads — stored on Walrus, no single point of failure
 
+## Authentication flow
+
+Every protected API call goes through Ed25519 signature verification:
+
+1. The SDK signs a message: `{timestamp}.{method}.{path}.{body_sha256}` using the delegate private key
+2. The relayer verifies the Ed25519 signature against the provided public key
+3. Timestamps must be within a **5-minute window** to prevent replay attacks
+4. The relayer resolves the public key to a `MemWalAccount` using the priority chain: cache → indexed accounts → onchain registry → header hint → config fallback
+5. The onchain account is fetched to verify the delegate key is registered in `delegate_keys`
+6. The resolved owner address is used to scope all subsequent operations
+
 ## Current status
 
 This describes the production beta model. The trust boundaries are designed to evolve — future versions may introduce client-side encryption by default or additional verifiability layers. Self-hosting remains the strongest option for teams that need full control today.
diff --git a/docs/fundamentals/architecture/how-storage-works.md b/docs/fundamentals/architecture/how-storage-works.md
index e5757b8b..5407cd43 100644
--- a/docs/fundamentals/architecture/how-storage-works.md
+++ b/docs/fundamentals/architecture/how-storage-works.md
@@ -47,7 +47,7 @@ sequenceDiagram
   <Step>
     ### Vector indexing
 
-    The vector embedding, along with the blob ID, owner address, namespace, and app ID, is stored in the indexed database (PostgreSQL + pgvector). This is the searchable index that powers recall.
+    The vector embedding (1536-dimensional, generated by `text-embedding-3-small`), along with the blob ID, owner address, and namespace, is stored in the `vector_entries` table in PostgreSQL with pgvector. An HNSW index on the embedding column enables fast approximate nearest neighbor search during recall.
   </Step>
 </Steps>
 
@@ -63,7 +63,7 @@ sequenceDiagram
 
     App->>Relayer: query ("What does this user prefer?")
     Relayer->>Relayer: generate query embedding
-    Relayer->>DB: vector search (owner + namespace + app_id)
+    Relayer->>DB: vector search (owner + namespace)
     DB-->>Relayer: matching blob IDs
     Relayer->>Walrus: download encrypted blobs
     Walrus-->>Relayer: encrypted payloads
@@ -73,16 +73,51 @@ sequenceDiagram
 ```
 
 1. Your query is converted into a vector embedding
-2. The database is searched for the closest matching vectors, scoped to your memory space (`owner + namespace + app_id`)
-3. Matching encrypted blobs are downloaded from Walrus
-4. The blobs are decrypted via SEAL
-5. Plaintext results are returned to your app
+2. The database is searched for the closest matching vectors using pgvector's cosine distance operator (`<=>`), scoped to your memory space (`owner + namespace`)
+3. Matching encrypted blobs are downloaded from Walrus concurrently
+4. Each blob is decrypted via SEAL using the delegate key
+5. Plaintext results are returned to your app, sorted by distance (most relevant first)
+
+<Note>
+If a blob has expired on Walrus (returns 404), the relayer automatically deletes the stale vector entry from the database. This reactive cleanup keeps your recall results clean without manual intervention.
+</Note>
+
+## Restoring a memory space
+
+If the local database is lost or incomplete, the restore flow rebuilds it from Walrus — the permanent source of truth.
+
+```mermaid
+sequenceDiagram
+    participant App as Your App
+    participant Relayer as Relayer
+    participant Chain as Sui Chain
+    participant Walrus as Walrus
+    participant DB as Indexed Database
+
+    App->>Relayer: restore("my-namespace")
+    Relayer->>Chain: query blobs by owner + namespace
+    Chain-->>Relayer: blob IDs (on-chain metadata)
+    Relayer->>DB: check which blobs already exist locally
+    DB-->>Relayer: existing blob IDs
+    Relayer->>Walrus: download missing blobs
+    Walrus-->>Relayer: encrypted payloads
+    Relayer->>Relayer: SEAL decrypt + re-embed
+    Relayer->>DB: insert new vector entries
+    Relayer-->>App: restored count
+```
+
+1. The relayer queries on-chain Walrus blob objects owned by the user, filtered by namespace metadata
+2. It compares against the local database to find which blobs are already indexed
+3. Only missing blobs are downloaded, decrypted, re-embedded, and re-indexed
+4. The restore supports a configurable `limit` (default: 50) to control how many blobs are processed per call
+
+Restore is incremental and idempotent — you can call it multiple times safely.
 
 ## Two layers, one system
 
 | Layer | Stores | Purpose |
 |-------|--------|---------|
 | **Walrus** | Encrypted blobs | Durable, decentralized source of truth |
-| **Indexed Database** | Vector embeddings + metadata | Fast semantic search for recall |
+| **PostgreSQL + pgvector** | Vector embeddings + metadata | Fast semantic search for recall |
 
-The indexed database is rebuildable — if it's ever lost, the [restore flow](/sdk/usage) can rediscover blobs from Walrus by owner and namespace, then re-embed and re-index them. Walrus is the permanent record.
+The database is rebuildable — if it's ever lost, the restore flow can rediscover blobs from Walrus by owner and namespace, then re-embed and re-index them. Walrus is the permanent record.
diff --git a/docs/fundamentals/concepts/memory-space.md b/docs/fundamentals/concepts/memory-space.md
index 12f2a1a5..02e92bb7 100644
--- a/docs/fundamentals/concepts/memory-space.md
+++ b/docs/fundamentals/concepts/memory-space.md
@@ -15,9 +15,9 @@ Every memory space is uniquely identified by three values:
 |-----------|-----------|
 | **Owner address** | The Sui wallet address that owns the memory |
 | **Namespace** | A developer-defined label to group and organize memories |
-| **App ID** | A globally unique identifier for the deployed MemWal instance |
+| **App ID** | The MemWal package ID (`MEMWAL_PACKAGE_ID`) — unique per relayer deployment |
 
-Together, `owner_address + namespace + app_id` form the boundary — no two memory spaces can overlap.
+Together, `owner + namespace + app_id` form the boundary — no two memory spaces can overlap.
 
 ## Namespace
 
@@ -33,6 +33,7 @@ Namespaces are set in the SDK when you create a client:
 ```ts
 const memwal = MemWal.create({
   key: process.env.MEMWAL_PRIVATE_KEY!,
+  accountId: process.env.MEMWAL_ACCOUNT_ID!,
   serverUrl: process.env.MEMWAL_SERVER_URL,
   namespace: "personal",
 });
@@ -40,9 +41,9 @@ const memwal = MemWal.create({
 
 ## App ID
 
-MemWal is not a singleton service — developers can clone the repo and run their own deployed instance. The **app ID** is a globally unique identifier for each deployment, ensuring that different apps don't clash on the same owner + namespace combination.
+The **app ID** is the MemWal package ID deployed on Sui (`MEMWAL_PACKAGE_ID`). Each relayer deployment is tied to a single package ID, which is used for SEAL encryption key derivation and Walrus blob metadata.
 
-Two separate MemWal deployments can each have a user with a `personal` namespace, and their memories will never mix — because the app ID is different.
+Two separate MemWal deployments can each have a user with a `personal` namespace, and their memories will never mix — because the app ID (package ID) is different. This means the vector database scopes queries by `owner + namespace`, while the encryption and blob discovery layer provides an additional isolation boundary through the package ID.
 
 ## How it works in practice
 
diff --git a/docs/fundamentals/concepts/ownership-and-access.md b/docs/fundamentals/concepts/ownership-and-access.md
index 07d915c2..d5561a24 100644
--- a/docs/fundamentals/concepts/ownership-and-access.md
+++ b/docs/fundamentals/concepts/ownership-and-access.md
@@ -11,7 +11,8 @@ Memory content in MemWal is stored on Walrus and cryptographically owned by a us
 
 ```ts
 const memwal = MemWal.create({
-  key: process.env.MEMWAL_PRIVATE_KEY!, // owner's private key
+  key: process.env.MEMWAL_PRIVATE_KEY!, // delegate private key
+  accountId: process.env.MEMWAL_ACCOUNT_ID!, // MemWalAccount object ID
   serverUrl: process.env.MEMWAL_SERVER_URL,
   namespace: "personal",
 });
@@ -46,7 +47,7 @@ flowchart TD
     D3 -->|reads| Memory
 ```
 
-## Acess Control Enforcement
+## Access Control Enforcement
 
 The relationship between owners and delegates is enforced on chain by the Sui smart contract system — not by application logic or database permissions.
 
diff --git a/docs/getting-started/choose-your-path.md b/docs/getting-started/choose-your-path.md
index 1f7d8d6c..731ebcba 100644
--- a/docs/getting-started/choose-your-path.md
+++ b/docs/getting-started/choose-your-path.md
@@ -10,7 +10,7 @@ These paths aren't mutually exclusive. You can combine them — for example, use
 
 ## 1. Default SDK
 
-Use `@cmdoss/memwal` when you want the fastest working integration.
+Use `@mysten/memwal` when you want the fastest working integration.
 
 - relayer handles embedding, encryption, retrieval, and restore
 - best starting point for most teams
@@ -21,11 +21,16 @@ Go to: [SDK Overview](/sdk/overview)
 
 Use this when you want to evaluate MemWal without running the backend yourself.
 
+| Network | Relayer URL |
+|---|---|
+| **Testnet** (staging) | `https://relayer.staging.memwal.ai` |
+| **Mainnet** (production) | `https://relayer.memwal.ai` |
+
 Go to: [Public Relayer](/relayer/public-relayer)
 
 ## 3. Manual Client Flow
 
-Use `@cmdoss/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/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
@@ -34,9 +39,9 @@ Go to: [SDK Usage](/sdk/usage)
 
 ## 4. AI Middleware
 
-Use `@cmdoss/memwal/ai` when you already use the AI SDK and want recall plus auto-save behavior.
+Use `@mysten/memwal/ai` when you already use the AI SDK and want recall plus auto-save behavior.
 
-Go to: [AI Integration](/sdk/ai-integration)
+Go to: [AI Integration](/sdk/usage/with-memwal)
 
 ## 5. Self-Host the Relayer
 
diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md
index 8c906d1e..e1e46bf3 100644
--- a/docs/getting-started/quick-start.md
+++ b/docs/getting-started/quick-start.md
@@ -8,7 +8,10 @@ The fastest way to get MemWal running is through the TypeScript SDK.
 
 - [Node.js](https://nodejs.org/) v18+ or [Bun](https://bun.sh/) v1+
 - A delegate key (Ed25519 private key in hex)
-- A relayer URL — use the [public relayer](/relayer/public-relayer) to get started
+- 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
 
@@ -19,29 +22,29 @@ The fastest way to get MemWal running is through the TypeScript SDK.
     <Tabs>
       <Tab title="pnpm">
         ```bash
-        pnpm add @cmdoss/memwal
+        pnpm add @mysten/memwal
         ```
       </Tab>
       <Tab title="npm">
         ```bash
-        npm install @cmdoss/memwal
+        npm install @mysten/memwal
         ```
       </Tab>
       <Tab title="yarn">
         ```bash
-        yarn add @cmdoss/memwal
+        yarn add @mysten/memwal
         ```
       </Tab>
       <Tab title="bun">
         ```bash
-        bun add @cmdoss/memwal
+        bun add @mysten/memwal
         ```
       </Tab>
     </Tabs>
 
     **Optional packages**
 
-    For AI middleware with [Vercel AI SDK](https://sdk.vercel.ai/) (`@cmdoss/memwal/ai`):
+    For AI middleware with [Vercel AI SDK](https://sdk.vercel.ai/) (`@mysten/memwal/ai`):
 
     <Tabs>
       <Tab title="pnpm">
@@ -66,7 +69,7 @@ The fastest way to get MemWal running is through the TypeScript SDK.
       </Tab>
     </Tabs>
 
-    For the [manual client flow](/getting-started/choose-your-path) (`@cmdoss/memwal/manual`):
+    For the [manual client flow](/getting-started/choose-your-path) (`@mysten/memwal/manual`):
 
     <Tabs>
       <Tab title="pnpm">
@@ -95,17 +98,26 @@ The fastest way to get MemWal running is through the TypeScript SDK.
   <Step>
     ### Configure the SDK
 
-    Set up the SDK with your delegate key and relayer URL:
+    Set up the SDK with your delegate key, account ID, and relayer URL:
 
     ```ts
-    import { MemWal } from "@cmdoss/memwal";
+    import { MemWal } from "@mysten/memwal";
 
     const memwal = MemWal.create({
-      key: process.env.MEMWAL_PRIVATE_KEY!,
-      serverUrl: process.env.MEMWAL_SERVER_URL,
+      key: "<your-ed25519-private-key>",
+      accountId: "<your-memwal-account-id>",
+      serverUrl: "https://relayer.memwal.ai",
       namespace: "my-app",
     });
     ```
+
+    <Tip>
+    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.
+    </Tip>
+
+    <Note>
+    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.
+    </Note>
   </Step>
 
   <Step>
@@ -128,6 +140,6 @@ The fastest way to get MemWal running is through the TypeScript SDK.
     console.log(result.results);
     ```
 
-    That's it — you're up and running.
+    That's it - you're up and running.
   </Step>
 </Steps>
diff --git a/docs/getting-started/what-is-memwal.md b/docs/getting-started/what-is-memwal.md
index ea6f8887..96039af3 100644
--- a/docs/getting-started/what-is-memwal.md
+++ b/docs/getting-started/what-is-memwal.md
@@ -1,9 +1,9 @@
 ---
 title: "What is MemWal?"
-description: "Privacy-preserving, decentralized memory protocol for humans and AI agents — powered by Walrus and Sui."
+description: "Privacy-preserving, decentralized memory layer for humans and AI agents — powered by Walrus and Sui."
 ---
 
-MemWal is a privacy-preserving, decentralized memory protocol for humans and AI agents — powered by Walrus and Sui. Store, recall, and share memory across apps, sessions, and agents.
+MemWal is a privacy-preserving, decentralized memory layer for humans and AI agents — powered by Walrus and Sui. Store, recall, and share memory across apps, sessions, and agents.
 
 <CardGroup cols={2}>
   <Card title="End-to-End Encrypted" icon="lock">
@@ -86,7 +86,7 @@ AI agents today lose context between sessions — every conversation starts from
 
 ## Use Cases
 
-MemWal fits any app or protocol that needs to store, retrieve, and update memory persistently:
+MemWal fits any app that needs to store, retrieve, and update memory persistently:
 
 - **AI chat apps** — capture valuable knowledge from conversations so agents remember context across sessions
 - **Note-taking and knowledge tools** — save user insights, summaries, and references as persistent, encrypted memory
@@ -100,10 +100,13 @@ And many more — check out the example apps below to see MemWal in action.
 
 The repo ships with ready-to-run apps in the [`/apps`](https://github.com/CommandOSSLabs/memwal/tree/main/apps) directory:
 
+- **App** — dashboard demo for zkLogin, delegate-key setup, and account management
 - **Chatbot** — AI chat app with persistent memory across sessions
 - **Noter** — note-taking tool that stores knowledge as encrypted memory
 - **Researcher** — research assistant that builds and recalls a knowledge base
 
+See [Example Apps](/examples/example-apps) for short code examples from each app.
+
 ## Explore the Docs
 
 <CardGroup cols={2}>
@@ -113,7 +116,7 @@ The repo ships with ready-to-run apps in the [`/apps`](https://github.com/Comman
   <Card title="Architecture" icon="building" href="/fundamentals/architecture/core-components">
     System overview, component responsibilities, core flows, data flow security
   </Card>
-  <Card title="SDK" icon="box" href="/sdk/overview">
+  <Card title="SDK" icon="box" href="/sdk/quick-start">
     Quickstart, usage patterns, AI integration, and examples
   </Card>
   <Card title="Relayer" icon="tower-broadcast" href="/relayer/overview">
@@ -125,7 +128,7 @@ The repo ships with ready-to-run apps in the [`/apps`](https://github.com/Comman
   <Card title="Indexer" icon="magnifying-glass" href="/indexer/purpose">
     Event indexing, onchain events, database sync
   </Card>
-  <Card title="Reference" icon="book" href="/reference/sdk-api">
+  <Card title="Reference" icon="book" href="/sdk/api-reference">
     SDK API, relayer API, configuration, environment variables
   </Card>
 </CardGroup>
diff --git a/docs/indexer/database-sync.md b/docs/indexer/database-sync.md
index 63b6a3ac..1848a29c 100644
--- a/docs/indexer/database-sync.md
+++ b/docs/indexer/database-sync.md
@@ -2,15 +2,81 @@
 title: "Database Sync"
 ---
 
-The indexer syncs account data into PostgreSQL so the relayer can resolve ownership quickly.
+The indexer syncs account data into PostgreSQL so the relayer can resolve ownership quickly without hitting the blockchain on every request.
 
-## Current Stored State
+## Database
 
-- `accounts`
-- `indexer_state`
+Both the relayer and the indexer connect to the same PostgreSQL instance (with the `pgvector` extension enabled). Migrations run automatically on boot.
 
-## Why It Helps
+## Tables
 
-- avoids repeated onchain registry scans during auth
-- keeps a resumable cursor for long-running event polling
-- makes account lookup effectively constant-time for the backend
+### `vector_entries`
+
+The primary search table — stores vector embeddings linked to encrypted Walrus blobs.
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | `TEXT` (PK) | UUID for this entry |
+| `owner` | `TEXT` | Owner's Sui address |
+| `namespace` | `TEXT` | Namespace label (default: `"default"`) |
+| `blob_id` | `TEXT` | Walrus blob ID pointing to the encrypted payload |
+| `embedding` | `vector(1536)` | 1536-dimensional vector embedding (pgvector) |
+| `created_at` | `TIMESTAMPTZ` | Insertion timestamp |
+
+**Indexes:**
+- `idx_vector_entries_owner` — B-tree on `owner`
+- `idx_vector_entries_blob_id` — B-tree on `blob_id`
+- `idx_vector_entries_owner_ns` — composite B-tree on `(owner, namespace)` for scoped queries
+- `idx_vector_entries_embedding` — HNSW on `embedding` using `vector_cosine_ops` for fast similarity search
+
+### `delegate_key_cache`
+
+Auth optimization — caches the mapping from delegate public key to account, so the relayer doesn't need to scan the onchain registry on every request.
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `public_key` | `TEXT` (PK) | Hex-encoded Ed25519 public key |
+| `account_id` | `TEXT` | MemWalAccount object ID |
+| `owner` | `TEXT` | Owner's Sui address |
+| `cached_at` | `TIMESTAMPTZ` | When this mapping was cached |
+
+The cache is populated lazily during auth. If a cached entry becomes stale (key was removed onchain), the relayer re-resolves from the chain and updates the cache.
+
+### `accounts`
+
+Populated by the indexer — maps owner addresses to their MemWalAccount object IDs.
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `account_id` | `TEXT` (PK) | MemWalAccount object ID |
+| `owner` | `TEXT` (unique) | Owner's Sui address |
+| `created_at` | `TIMESTAMPTZ` | When this row was indexed |
+
+### `indexer_state`
+
+Tracks the indexer's cursor position so it can resume from where it left off after restarts.
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `key` | `TEXT` (PK) | State key (e.g., `"event_cursor"`) |
+| `value` | `TEXT` | JSON-serialized cursor (`txDigest` + `eventSeq`) |
+
+## How It Helps
+
+- **Constant-time account lookup** — the relayer checks `delegate_key_cache` and `accounts` instead of scanning the onchain registry
+- **Resumable event polling** — the indexer stores its cursor in `indexer_state`, so it picks up where it left off after restarts without re-processing old events
+- **Reactive cleanup** — when Walrus returns 404 for an expired blob during recall, the relayer deletes the corresponding `vector_entries` rows automatically
+
+## Similarity Search
+
+Recall queries use pgvector's cosine distance operator (`<=>`) against the HNSW index:
+
+```sql
+SELECT blob_id, (embedding <=> $1)::float8 AS distance
+FROM vector_entries
+WHERE owner = $2 AND namespace = $3
+ORDER BY embedding <=> $1
+LIMIT $4
+```
+
+The HNSW index provides approximate nearest neighbor search, which is fast enough for interactive recall even with large numbers of stored memories.
diff --git a/docs/indexer/onchain-events.md b/docs/indexer/onchain-events.md
index 80c338ab..6a7b6fa2 100644
--- a/docs/indexer/onchain-events.md
+++ b/docs/indexer/onchain-events.md
@@ -2,12 +2,20 @@
 title: "Onchain Events"
 ---
 
-The current indexer listens to Sui events for the MemWal package and uses them to update local
-backend state.
+The indexer listens to Sui events emitted by the MemWal contract and uses them to update local backend state.
 
-## Current Event Coverage
+## Events
 
-- `AccountCreated`
+The MemWal contract emits the following events:
 
-The current service comment also points to delegate-key events as part of the broader V2 design,
-even though the main loop shown in the repo currently targets account creation flow first.
+| Event | Emitted when | Fields |
+|-------|-------------|--------|
+| `AccountCreated` | A new account is created | `account_id`, `owner` |
+| `DelegateKeyAdded` | A delegate key is added | `account_id`, `public_key`, `sui_address`, `label` |
+| `DelegateKeyRemoved` | A delegate key is removed | `account_id`, `public_key` |
+| `AccountDeactivated` | An account is frozen | `account_id`, `owner` |
+| `AccountReactivated` | A frozen account is unfrozen | `account_id`, `owner` |
+
+## Current Coverage
+
+The indexer currently targets the `AccountCreated` event flow as its primary sync path. Delegate key events and account activation events are part of the broader design and may be indexed in future iterations.
diff --git a/docs/indexer/purpose.md b/docs/indexer/purpose.md
index 1154bf78..5c00c67f 100644
--- a/docs/indexer/purpose.md
+++ b/docs/indexer/purpose.md
@@ -2,7 +2,52 @@
 title: "Purpose"
 ---
 
-The indexer exists to keep backend account lookup fast.
+The indexer keeps the backend in sync with onchain state so the relayer can resolve accounts quickly.
 
-Instead of forcing the relayer to scan the chain for every request, the indexer listens to
-MemWal events and syncs the relevant account data into PostgreSQL.
+## Why It Exists
+
+Without the indexer, every authenticated request would require the relayer to scan the onchain `AccountRegistry` to find which `MemWalAccount` holds a given delegate key. This involves fetching the registry object, iterating through its dynamic fields, and checking each account — an expensive chain of RPC calls.
+
+The indexer eliminates this by listening to Sui events and syncing account data into PostgreSQL. The relayer can then resolve delegate key ownership with a single database lookup.
+
+## How It Works
+
+The indexer is a standalone Rust service (`services/indexer`) that:
+
+1. Connects to the same PostgreSQL database as the relayer
+2. Polls Sui blockchain events using `suix_queryEvents`
+3. Filters for `AccountCreated` events from the MemWal package
+4. Inserts `account_id → owner` mappings into the `accounts` table
+5. Stores its event cursor in `indexer_state` so it can resume after restarts
+
+## Auth Resolution Flow
+
+When the relayer receives a request, it resolves the delegate key's account using this priority:
+
+1. **PostgreSQL cache** (`delegate_key_cache`) — fastest, populated lazily by the relayer itself
+2. **Indexed accounts** (`accounts`) — populated by the indexer, enables account discovery without chain scans
+3. **Onchain registry scan** — fallback, scans `AccountRegistry` dynamic fields via RPC
+4. **Header hint** (`x-account-id`) — client-provided hint, useful during first-time setup
+5. **Config fallback** (`MEMWAL_ACCOUNT_ID`) — server-level default
+
+After successful resolution through any strategy, the mapping is cached in `delegate_key_cache` for future requests.
+
+## Configuration
+
+The indexer reads these environment variables:
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `DATABASE_URL` | Yes | — | PostgreSQL connection string |
+| `MEMWAL_PACKAGE_ID` | Yes | — | MemWal contract package ID to filter events |
+| `SUI_RPC_URL` | No | Mainnet fullnode | Sui RPC endpoint |
+| `POLL_INTERVAL_SECS` | No | `5` | Seconds between event poll cycles |
+
+## Running
+
+```bash
+cd services/indexer
+cargo run
+```
+
+The indexer is recommended for production but optional for development — the relayer can fall back to onchain resolution without it.
diff --git a/docs/logo-dark.svg b/docs/logo-dark.svg
new file mode 100644
index 00000000..f9b0bb40
--- /dev/null
+++ b/docs/logo-dark.svg
@@ -0,0 +1,13 @@
+<svg width="497" height="78" viewBox="0 0 497 78" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M147.57 9.01L166.95 66.83L186.22 9.01H202.54V76.52H193.46V14.62L172.45 76.52H161.33L140.32 14.62V76.52H131.14V9.01H147.57Z" fill="white" style="fill:white;fill-opacity:1;"/>
+<path d="M210.13 40.31C211.39 37.05 213.14 34.21 215.38 31.8C217.62 29.39 220.29 27.52 223.38 26.19C226.47 24.86 229.86 24.2 233.53 24.2C237.2 24.2 240.58 24.86 243.68 26.19C246.77 27.52 249.43 29.39 251.64 31.8C253.85 34.21 255.58 37.05 256.84 40.31C258.1 43.57 258.73 47.14 258.73 51.02V54.39H217.33C217.6 56.77 218.18 58.94 219.06 60.92C219.94 62.89 221.12 64.56 222.58 65.92C224.04 67.28 225.74 68.35 227.68 69.13C229.62 69.91 231.78 70.3 234.16 70.3C238.17 70.3 241.43 69.45 243.95 67.75C246.46 66.05 248.16 63.77 249.05 60.92H258.33C257.72 63.3 256.73 65.53 255.37 67.6C254.01 69.67 252.31 71.46 250.27 72.95C248.23 74.45 245.87 75.64 243.18 76.52C240.49 77.4 237.49 77.85 234.15 77.85C230.07 77.85 226.43 77.19 223.24 75.86C220.04 74.53 217.32 72.66 215.08 70.25C212.84 67.84 211.14 65 209.98 61.73C208.82 58.47 208.25 54.9 208.25 51.02C208.25 47.14 208.88 43.57 210.14 40.31H210.13ZM249.65 47.45C249.51 45.34 249.02 43.3 248.17 41.33C247.32 39.36 246.2 37.64 244.8 36.18C243.41 34.72 241.76 33.55 239.85 32.66C237.95 31.78 235.84 31.33 233.53 31.33C231.22 31.33 229.09 31.77 227.16 32.66C225.22 33.54 223.57 34.72 222.21 36.18C220.85 37.64 219.76 39.34 218.95 41.28C218.13 43.22 217.62 45.28 217.42 47.45H249.65Z" fill="white" style="fill:white;fill-opacity:1;"/>
+<path d="M263.72 25.53H272.39V36.75H273.21C273.82 34.85 274.64 33.16 275.66 31.7C276.68 30.24 277.87 29 279.23 27.98C280.59 26.96 282.09 26.18 283.72 25.63C285.35 25.09 287.05 24.81 288.82 24.81C292.49 24.81 295.65 25.86 298.3 27.97C300.95 30.08 302.75 33.21 303.7 37.35H304.41C305.02 35.38 305.87 33.63 306.96 32.1C308.05 30.57 309.31 29.26 310.73 28.17C312.16 27.08 313.72 26.25 315.42 25.67C317.12 25.09 318.89 24.8 320.72 24.8C323.1 24.8 325.27 25.21 327.25 26.02C329.22 26.84 330.92 28.08 332.35 29.74C333.78 31.41 334.86 33.48 335.61 35.96C336.36 38.44 336.73 41.38 336.73 44.78V76.49H327.86V45.9C327.86 41.28 326.92 37.91 325.06 35.8C323.19 33.69 320.59 32.64 317.26 32.64C315.36 32.64 313.6 33.03 312.01 33.81C310.41 34.59 309.07 35.77 307.98 37.33C306.89 38.89 306.06 40.87 305.48 43.25C304.9 45.63 304.61 48.38 304.61 51.51V76.49H295.94V45.9C295.94 41.28 295 37.91 293.14 35.8C291.27 33.69 288.67 32.64 285.34 32.64C284.12 32.64 282.77 32.88 281.31 33.35C279.85 33.83 278.47 34.73 277.18 36.05C275.89 37.38 274.8 39.28 273.92 41.76C273.04 44.24 272.59 47.49 272.59 51.5V76.48H263.72V25.53Z" fill="white" style="fill:white;fill-opacity:1;"/>
+<path d="M339.9 9.01H349.08L363.76 70.3L378.45 9.01H392.32L407.01 70.3L421.69 9.01H430.77L414.76 76.52H399.16L385.39 18.8L371.52 76.52H355.92L339.91 9.01H339.9Z" fill="white" style="fill:white;fill-opacity:1;"/>
+<path d="M430.51 40.47C431.7 37.24 433.3 34.47 435.3 32.16C437.3 29.85 439.7 28.05 442.49 26.76C445.28 25.47 448.27 24.82 451.46 24.82C455.95 24.82 459.82 26.04 463.09 28.49C466.35 30.94 468.8 34.24 470.43 38.38H471.25V25.53H479.82V76.52H471.25V63.67H470.43C468.8 67.82 466.35 71.12 463.09 73.56C459.83 76 455.95 77.23 451.46 77.23C448.26 77.23 445.27 76.58 442.49 75.29C439.7 74 437.3 72.2 435.3 69.88C433.29 67.57 431.7 64.8 430.51 61.57C429.32 58.34 428.73 54.82 428.73 51.02C428.73 47.22 429.32 43.69 430.51 40.47ZM438.72 58.36C439.47 60.6 440.54 62.58 441.93 64.28C443.32 65.98 445.04 67.32 447.08 68.31C449.12 69.3 451.4 69.79 453.91 69.79C456.42 69.79 458.82 69.3 460.9 68.31C462.97 67.33 464.72 65.96 466.15 64.23C467.58 62.5 468.66 60.49 469.41 58.21C470.16 55.93 470.53 53.54 470.53 51.02C470.53 48.5 470.16 46.11 469.41 43.83C468.66 41.55 467.57 39.55 466.15 37.81C464.72 36.08 462.97 34.72 460.9 33.73C458.82 32.75 456.5 32.25 453.91 32.25C451.32 32.25 449.12 32.74 447.08 33.73C445.04 34.72 443.32 36.06 441.93 37.76C440.54 39.46 439.47 41.43 438.72 43.68C437.97 45.92 437.6 48.37 437.6 51.02C437.6 53.67 437.97 56.12 438.72 58.36Z" fill="white" style="fill:white;fill-opacity:1;"/>
+<path d="M487.67 4.83H496.54V76.52H487.67V4.83Z" fill="white" style="fill:white;fill-opacity:1;"/>
+<path d="M12.75 25.51H0V76.53H12.75V25.51Z" fill="white" style="fill:white;fill-opacity:1;"/>
+<path d="M28.69 0H12.75V25.51H28.69V0Z" fill="white" style="fill:white;fill-opacity:1;"/>
+<path d="M47.83 25.51H28.7V76.53H47.83V25.51Z" fill="white" style="fill:white;fill-opacity:1;"/>
+<path d="M70.15 0H47.83V25.51H70.15V0Z" fill="white" style="fill:white;fill-opacity:1;"/>
+<path d="M95.66 25.51H70.15V76.53H95.66V25.51Z" fill="white" style="fill:white;fill-opacity:1;"/>
+</svg>
diff --git a/docs/logo-light.svg b/docs/logo-light.svg
new file mode 100644
index 00000000..02124e7b
--- /dev/null
+++ b/docs/logo-light.svg
@@ -0,0 +1,13 @@
+<svg width="497" height="78" viewBox="0 0 497 78" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M147.57 9.01L166.95 66.83L186.22 9.01H202.54V76.52H193.46V14.62L172.45 76.52H161.33L140.32 14.62V76.52H131.14V9.01H147.57Z" fill="black" style="fill:black;fill-opacity:1;"/>
+<path d="M210.13 40.31C211.39 37.05 213.14 34.21 215.38 31.8C217.62 29.39 220.29 27.52 223.38 26.19C226.47 24.86 229.86 24.2 233.53 24.2C237.2 24.2 240.58 24.86 243.68 26.19C246.77 27.52 249.43 29.39 251.64 31.8C253.85 34.21 255.58 37.05 256.84 40.31C258.1 43.57 258.73 47.14 258.73 51.02V54.39H217.33C217.6 56.77 218.18 58.94 219.06 60.92C219.94 62.89 221.12 64.56 222.58 65.92C224.04 67.28 225.74 68.35 227.68 69.13C229.62 69.91 231.78 70.3 234.16 70.3C238.17 70.3 241.43 69.45 243.95 67.75C246.46 66.05 248.16 63.77 249.05 60.92H258.33C257.72 63.3 256.73 65.53 255.37 67.6C254.01 69.67 252.31 71.46 250.27 72.95C248.23 74.45 245.87 75.64 243.18 76.52C240.49 77.4 237.49 77.85 234.15 77.85C230.07 77.85 226.43 77.19 223.24 75.86C220.04 74.53 217.32 72.66 215.08 70.25C212.84 67.84 211.14 65 209.98 61.73C208.82 58.47 208.25 54.9 208.25 51.02C208.25 47.14 208.88 43.57 210.14 40.31H210.13ZM249.65 47.45C249.51 45.34 249.02 43.3 248.17 41.33C247.32 39.36 246.2 37.64 244.8 36.18C243.41 34.72 241.76 33.55 239.85 32.66C237.95 31.78 235.84 31.33 233.53 31.33C231.22 31.33 229.09 31.77 227.16 32.66C225.22 33.54 223.57 34.72 222.21 36.18C220.85 37.64 219.76 39.34 218.95 41.28C218.13 43.22 217.62 45.28 217.42 47.45H249.65Z" fill="black" style="fill:black;fill-opacity:1;"/>
+<path d="M263.72 25.53H272.39V36.75H273.21C273.82 34.85 274.64 33.16 275.66 31.7C276.68 30.24 277.87 29 279.23 27.98C280.59 26.96 282.09 26.18 283.72 25.63C285.35 25.09 287.05 24.81 288.82 24.81C292.49 24.81 295.65 25.86 298.3 27.97C300.95 30.08 302.75 33.21 303.7 37.35H304.41C305.02 35.38 305.87 33.63 306.96 32.1C308.05 30.57 309.31 29.26 310.73 28.17C312.16 27.08 313.72 26.25 315.42 25.67C317.12 25.09 318.89 24.8 320.72 24.8C323.1 24.8 325.27 25.21 327.25 26.02C329.22 26.84 330.92 28.08 332.35 29.74C333.78 31.41 334.86 33.48 335.61 35.96C336.36 38.44 336.73 41.38 336.73 44.78V76.49H327.86V45.9C327.86 41.28 326.92 37.91 325.06 35.8C323.19 33.69 320.59 32.64 317.26 32.64C315.36 32.64 313.6 33.03 312.01 33.81C310.41 34.59 309.07 35.77 307.98 37.33C306.89 38.89 306.06 40.87 305.48 43.25C304.9 45.63 304.61 48.38 304.61 51.51V76.49H295.94V45.9C295.94 41.28 295 37.91 293.14 35.8C291.27 33.69 288.67 32.64 285.34 32.64C284.12 32.64 282.77 32.88 281.31 33.35C279.85 33.83 278.47 34.73 277.18 36.05C275.89 37.38 274.8 39.28 273.92 41.76C273.04 44.24 272.59 47.49 272.59 51.5V76.48H263.72V25.53Z" fill="black" style="fill:black;fill-opacity:1;"/>
+<path d="M339.9 9.01H349.08L363.76 70.3L378.45 9.01H392.32L407.01 70.3L421.69 9.01H430.77L414.76 76.52H399.16L385.39 18.8L371.52 76.52H355.92L339.91 9.01H339.9Z" fill="black" style="fill:black;fill-opacity:1;"/>
+<path d="M430.51 40.47C431.7 37.24 433.3 34.47 435.3 32.16C437.3 29.85 439.7 28.05 442.49 26.76C445.28 25.47 448.27 24.82 451.46 24.82C455.95 24.82 459.82 26.04 463.09 28.49C466.35 30.94 468.8 34.24 470.43 38.38H471.25V25.53H479.82V76.52H471.25V63.67H470.43C468.8 67.82 466.35 71.12 463.09 73.56C459.83 76 455.95 77.23 451.46 77.23C448.26 77.23 445.27 76.58 442.49 75.29C439.7 74 437.3 72.2 435.3 69.88C433.29 67.57 431.7 64.8 430.51 61.57C429.32 58.34 428.73 54.82 428.73 51.02C428.73 47.22 429.32 43.69 430.51 40.47ZM438.72 58.36C439.47 60.6 440.54 62.58 441.93 64.28C443.32 65.98 445.04 67.32 447.08 68.31C449.12 69.3 451.4 69.79 453.91 69.79C456.42 69.79 458.82 69.3 460.9 68.31C462.97 67.33 464.72 65.96 466.15 64.23C467.58 62.5 468.66 60.49 469.41 58.21C470.16 55.93 470.53 53.54 470.53 51.02C470.53 48.5 470.16 46.11 469.41 43.83C468.66 41.55 467.57 39.55 466.15 37.81C464.72 36.08 462.97 34.72 460.9 33.73C458.82 32.75 456.5 32.25 453.91 32.25C451.32 32.25 449.12 32.74 447.08 33.73C445.04 34.72 443.32 36.06 441.93 37.76C440.54 39.46 439.47 41.43 438.72 43.68C437.97 45.92 437.6 48.37 437.6 51.02C437.6 53.67 437.97 56.12 438.72 58.36Z" fill="black" style="fill:black;fill-opacity:1;"/>
+<path d="M487.67 4.83H496.54V76.52H487.67V4.83Z" fill="black" style="fill:black;fill-opacity:1;"/>
+<path d="M12.75 25.51H0V76.53H12.75V25.51Z" fill="black" style="fill:black;fill-opacity:1;"/>
+<path d="M28.69 0H12.75V25.51H28.69V0Z" fill="black" style="fill:black;fill-opacity:1;"/>
+<path d="M47.83 25.51H28.7V76.53H47.83V25.51Z" fill="black" style="fill:black;fill-opacity:1;"/>
+<path d="M70.15 0H47.83V25.51H70.15V0Z" fill="black" style="fill:black;fill-opacity:1;"/>
+<path d="M95.66 25.51H70.15V76.53H95.66V25.51Z" fill="black" style="fill:black;fill-opacity:1;"/>
+</svg>
diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
index 71187c65..0dbf9188 100644
--- a/docs/reference/configuration.md
+++ b/docs/reference/configuration.md
@@ -14,6 +14,7 @@ Used by:
 | Field | Required | Notes |
 | --- | --- | --- |
 | `key` | yes | Delegate private key in hex |
+| `accountId` | yes | MemWalAccount object ID on Sui |
 | `serverUrl` | no | Relayer URL. Default: `http://localhost:8000` |
 | `namespace` | no | Default memory boundary. Default: `"default"` |
 
@@ -21,7 +22,7 @@ Used by:
 
 Used by:
 
-- `new MemWalManual(config)`
+- `MemWalManual.create(config)`
 
 Core fields:
 
diff --git a/docs/reference/environment-variables.md b/docs/reference/environment-variables.md
index 23582b5c..88768fa8 100644
--- a/docs/reference/environment-variables.md
+++ b/docs/reference/environment-variables.md
@@ -47,8 +47,9 @@ These are not all enforced at boot, but most real deployments need them.
 - The relayer uses them for `remember`, `recall`, `analyze`, `ask`, and restore re-indexing.
 - `SEAL_KEY_SERVERS` is required for the sidecar SEAL encrypt and decrypt path.
 - `SUI_NETWORK` now drives the default RPC URL, Walrus endpoints, Walrus package ID, and upload relay selection.
+- The sidecar `POST /walrus/upload` route defaults Walrus storage epochs by network: `50` on `testnet`, `2` on `mainnet`, unless the request explicitly passes `epochs`.
 - `MEMWAL_PACKAGE_ID` and `MEMWAL_REGISTRY_ID` are server env vars. Do not replace them with `VITE_*` app env vars.
-- For testnet, use `MEMWAL_PACKAGE_ID=0x12b28adbe55c25341f08b8ad9ac69462aab917048c7cd5b736d951200090ee3f` and `MEMWAL_REGISTRY_ID=0xfb8a1d298e2a73bdab353da3fcb3b16f68ab7d1f392f3a5c4944c747c026fc05`.
+- For testnet, use `MEMWAL_PACKAGE_ID=0xcf6ad755a1cdff7217865c796778fabe5aa399cb0cf2eba986f4b582047229c6` and `MEMWAL_REGISTRY_ID=0xe80f2feec1c139616a86c9f71210152e2a7ca552b20841f2e192f99f75864437`.
 - Without `OPENAI_API_KEY`, the server can fall back to mock embeddings. That is useful for local testing, not for normal production behavior.
 - The Rust server starts the TypeScript sidecar automatically.
 - `/health` is the fastest way to confirm the relayer is up.
diff --git a/docs/reference/relayer-api.md b/docs/reference/relayer-api.md
deleted file mode 100644
index c2d584ac..00000000
--- a/docs/reference/relayer-api.md
+++ /dev/null
@@ -1,91 +0,0 @@
----
-title: "Relayer API Reference"
----
-
-The current Rust server exposes these routes from `services/server/src/main.rs`.
-
-See also:
-
-- [Environment Variables](/reference/environment-variables)
-- [Configuration](/reference/configuration)
-
-## Public
-
-### `GET /health`
-
-- Use for a simple service check
-
-Example response:
-
-```json
-{
-  "status": "ok",
-  "version": "..."
-}
-```
-
-## Protected
-
-### `POST /api/remember`
-
-- Store text for the authenticated owner and namespace
-
-```json
-{
-  "text": "User prefers dark mode",
-  "namespace": "demo"
-}
-```
-
-### `POST /api/recall`
-
-- Search and return plaintext results
-
-```json
-{
-  "query": "What do we know about this user?",
-  "limit": 10,
-  "namespace": "demo"
-}
-```
-
-### `POST /api/remember/manual`
-
-- Register encrypted payload plus precomputed vector
-- Current backend expects `encrypted_data`, not a pre-existing `blob_id`
-
-### `POST /api/recall/manual`
-
-- Search with a precomputed vector
-- Returns `{ blob_id, distance }` hits
-
-### `POST /api/analyze`
-
-- Extract facts from text and store them as memories
-
-### `POST /api/ask`
-
-- Recall memories, inject them into an LLM prompt, and return an answer
-
-### `POST /api/restore`
-
-- Rebuild missing vector entries for one owner and namespace
-- Uses chain metadata plus blob discovery
-
-```json
-{
-  "namespace": "demo",
-  "limit": 50
-}
-```
-
-## Signed Headers
-
-The SDK signs requests and sends headers such as:
-
-- `x-public-key`
-- `x-signature`
-- `x-timestamp`
-
-The default SDK also sends `x-delegate-key` for backend flows that may require delegate-key-backed
-decrypt or restore behavior.
diff --git a/docs/reference/sdk-api.md b/docs/reference/sdk-api.md
deleted file mode 100644
index c7803094..00000000
--- a/docs/reference/sdk-api.md
+++ /dev/null
@@ -1,101 +0,0 @@
----
-title: "SDK API Reference"
----
-
-See also:
-
-- [Configuration](/reference/configuration)
-- [Relayer API](/reference/relayer-api)
-
-## `MemWal.create(config)`
-
-```ts
-MemWal.create(config: MemWalConfig): MemWal
-```
-
-Config:
-
-| Property | Type | Notes |
-| --- | --- | --- |
-| `key` | `string` | Ed25519 private key in hex |
-| `serverUrl?` | `string` | Relayer URL |
-| `namespace?` | `string` | Default namespace, fallback is `"default"` |
-
-For the full config surface, see [Configuration](/reference/configuration).
-
-## `MemWal`
-
-### `remember(text, namespace?)`
-
-- Store one memory through the relayer
-- Returns: `id`, `blob_id`, `owner`
-
-### `recall(query, limit?, namespace?)`
-
-- Search one owner-and-namespace boundary
-- Returns plaintext matches
-
-### `analyze(text, namespace?)`
-
-- Extract memorable facts from text
-- Stores each fact as memory
-
-### `restore(namespace, limit?)`
-
-- Rebuild missing indexed entries for one namespace
-- Use when local vector state is incomplete
-
-### `health()`
-
-- Check relayer health
-
-### `getPublicKeyHex()`
-
-- Return the public key for the current delegate key
-
-### Lower-Level `MemWal` Methods
-
-- `rememberManual({ blobId, vector, namespace? })`
-- `recallManual({ vector, limit?, namespace? })`
-- `embed(text)`
-
-These exist on the current SDK surface, but the main beta path is still `remember`, `recall`,
-`analyze`, and `restore`.
-
-## `MemWalManual`
-
-Import:
-
-```ts
-import { MemWalManual } from "@cmdoss/memwal/manual";
-```
-
-Main methods:
-
-- `rememberManual(text, namespace?)`
-- `recallManual(query, limit?, namespace?)`
-- `restore(namespace, limit?)`
-- `isWalletMode`
-
-Use this client when the app must handle embedding calls and local SEAL operations.
-
-Important config notes:
-
-- `suiNetwork` now defaults to `mainnet`
-- `sealKeyServers?` lets the client override the built-in SEAL key server list
-
-## `withMemWal`
-
-Import:
-
-```ts
-import { withMemWal } from "@cmdoss/memwal/ai";
-```
-
-Use it to add:
-
-- recall before generation
-- memory context injection
-- optional auto-save after generation
-
-See [Configuration](/reference/configuration) for middleware options.
diff --git a/docs/relayer/api-reference.md b/docs/relayer/api-reference.md
new file mode 100644
index 00000000..0476a90f
--- /dev/null
+++ b/docs/relayer/api-reference.md
@@ -0,0 +1,263 @@
+---
+title: "API Reference"
+---
+
+The Rust relayer exposes these routes. Routes are defined in `services/server/src/main.rs`.
+
+See also:
+
+- [Environment Variables](/reference/environment-variables)
+- [Configuration](/reference/configuration)
+
+## Authentication
+
+All `/api/*` routes require signed headers. The SDK handles this automatically.
+
+### Required Headers
+
+| Header | Description |
+|--------|-------------|
+| `x-public-key` | Hex-encoded Ed25519 public key (32 bytes) |
+| `x-signature` | Hex-encoded Ed25519 signature (64 bytes) |
+| `x-timestamp` | Unix timestamp in seconds (5-minute validity window) |
+
+### Optional Headers
+
+| Header | Description |
+|--------|-------------|
+| `x-account-id` | MemWalAccount object ID hint — speeds up account resolution when not cached |
+| `x-delegate-key` | Delegate private key (hex) — used by the default SDK for SEAL decrypt flows |
+
+### Signature Format
+
+The signed message is: `{timestamp}.{method}.{path}.{body_sha256}`
+
+The relayer verifies the Ed25519 signature, then resolves the owner by looking up the public key in onchain `MemWalAccount.delegate_keys`.
+
+## Public Routes
+
+### `GET /health`
+
+Service health check. No authentication required.
+
+**Response:**
+
+```json
+{
+  "status": "ok",
+  "version": "0.1.0"
+}
+```
+
+### `POST /sponsor`
+
+Proxy to the SEAL/Walrus sidecar's `/sponsor` endpoint for sponsored transactions. No authentication required.
+
+### `POST /sponsor/execute`
+
+Proxy to the sidecar's `/sponsor/execute` endpoint. No authentication required.
+
+## Protected Routes
+
+### `POST /api/remember`
+
+Store text as an encrypted memory. The relayer handles embedding, SEAL encryption, Walrus upload, and vector indexing.
+
+**Request:**
+
+```json
+{
+  "text": "User prefers dark mode",
+  "namespace": "demo"
+}
+```
+
+`namespace` defaults to `"default"` if omitted.
+
+**Response:**
+
+```json
+{
+  "id": "uuid",
+  "blob_id": "walrus-blob-id",
+  "owner": "0x...",
+  "namespace": "demo"
+}
+```
+
+### `POST /api/recall`
+
+Search for memories matching a natural language query. Returns decrypted plaintext results.
+
+**Request:**
+
+```json
+{
+  "query": "What do we know about this user?",
+  "limit": 10,
+  "namespace": "demo"
+}
+```
+
+`limit` defaults to `10`. `namespace` defaults to `"default"`.
+
+**Response:**
+
+```json
+{
+  "results": [
+    {
+      "blob_id": "walrus-blob-id",
+      "text": "User prefers dark mode",
+      "distance": 0.15
+    }
+  ],
+  "total": 1
+}
+```
+
+### `POST /api/remember/manual`
+
+Register a client-encrypted payload. The client sends SEAL-encrypted data (base64) and a precomputed embedding vector. The relayer uploads the encrypted bytes to Walrus and stores the vector mapping.
+
+**Request:**
+
+```json
+{
+  "encrypted_data": "base64-encoded-seal-encrypted-bytes",
+  "vector": [0.01, -0.02, ...],
+  "namespace": "demo"
+}
+```
+
+**Response:**
+
+```json
+{
+  "id": "uuid",
+  "blob_id": "walrus-blob-id",
+  "owner": "0x...",
+  "namespace": "demo"
+}
+```
+
+### `POST /api/recall/manual`
+
+Search with a precomputed query vector. Returns blob IDs and distances only — the client handles downloading and decrypting.
+
+**Request:**
+
+```json
+{
+  "vector": [0.01, -0.02, ...],
+  "limit": 10,
+  "namespace": "demo"
+}
+```
+
+**Response:**
+
+```json
+{
+  "results": [
+    {
+      "blob_id": "walrus-blob-id",
+      "distance": 0.15
+    }
+  ],
+  "total": 1
+}
+```
+
+### `POST /api/analyze`
+
+Extract facts from text using an LLM, then store each fact as a separate memory (embed, encrypt, upload, index).
+
+**Request:**
+
+```json
+{
+  "text": "I live in Hanoi and prefer dark mode.",
+  "namespace": "demo"
+}
+```
+
+**Response:**
+
+```json
+{
+  "facts": [
+    {
+      "text": "User lives in Hanoi",
+      "id": "uuid",
+      "blob_id": "walrus-blob-id"
+    },
+    {
+      "text": "User prefers dark mode",
+      "id": "uuid",
+      "blob_id": "walrus-blob-id"
+    }
+  ],
+  "total": 2,
+  "owner": "0x..."
+}
+```
+
+### `POST /api/ask`
+
+Recall memories, inject them into an LLM prompt, and return an AI-generated answer with the context used.
+
+**Request:**
+
+```json
+{
+  "question": "What do you know about my preferences?",
+  "limit": 5,
+  "namespace": "demo"
+}
+```
+
+`limit` defaults to `5`. `namespace` defaults to `"default"`.
+
+**Response:**
+
+```json
+{
+  "answer": "Based on your memories, you prefer dark mode and live in Hanoi.",
+  "memories_used": 2,
+  "memories": [
+    {
+      "blob_id": "walrus-blob-id",
+      "text": "User prefers dark mode",
+      "distance": 0.12
+    }
+  ]
+}
+```
+
+### `POST /api/restore`
+
+Rebuild missing vector entries for one namespace. Queries onchain blobs by owner and namespace, downloads from Walrus, decrypts, re-embeds, and re-indexes only the entries missing from the local database.
+
+**Request:**
+
+```json
+{
+  "namespace": "demo",
+  "limit": 50
+}
+```
+
+`limit` defaults to `50`.
+
+**Response:**
+
+```json
+{
+  "restored": 3,
+  "skipped": 7,
+  "total": 10,
+  "namespace": "demo",
+  "owner": "0x..."
+}
+```
diff --git a/docs/relayer/installation-and-setup.md b/docs/relayer/installation-and-setup.md
deleted file mode 100644
index 640213e7..00000000
--- a/docs/relayer/installation-and-setup.md
+++ /dev/null
@@ -1,106 +0,0 @@
----
-title: "Installation and Setup"
----
-
-The relayer is configured through environment variables and starts its sidecar automatically.
-
-## Main Environment Variables
-
-- `PORT`
-- `DATABASE_URL`
-- `OPENAI_API_KEY`
-- `OPENAI_API_BASE`
-- `SUI_NETWORK`
-- `SUI_RPC_URL`
-- `WALRUS_PUBLISHER_URL`
-- `WALRUS_AGGREGATOR_URL`
-- `SERVER_SUI_PRIVATE_KEY`
-- `SERVER_SUI_PRIVATE_KEYS`
-- `SEAL_KEY_SERVERS`
-- `MEMWAL_PACKAGE_ID`
-- `MEMWAL_REGISTRY_ID`
-- `WALRUS_PACKAGE_ID`
-- `WALRUS_UPLOAD_RELAY_URL`
-- `ENOKI_API_KEY`
-- `ENOKI_NETWORK`
-- `SIDECAR_URL`
-
-## Defaults That Matter
-
-- `PORT` defaults to `8000`
-- `SIDECAR_URL` defaults to `http://localhost:9000`
-- `SUI_RPC_URL` falls back to a network default based on `SUI_NETWORK`
-- `SUI_NETWORK` now defaults to `mainnet`
-- Walrus endpoints fall back to mainnet defaults if not overridden
-- `WALRUS_PACKAGE_ID` and `WALRUS_UPLOAD_RELAY_URL` also follow `SUI_NETWORK` if not set
-
-## Setup Checklist
-
-1. create `services/server/.env`
-2. set `DATABASE_URL`
-3. set `OPENAI_API_KEY` and, if needed, `OPENAI_API_BASE`
-4. set contract and network values
-5. set `SEAL_KEY_SERVERS`
-6. set Walrus endpoints
-7. set one server key or a key pool
-8. install `services/server/scripts` dependencies
-9. run `cargo run` in `services/server`
-
-## Contract IDs
-
-For a testnet relayer setup, use:
-
-```env
-SUI_NETWORK=testnet
-MEMWAL_PACKAGE_ID=0x12b28adbe55c25341f08b8ad9ac69462aab917048c7cd5b736d951200090ee3f
-MEMWAL_REGISTRY_ID=0xfb8a1d298e2a73bdab353da3fcb3b16f68ab7d1f392f3a5c4944c747c026fc05
-```
-
-Notes:
-
-- the relayer uses `MEMWAL_PACKAGE_ID` and `MEMWAL_REGISTRY_ID`
-- `MEMWAL_REGISTRY_ID` is still required by the current server config
-- `VITE_MEMWAL_PACKAGE_ID` and `VITE_MEMWAL_REGISTRY_ID` are frontend env vars for the app or playground
-
-## Embedding Provider
-
-- `OPENAI_API_KEY` is the server-side key used for embedding and fact extraction
-- `OPENAI_API_BASE` lets you point the relayer to an OpenAI-compatible provider such as OpenRouter
-- when these are set, the relayer calls the provider directly during `remember`, `recall`, `analyze`,
-  `ask`, and restore re-indexing
-- without `OPENAI_API_KEY`, the relayer falls back to mock embeddings for local testing
-
-## SEAL Key Servers
-
-- `SEAL_KEY_SERVERS` is a comma-separated list of SEAL key server object IDs
-- the sidecar uses this list for backend SEAL encrypt and decrypt operations
-- the server no longer relies on hardcoded testnet key server IDs
-- make sure the list matches the selected `SUI_NETWORK`
-- for testnet setup, use https://seal-docs.wal.app/Pricing to find the current SEAL key server object IDs
-
-## Notes On Keys
-
-- `SERVER_SUI_PRIVATE_KEY` is the main server key
-- `SERVER_SUI_PRIVATE_KEYS` is a comma-separated key pool for parallel Walrus uploads
-- if both are set, the key pool takes priority for uploads
-
-## Database Behavior
-
-- the server connects to PostgreSQL on boot
-- migrations in `services/server/migrations` run automatically
-- `pgvector` must already be available in the database
-
-## Sidecar Behavior
-
-- the Rust server starts the TypeScript sidecar on boot
-- the sidecar handles backend SEAL and Walrus operations
-- if sidecar startup fails, the relayer will fail fast on boot
-
-## Operational Notes
-
-- `/health` is the basic service check
-- API routes live under `/api/*`
-- account lookup improves when the indexer is running
-- `OPENAI_API_KEY` + `OPENAI_API_BASE` control which embedding API the relayer calls
-- `SEAL_KEY_SERVERS` controls which SEAL key servers the sidecar trusts
-- without `OPENAI_API_KEY`, the server can fall back to mock embeddings, but that is not the normal production path
diff --git a/docs/relayer/overview.md b/docs/relayer/overview.md
index 631dc8b1..82cffa90 100644
--- a/docs/relayer/overview.md
+++ b/docs/relayer/overview.md
@@ -1,63 +1,76 @@
 ---
-title: "Relayer Overview"
+title: "Overview"
 ---
 
-The relayer turns signed SDK calls into memory operations.
+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
 
-- verifies delegate-key access
-- resolves owner and account context
-- stores and searches vectors by `owner + namespace`
-- coordinates SEAL and Walrus operations through the sidecar
-- runs `remember`, `recall`, `analyze`, `ask`, and `restore`
-- uses env-driven network config for RPC, Walrus, and SEAL sidecar behavior
+- **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
 
-## Trust Boundary
+## Architecture
 
-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.
+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.
+
+```mermaid
+flowchart LR
+    Client["SDK / App"]
+
+    %% ===== HOST =====
+    subgraph Host["Relayer Host"]
+        direction LR
 
-The relayer currently handles:
+        Axum["Rust Relayer (Axum)<br>Auth + routes"]
+        Sidecar["TypeScript Sidecar<br>SEAL + Walrus"]
 
-- embedding generation
-- encryption and decryption orchestration
-- Walrus upload and download orchestration
-- fact extraction for `analyze`
-- restore and re-index flows
+        %% container backend
+        subgraph Stack
+            direction TB
+            DB["PostgreSQL + pgvector"]
+            Sui["Sui RPC"]
+            AI["Embedding / LLM API"]
+        end
+    end
 
-If you need to minimize this trust, you can [self-host](/relayer/self-hosting) the relayer or use the [manual client flow](/sdk/usage) to handle encryption and embedding entirely on the client side. See [Trust & Security Model](/fundamentals/architecture/data-flow-security-model) for the full breakdown.
+    %% external
+    Seal["SEAL key servers"]
+    Walrus["Walrus"]
 
-## Network and Sidecar Config
+    %% flows
+    Client --> Axum
 
-- the relayer now defaults to `mainnet` network settings
-- `SUI_NETWORK` drives the default RPC URL and Walrus service endpoints
-- `SEAL_KEY_SERVERS` tells the sidecar which SEAL key server objects to use
-- self-hosted deployments can override Walrus package and upload relay defaults through env vars
+    %% chỉ nối vào container (qua node đầu)
+    Axum --> DB
 
-## Namespace Behavior
+    %% sidecar
+    Axum --> Sidecar
+    Sidecar --> Seal
+    Sidecar --> Walrus  
+```
 
-- vector entries are stored by `owner + namespace`
-- Walrus uploads carry `memwal_namespace` metadata
-- restore runs one namespace at a time
+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.
 
-Namespace is recorded onchain through Walrus blob metadata during upload. It is not a separate
-MemWal contract object.
+## Key Pool
 
-## Restore Behavior
+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.
 
-Restore is incremental:
+## Single-Instance Design
 
-1. query blobs for one owner and namespace
-2. compare with local DB state
-3. restore only missing entries
+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.
 
-## Routes
+<Note>
+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.
+</Note>
+
+## 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.
 
-- `GET /health`
-- `POST /api/remember`
-- `POST /api/recall`
-- `POST /api/remember/manual`
-- `POST /api/recall/manual`
-- `POST /api/analyze`
-- `POST /api/ask`
-- `POST /api/restore`
+If you need to minimize this trust, you can [self-host](/relayer/self-hosting) the relayer or use the [manual client flow](/sdk/usage/memwal-manual) to handle encryption and embedding entirely on the client side. See [Trust & Security Model](/fundamentals/architecture/data-flow-security-model) for the full breakdown.
diff --git a/docs/relayer/public-relayer.md b/docs/relayer/public-relayer.md
index 79f30486..5efb9de4 100644
--- a/docs/relayer/public-relayer.md
+++ b/docs/relayer/public-relayer.md
@@ -2,42 +2,33 @@
 title: "Public Relayer"
 ---
 
-The public relayer is the fastest way to evaluate MemWal during beta.
+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.
 
-## Use It When
+## Endpoints
 
-- you are testing the SDK
-- you want to validate namespace-aware flows quickly
-- you want to try `remember`, `recall`, `analyze`, and `restore` before self-hosting
+| Network | Relayer URL |
+|---|---|
+| **Production** (mainnet) | `https://relayer.memwal.ai` |
+| **Staging** (testnet) | `https://relayer.staging.memwal.ai` |
 
 ## Minimal Config
 
 ```ts
-import { MemWal } from "@cmdoss/memwal";
+import { MemWal } from "@mysten/memwal";
 
 const memwal = MemWal.create({
-  key: process.env.MEMWAL_PRIVATE_KEY!,
-  serverUrl: process.env.MEMWAL_SERVER_URL!,
+  key: "<your-ed25519-private-key>",
+  accountId: "<your-memwal-account-id>",
+  serverUrl: "https://relayer.memwal.ai",
   namespace: "demo",
 });
 ```
 
-## Good Evaluation Flow
+## What to Know
 
-1. call `health()`
-2. store one memory with `remember()`
-3. retrieve it with `recall()`
-4. try `analyze()` on a longer passage
-5. use `restore()` only when you want to validate recovery behavior
+- **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.
+- **Storage costs** - the server wallet covers Walrus storage fees. Usage limits may apply during beta.
 
-## Assume This
-
-- the public relayer is a managed beta surface
-- the documented routes are the supported surface
-- your integration should set a namespace explicitly
-
-## Self-Host Instead If You Need
-
-- your own infra and credentials
-- tighter operational guarantees
-- your own rollout control
+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 e76b6886..d941f325 100644
--- a/docs/relayer/self-hosting.md
+++ b/docs/relayer/self-hosting.md
@@ -1,143 +1,134 @@
 ---
-title: "Operate Your Own Relayer"
+title: "Self-Hosting"
 ---
 
-Run your own relayer when you need your own backend, secrets, and rollout control.
+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.
 
-## Use It When
+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.
 
-- you want your own deployment environment
-- you want your own database and credentials
-- you want to control relayer upgrades and uptime
-- you want the server to use your own embedding provider credentials
+## When to Self-Host
 
-## What Runs
+The most common reasons are removing the trust assumption on a third-party relayer or running your own MemWal instance entirely:
+
+- **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
 
-A self-hosted MemWal backend usually has:
+## What Runs
 
-- the Rust relayer in `services/server`
-- the TypeScript sidecar in `services/server/scripts`
-- PostgreSQL with pgvector
-- optional but recommended: the indexer in `services/indexer`
+A self-hosted MemWal backend has:
 
-## Local Run Flow
+| Component | Location | Description |
+|-----------|----------|-------------|
+| **Rust relayer** | `services/server` | Axum HTTP server — auth, routing, embedding, vector search |
+| **TypeScript sidecar** | `services/server/scripts` | SEAL encrypt/decrypt, Walrus upload, blob query (uses `@mysten/seal` and `@mysten/walrus`) |
+| **PostgreSQL + pgvector** | External | Vector storage, auth cache, indexer state |
+| **Indexer** (recommended) | `services/indexer` | Polls Sui events, syncs account data into PostgreSQL |
 
-1. create a PostgreSQL database with `pgvector`
-2. copy `services/server/.env.example` to `services/server/.env`
-3. fill in the required env vars
-4. install sidecar deps in `services/server/scripts`
-5. run the Rust server from `services/server`
-6. optionally run the indexer from `services/indexer`
+The Rust relayer starts the TypeScript sidecar as a child process on boot. They communicate over HTTP (`localhost:9000` by default). If the sidecar fails to start within 15 seconds, the relayer exits.
 
 ## Quick Start
 
-If you already have PostgreSQL + pgvector running, the shortest path is:
+If you do not already have PostgreSQL + pgvector running, start it with:
 
 ```bash
-cp services/server/.env.example services/server/.env
-cd services/server/scripts && npm ci
-cd ../ && cargo run
-cd ../indexer && cargo run
+docker compose -f services/server/docker-compose.yml up -d postgres
 ```
 
-Then check:
+Then run the relayer:
 
 ```bash
-curl http://localhost:8000/health
+cp services/server/.env.example services/server/.env
+cd services/server/scripts
+npm ci
+cd ..
+cargo run
 ```
 
-Use this quick start for local evaluation. For production operation, review the full env setup
-and key configuration below.
-
-## Testnet Contract IDs
-
-If you want to run your own relayer on testnet, use these server env vars:
+Then check:
 
-```env
-SUI_NETWORK=testnet
-MEMWAL_PACKAGE_ID=0x12b28adbe55c25341f08b8ad9ac69462aab917048c7cd5b736d951200090ee3f
-MEMWAL_REGISTRY_ID=0xfb8a1d298e2a73bdab353da3fcb3b16f68ab7d1f392f3a5c4944c747c026fc05
+```bash
+curl http://localhost:8000/health
 ```
 
-Important:
-
-- use `MEMWAL_PACKAGE_ID` and `MEMWAL_REGISTRY_ID` in `services/server/.env`
-- `VITE_MEMWAL_PACKAGE_ID` and `VITE_MEMWAL_REGISTRY_ID` are for the app or playground, not for the relayer
-- the current server config still requires `MEMWAL_REGISTRY_ID`
+## Environment Variables
 
-If you want the relayer to create real embeddings, set:
+### Required
 
-- `OPENAI_API_KEY`
-- `OPENAI_API_BASE`
+- `DATABASE_URL`
+- `MEMWAL_PACKAGE_ID`
+- `MEMWAL_REGISTRY_ID`
+- `SERVER_SUI_PRIVATE_KEY` or `SERVER_SUI_PRIVATE_KEYS`
+- `SEAL_KEY_SERVERS` — comma-separated list of SEAL key server object IDs
 
-The relayer uses these values to call an OpenAI-compatible `/embeddings` API during `remember`,
-`recall`, `analyze`, `ask`, and restore re-indexing.
+### Recommended
 
-You also need:
+- `OPENAI_API_KEY` — enables real embeddings (falls back to mock embeddings without it)
+- `OPENAI_API_BASE` — point to an OpenAI-compatible provider like OpenRouter
 
-- `SEAL_KEY_SERVERS`
+### Defaults
 
-The sidecar uses this comma-separated list of object IDs for backend SEAL encrypt and decrypt.
+- `PORT` defaults to `8000`
+- `SIDECAR_URL` defaults to `http://localhost:9000`
+- `SUI_NETWORK` defaults to `mainnet`
+- `SUI_RPC_URL`, Walrus endpoints, and `WALRUS_PACKAGE_ID` fall back to network defaults based on `SUI_NETWORK`
+- The sidecar Walrus upload route defaults storage `epochs` by network: `50` on `testnet`, `2` on `mainnet` (unless the request passes `epochs`)
 
-For testnet setup, use https://seal-docs.wal.app/Pricing to get the current SEAL key server object IDs.
+### Server Keys
 
-## Commands
+- `SERVER_SUI_PRIVATE_KEY` is the main server key
+- `SERVER_SUI_PRIVATE_KEYS` is a comma-separated key pool for parallel Walrus uploads
+- if both are set, the key pool takes priority for uploads
 
-Install sidecar dependencies:
+## Package Contract IDs
+### TESTNET
+```env
+SUI_NETWORK=testnet
+MEMWAL_PACKAGE_ID=0xcf6ad755a1cdff7217865c796778fabe5aa399cb0cf2eba986f4b582047229c6
+MEMWAL_REGISTRY_ID=0xe80f2feec1c139616a86c9f71210152e2a7ca552b20841f2e192f99f75864437
 
-```bash
-cd services/server/scripts
-npm ci
 ```
-
-Start the relayer:
-
-```bash
-cd services/server
-cargo run
+### MAINNET
+```env
+SUI_NETWORK=mainnet
+MEMWAL_PACKAGE_ID=0xcee7a6fd8de52ce645c38332bde23d4a30fd9426bc4681409733dd50958a24c6
+MEMWAL_REGISTRY_ID=0x0da982cefa26864ae834a8a0504b904233d49e20fcc17c373c8bed99c75a7edd
 ```
 
-The server starts the sidecar automatically through `npx tsx sidecar-server.ts`.
-
-Start the indexer:
+For SEAL key server object IDs on testnet, see https://seal-docs.wal.app/Pricing.
 
-```bash
-cd services/indexer
-cargo run
-```
+Using official key server of SDK is recommended. 
 
-## What To Expect
+<Note>
+`VITE_MEMWAL_PACKAGE_ID` and `VITE_MEMWAL_REGISTRY_ID` are frontend env vars for the app or playground — not for the relayer.
+</Note>
 
-- the relayer listens on `http://localhost:8000` by default
-- the sidecar listens on `http://localhost:9000` by default
-- the server runs DB migrations automatically on boot
-- `/health` is the first endpoint to test
+## Database Setup
 
-## Required For A Working Relayer
+The relayer requires PostgreSQL with the `pgvector` extension. The relayer runs migrations automatically on boot, creating these tables:
 
-- `DATABASE_URL`
-- `SUI_RPC_URL`
-- `WALRUS_PUBLISHER_URL`
-- `WALRUS_AGGREGATOR_URL`
-- `MEMWAL_PACKAGE_ID`
-- `MEMWAL_REGISTRY_ID`
-- `SERVER_SUI_PRIVATE_KEY` or `SERVER_SUI_PRIVATE_KEYS`
+- `vector_entries` — 1536-dimensional embeddings with HNSW index for cosine similarity search
+- `delegate_key_cache` — auth optimization (delegate key → account mapping)
+- `accounts` — populated by the indexer (account → owner mapping)
+- `indexer_state` — indexer cursor tracking
 
-## Recommended But Context-Dependent
+See [Database Sync](/indexer/database-sync) for the full schema.
 
-- `OPENAI_API_KEY`: lets the relayer call your embedding provider for real embeddings
-- `OPENAI_API_BASE`: use this when your provider is not the default OpenAI base URL
-- `SEAL_KEY_SERVERS`: required for backend SEAL encrypt and decrypt
-- indexer: recommended for fast account lookup, especially outside quick local testing
+## Operational Notes
 
-## Docker Path
+- The server starts the sidecar automatically on boot — if sidecar startup fails, the relayer will exit
+- DB migrations run automatically on boot (`pgvector` must already be installed as a PostgreSQL extension)
+- Connection pool: 10 max connections (relayer), 3 max connections (indexer)
+- `/health` is the basic service check, API routes live under `/api/*`
+- The indexer is recommended for fast account lookup in production — without it, the relayer falls back to onchain registry scans
+- Without `OPENAI_API_KEY`, the server uses deterministic mock embeddings (hash-based) — useful for local testing but not production
 
-If you want to deploy the relayer as a container, use:
+## Docker
 
 - `services/server/Dockerfile` for the relayer
 - `services/indexer/Dockerfile` for the indexer
 
 ## Read Next
 
-- [Installation and Setup](/relayer/installation-and-setup)
-- [Relayer API](/reference/relayer-api)
+- [Relayer API](/relayer/api-reference)
diff --git a/docs/sdk/ai-integration.md b/docs/sdk/ai-integration.md
index b6eb6dd5..559f0f3e 100644
--- a/docs/sdk/ai-integration.md
+++ b/docs/sdk/ai-integration.md
@@ -1,5 +1,5 @@
 ---
-title: "AI Integration"
+title: "@ai-sdk Integration"
 ---
 
 MemWal includes an AI SDK integration for applications that already use model middleware.
@@ -8,11 +8,12 @@ MemWal includes an AI SDK integration for applications that already use model mi
 
 ```ts
 import { generateText } from "ai";
-import { withMemWal } from "@cmdoss/memwal/ai";
+import { withMemWal } from "@mysten/memwal/ai";
 import { openai } from "@ai-sdk/openai";
 
 const model = withMemWal(openai("gpt-4o"), {
   key: process.env.MEMWAL_PRIVATE_KEY!,
+  accountId: process.env.MEMWAL_ACCOUNT_ID!,
   serverUrl: process.env.MEMWAL_SERVER_URL,
   namespace: "chatbot-prod",
   maxMemories: 5,
diff --git a/docs/sdk/api-reference.md b/docs/sdk/api-reference.md
new file mode 100644
index 00000000..c1f5cbc6
--- /dev/null
+++ b/docs/sdk/api-reference.md
@@ -0,0 +1,205 @@
+---
+title: "API Reference"
+---
+
+See also:
+
+- [Configuration](/reference/configuration)
+- [Relayer API](/relayer/api-reference)
+
+## `MemWal.create(config)`
+
+```ts
+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](/reference/configuration).
+
+## `MemWal` Methods
+
+### `remember(text, namespace?): Promise<RememberResult>`
+
+Store one memory through the relayer. The relayer handles embedding, SEAL encryption, Walrus upload, and vector indexing.
+
+**Returns:**
+
+```ts
+{
+  id: string;        // UUID for this entry
+  blob_id: string;   // Walrus blob ID
+  owner: string;     // Owner Sui address
+  namespace: string; // Namespace used
+}
+```
+
+### `recall(query, limit?, namespace?): Promise<RecallResult>`
+
+Search for memories matching a natural language query, scoped to `owner + namespace`.
+
+- `limit` defaults to `10`
+
+**Returns:**
+
+```ts
+{
+  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 store each fact as a separate memory.
+
+**Returns:**
+
+```ts
+{
+  facts: Array<{
+    text: string;     // Extracted fact
+    id: string;       // UUID
+    blob_id: string;  // Walrus blob ID
+  }>;
+  total: number;
+  owner: string;
+}
+```
+
+### `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:**
+
+```ts
+{
+  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`
+
+```ts
+import { MemWalManual } from "@mysten/memwal/manual";
+```
+
+See [MemWalManual usage](/sdk/usage/memwal-manual) 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`
+
+```ts
+import { withMemWal } from "@mysten/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](/reference/configuration) for all options.
+
+## Account Management
+
+```ts
+import {
+  createAccount,
+  addDelegateKey,
+  removeDelegateKey,
+  generateDelegateKey,
+} from "@mysten/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
+
+```ts
+import { delegateKeyToSuiAddress, delegateKeyToPublicKey } from "@mysten/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 |
diff --git a/docs/sdk/basic-usage.md b/docs/sdk/basic-usage.md
deleted file mode 100644
index c871e068..00000000
--- a/docs/sdk/basic-usage.md
+++ /dev/null
@@ -1,46 +0,0 @@
----
-title: "Basic Usage"
----
-
-## Use This When
-
-- you want the shortest working MemWal example
-- you are using the default relayer-backed SDK
-
-## Code
-
-```ts
-import { MemWal } from "@cmdoss/memwal";
-
-const memwal = MemWal.create({
-  key: process.env.MEMWAL_PRIVATE_KEY!,
-  serverUrl: process.env.MEMWAL_SERVER_URL,
-  namespace: "demo",
-});
-
-await memwal.health();
-
-const stored = await memwal.remember(
-  "User prefers dark mode and works in TypeScript."
-);
-
-const recalled = await memwal.recall(
-  "What do we know about this user?",
-  5
-);
-
-console.log(stored.blob_id);
-console.log(recalled.results);
-```
-
-## What You Should See
-
-- `health()` succeeds
-- `remember()` returns a `blob_id`
-- `recall()` returns plaintext results for the same namespace
-
-## Read Next
-
-- [Advanced Usage](/sdk/advanced-usage)
-- [SDK Usage](/sdk/usage)
-- [SDK API Reference](/reference/sdk-api)
diff --git a/docs/sdk/example-map.md b/docs/sdk/example-map.md
index 998b47a6..5e5d552a 100644
--- a/docs/sdk/example-map.md
+++ b/docs/sdk/example-map.md
@@ -4,6 +4,6 @@ title: "Example Map"
 
 ## Start Here
 
-- [Basic Usage](/sdk/basic-usage): initialize the SDK, store one memory, recall it
+- [Quick Start](/sdk/quick-start): install the SDK and store your first memory
 - [Advanced Usage](/sdk/advanced-usage): manual methods, `analyze()`, and AI middleware
 - [Research App Example](/sdk/research-app-example): application-level pattern for structured memory
diff --git a/docs/sdk/examples.md b/docs/sdk/examples.md
new file mode 100644
index 00000000..c3be717f
--- /dev/null
+++ b/docs/sdk/examples.md
@@ -0,0 +1,72 @@
+---
+title: "Examples"
+---
+
+## Basic: Store and Recall
+
+The shortest working MemWal example using the default relayer-backed SDK.
+
+```ts
+import { MemWal } from "@mysten/memwal";
+
+const memwal = MemWal.create({
+  key: process.env.MEMWAL_PRIVATE_KEY!,
+  accountId: process.env.MEMWAL_ACCOUNT_ID!,
+  serverUrl: process.env.MEMWAL_SERVER_URL,
+  namespace: "demo",
+});
+
+await memwal.health();
+
+const stored = await memwal.remember(
+  "User prefers dark mode and works in TypeScript."
+);
+
+const recalled = await memwal.recall(
+  "What do we know about this user?",
+  5
+);
+
+console.log(stored.blob_id);
+console.log(recalled.results);
+```
+
+What you should see:
+
+- `health()` succeeds
+- `remember()` returns a `blob_id`
+- `recall()` returns plaintext results for the same namespace
+
+## Advanced: Manual Methods and Analyze
+
+### Manual Registration
+
+Use `rememberManual()` when you already have an encrypted payload plus vector, and `recallManual()`
+when you already have a query vector.
+
+### Fact Extraction
+
+Use `analyze()` when you want the relayer to extract facts from longer text and store them as
+memories.
+
+```ts
+const analyzed = await memwal.analyze(
+  "I live in Hanoi, prefer dark mode, and usually work late at night."
+);
+console.log(analyzed.facts);
+```
+
+### AI Middleware
+
+Use `withMemWal` when you want recall before generation and optional auto-save after generation.
+See [AI Integration](/sdk/ai-integration) for the full setup.
+
+## Research App Pattern
+
+Use this when you want to store structured research findings and recall them in later sessions.
+
+1. Save a structured summary with `remember()`
+2. Generate targeted queries later
+3. Use `recall()` to pull relevant findings back into context
+
+Structured summaries usually recall better than raw transcripts because they keep the signal high.
diff --git a/docs/sdk/overview.md b/docs/sdk/overview.md
index 190cb873..32e8f307 100644
--- a/docs/sdk/overview.md
+++ b/docs/sdk/overview.md
@@ -1,10 +1,10 @@
 ---
-title: "SDK Overview"
+title: "Overview"
 ---
 
 MemWal exposes three SDK surfaces.
 
-## `@cmdoss/memwal`
+## `@mysten/memwal`
 
 Use this first.
 
@@ -13,25 +13,25 @@ Use this first.
 - main methods: `remember`, `recall`, `analyze`, `restore`, `health`
 
 ```ts
-import { MemWal } from "@cmdoss/memwal";
+import { MemWal } from "@mysten/memwal";
 ```
 
-## `@cmdoss/memwal/manual`
+## `@mysten/memwal/manual`
 
 Use this when the client must handle embeddings and local SEAL operations.
 
 - relayer still handles upload relay, registration, search, and restore
 
 ```ts
-import { MemWalManual } from "@cmdoss/memwal/manual";
+import { MemWalManual } from "@mysten/memwal/manual";
 ```
 
-## `@cmdoss/memwal/ai`
+## `@mysten/memwal/ai`
 
 Use this when you already use the AI SDK.
 
 ```ts
-import { withMemWal } from "@cmdoss/memwal/ai";
+import { withMemWal } from "@mysten/memwal/ai";
 ```
 
 ## Namespace
@@ -40,7 +40,7 @@ Both clients support a default namespace. If you omit it, it falls back to `"def
 
 ## Recommended Path
 
-1. start with `MemWal`
-2. set a namespace explicitly
-3. validate `remember`, `recall`, `analyze`, and `restore`
-4. move to `MemWalManual` only if you need client-managed embeddings and local SEAL work
+1. Start with `MemWal`
+2. Set a namespace explicitly
+3. Validate `remember`, `recall`, `analyze`, and `restore`
+4. Move to `MemWalManual` only if you need client-managed embeddings and local SEAL work
diff --git a/docs/sdk/quick-start.md b/docs/sdk/quick-start.md
index bb148bca..43408fea 100644
--- a/docs/sdk/quick-start.md
+++ b/docs/sdk/quick-start.md
@@ -1,56 +1,101 @@
 ---
 title: "Quick Start"
+description: "Install the MemWal SDK and store your first memory in under a minute."
 ---
 
-This example uses the default relayer-backed client.
+The MemWal SDK gives your app persistent, encrypted memory — store, recall, and analyze context across sessions. It exposes three entry points:
 
-```ts
-import { MemWal } from "@cmdoss/memwal";
+| Entry point | Import | When to use |
+| --- | --- | --- |
+| `MemWal` | `@mysten/memwal` | **Recommended default** for most integrations — relayer handles embeddings, SEAL, and storage |
+| `MemWalManual` | `@mysten/memwal/manual` | You need client-managed embeddings and local SEAL operations |
+| `withMemWal` | `@mysten/memwal/ai` | You already use the Vercel AI SDK and want memory as middleware |
 
-const memwal = MemWal.create({
-  key: process.env.MEMWAL_PRIVATE_KEY!,
-  serverUrl: process.env.MEMWAL_SERVER_URL,
-  namespace: process.env.MEMWAL_NAMESPACE ?? "demo",
-});
+## Installation
 
-await memwal.health();
-await memwal.remember("I live in Hanoi and prefer dark mode.");
+<CodeGroup>
 
-const recall = await memwal.recall("What do we know about this user?");
-console.log(recall.results);
+```bash npm
+npm install @mysten/memwal
+```
 
-const analyzed = await memwal.analyze(
-  "I live in Hanoi, prefer dark mode, and usually work late at night."
-);
-console.log(analyzed.facts);
+```bash pnpm
+pnpm add @mysten/memwal
 ```
 
-## Good Namespace Examples
+```bash yarn
+yarn add @mysten/memwal
+```
 
-- `chatbot-prod`
-- `researcher-staging`
-- `support-agent`
+</CodeGroup>
 
-Avoid keeping everything in `"default"` after early testing.
+For `MemWalManual`, you also need the optional peer dependencies:
 
-## What Happens
+<CodeGroup>
 
-- the SDK signs each request
-- the relayer verifies delegate access
-- data is stored and searched by `owner + namespace`
-- the relayer coordinates embeddings, SEAL, Walrus, and vector indexing
+```bash npm
+npm install @mysten/sui @mysten/seal @mysten/walrus
+```
 
-## Restore Example
+```bash pnpm
+pnpm add @mysten/sui @mysten/seal @mysten/walrus
+```
 
-```ts
-const result = await memwal.restore("demo");
-console.log(result);
+```bash yarn
+yarn add @mysten/sui @mysten/seal @mysten/walrus
+```
+
+</CodeGroup>
+
+For `withMemWal`, you also need:
+
+<CodeGroup>
+
+```bash npm
+npm install ai zod
+```
+
+```bash pnpm
+pnpm add ai zod
 ```
 
-Use restore when the relayer needs to rebuild missing indexed state for one namespace.
+```bash yarn
+yarn add ai zod
+```
+
+</CodeGroup>
+
+## Configuration
+
+`MemWal.create` takes a config object with the following fields:
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `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) |
+| `namespace` | `string` | No | Default namespace — falls back to `"default"` |
+
+## First Memory
+
+```ts
+import { MemWal } from "@mysten/memwal";
+
+const memwal = MemWal.create({
+  key: "<your-ed25519-private-key>",
+  accountId: "<your-memwal-account-id>",
+  serverUrl: "https://your-relayer-url.com",
+  namespace: "demo",
+});
+
+await memwal.health();
+await memwal.remember("I live in Hanoi and prefer dark mode.");
+
+const result = await memwal.recall("What do we know about this user?");
+console.log(result.results);
+```
 
 ## Next Steps
 
-- [SDK Usage](/sdk/usage)
-- [AI Integration](/sdk/ai-integration)
-- [SDK API Reference](/reference/sdk-api)
+- [Usage](/sdk/usage) — all three clients in detail, namespace rules, and restore
+- [API Reference](/sdk/api-reference) — full method signatures and config fields
diff --git a/docs/sdk/usage.md b/docs/sdk/usage.md
index 13f81e22..0318feaa 100644
--- a/docs/sdk/usage.md
+++ b/docs/sdk/usage.md
@@ -1,136 +1,20 @@
 ---
 title: "Usage"
+description: "Detailed usage for all three MemWal clients — MemWal, MemWalManual, and withMemWal."
 ---
 
-This page lists the current public SDK surface in one place.
+MemWal exposes three entry points:
 
-## Namespace Rules
-
-- set a default namespace in `create(...)` when one app or tenant uses one boundary
-- pass `namespace` per call when one client needs multiple boundaries
-- if omitted, namespace falls back to client config, then to `"default"`
-
-## `MemWal`
-
-Use `MemWal` when you want the relayer to handle the main workflow.
-
-### Create
-
-```ts
-const memwal = MemWal.create({
-  key: process.env.MEMWAL_PRIVATE_KEY!,
-  serverUrl: process.env.MEMWAL_SERVER_URL,
-  namespace: "chatbot-prod",
-});
-```
-
-Config:
-
-- `key`
-- `serverUrl?`
-- `namespace?`
-
-### Main Methods
-
-- `remember(text, namespace?)`: store text as memory
-- `recall(query, limit?, namespace?)`: return decrypted matches
-- `analyze(text, namespace?)`: extract facts and store them
-- `restore(namespace, limit?)`: rebuild missing indexed entries for one namespace
-- `health()`: check relayer health
-- `getPublicKeyHex()`: return the current public key
-
-### Lower-Level Methods
-
-- `rememberManual({ blobId, vector, namespace? })`
-- `recallManual({ vector, limit?, namespace? })`
-- `embed(text)`
-
-### Restore
-
-```ts
-const result = await memwal.restore("chatbot-prod", 50);
-console.log(result);
-```
-
-Restore is:
-
-- incremental
-- namespace-scoped
-- meant to repair PostgreSQL vector state from Walrus-backed memory
-
-## `MemWalManual`
+| Entry point | Import | When to use |
+| --- | --- | --- |
+| `MemWal` | `@mysten/memwal` | **Recommended default** — relayer handles embeddings, SEAL, and storage |
+| `MemWalManual` | `@mysten/memwal/manual` | You need client-managed embeddings and local SEAL operations |
+| `withMemWal` | `@mysten/memwal/ai` | You already use the Vercel AI SDK and want memory as middleware |
 
-Use `MemWalManual` when the client must handle embeddings and local SEAL operations.
-
-### Create
-
-```ts
-const manual = MemWalManual.create({
-  key: process.env.MEMWAL_PRIVATE_KEY!,
-  serverUrl: process.env.MEMWAL_SERVER_URL,
-  suiPrivateKey: process.env.SUI_PRIVATE_KEY!,
-  embeddingApiKey: process.env.OPENAI_API_KEY!,
-  packageId: process.env.MEMWAL_PACKAGE_ID!,
-  accountId: process.env.MEMWAL_ACCOUNT_ID!,
-  namespace: "chatbot-prod",
-});
-```
-
-Key config fields:
-
-- `key`
-- `serverUrl?`
-- `suiPrivateKey?` or `walletSigner?`
-- `suiNetwork?`
-- `sealKeyServers?`
-- `embeddingApiKey`
-- `embeddingApiBase?`
-- `embeddingModel?`
-- `packageId`
-- `accountId`
-- `namespace?`
-
-Manual mode notes:
-
-- `suiNetwork` defaults to `mainnet`
-- `sealKeyServers` lets the client override the built-in SEAL key server object IDs
-- Walrus publisher, aggregator, and upload relay defaults now follow `suiNetwork`
-
-### Main Methods
-
-- `rememberManual(text, namespace?)`: embed locally, encrypt locally, then send encrypted payload plus vector to the relayer
-- `recallManual(query, limit?, namespace?)`: embed locally, search through the relayer, download blobs, and decrypt locally
-- `restore(namespace, limit?)`: call the same relayer restore endpoint
-- `isWalletMode`: tells you whether the client uses a connected wallet signer
-
-## `withMemWal`
-
-Use `withMemWal(model, options)` when your app already uses the AI SDK.
-
-```ts
-const model = withMemWal(openai("gpt-4o"), {
-  key: process.env.MEMWAL_PRIVATE_KEY!,
-  serverUrl: process.env.MEMWAL_SERVER_URL,
-  namespace: "chatbot-prod",
-});
-```
-
-Behavior:
-
-- recall before generation
-- inject memory context
-- optional `analyze()` after generation
-
-Options:
-
-- `key`, `serverUrl?`, `namespace?`
-- `maxMemories?`
-- `autoSave?`
-- `minRelevance?`
-- `debug?`
+## Namespace Rules
 
-## Recommended Paths
+- Set a default namespace in `create(...)` when one app or tenant uses one boundary
+- Pass `namespace` per call when one client needs multiple boundaries
+- If omitted, namespace falls back to client config, then to `"default"`
 
-- `MemWal`: best default for most integrations
-- `MemWalManual`: use when you need client-managed embeddings and local SEAL work
-- `withMemWal`: use when you already run the AI SDK
+Good namespace examples: `todo`, `personal`, `password`, `project-x`. Avoid keeping everything in `"default"` after early testing.
diff --git a/docs/sdk/usage/memwal-manual.md b/docs/sdk/usage/memwal-manual.md
new file mode 100644
index 00000000..a7f70c49
--- /dev/null
+++ b/docs/sdk/usage/memwal-manual.md
@@ -0,0 +1,100 @@
+---
+title: "MemWalManual"
+description: "Client-managed embeddings and local SEAL operations."
+---
+
+Use when the client must handle embedding calls and local SEAL operations. The relayer still handles
+upload relay, vector registration, search, and restore.
+
+This is the recommended path for Web3-native users who want to minimize trust in the relayer — it never sees your plaintext data.
+
+## What the client handles vs. what the relayer handles
+
+| Operation | Client (MemWalManual) | Relayer |
+|-----------|----------------------|---------|
+| Embedding | Client calls OpenAI/compatible API | — |
+| SEAL encryption | Client encrypts locally | — |
+| Walrus upload | — | Server uploads via sidecar (server pays gas) |
+| Vector registration | — | Server stores `{blob_id, vector}` in PostgreSQL |
+| Recall search | — | Server searches vectors, returns `{blob_id, distance}` |
+| Walrus download | Client downloads from aggregator | — |
+| SEAL decryption | Client decrypts locally (SessionKey) | — |
+
+## Setup
+
+```ts
+import { MemWalManual } from "@mysten/memwal/manual";
+
+const manual = MemWalManual.create({
+  key: "<your-ed25519-private-key>",
+  serverUrl: "https://your-relayer-url.com",
+  suiPrivateKey: "<your-sui-private-key>",    // OR walletSigner
+  embeddingApiKey: "<your-openai-api-key>",
+  packageId: "<memwal-package-id>",
+  accountId: "<memwal-account-id>",
+  namespace: "chatbot-prod",
+});
+```
+
+## Core Methods
+
+```ts
+// Embed locally, encrypt locally, relay encrypted payload + vector
+await manual.rememberManual("User prefers dark mode.");
+
+// Embed locally, search via relayer, download and decrypt locally
+const result = await manual.recallManual("What do we know?", 5);
+for (const memory of result.results) {
+  console.log(memory.text, memory.distance);
+}
+
+// Same relayer restore endpoint
+await manual.restore("chatbot-prod", 50);
+
+// Check if using a connected wallet signer
+console.log(manual.isWalletMode);
+```
+
+## Remember flow (under the hood)
+
+1. Client generates embedding via OpenAI-compatible API
+2. Client SEAL-encrypts the plaintext locally (no wallet signature needed)
+3. Client sends `{encrypted_data (base64), vector}` to the relayer
+4. Relayer uploads encrypted bytes to Walrus via upload-relay sidecar (server pays gas)
+5. Relayer stores `{blob_id, vector, owner, namespace}` in PostgreSQL
+
+## Recall flow (under the hood)
+
+1. Client generates query embedding via OpenAI-compatible API
+2. Client sends the vector to the relayer
+3. Relayer searches PostgreSQL and returns `{blob_id, distance}` hits
+4. Client downloads all matching encrypted blobs from Walrus concurrently
+5. Client creates a single SEAL SessionKey (one wallet popup in browser mode)
+6. Client decrypts each blob locally using the shared session key
+
+## Browser Integration (wallet signer)
+
+Use `walletSigner` instead of `suiPrivateKey` when integrating with a connected wallet (e.g., `@mysten/dapp-kit`):
+
+```ts
+const manual = MemWalManual.create({
+  key: "<your-ed25519-delegate-key>",
+  walletSigner: {
+    address: walletAddress,
+    signAndExecuteTransaction: signAndExecuteTransaction,
+    signPersonalMessage: signPersonalMessage,
+  },
+  embeddingApiKey: "<your-openai-api-key>",
+  packageId: "<memwal-package-id>",
+  accountId: "<memwal-account-id>",
+});
+```
+
+## Config Notes
+
+- `suiNetwork` defaults to `mainnet`
+- `sealKeyServers` lets the client override the built-in SEAL key server object IDs
+- Walrus publisher, aggregator, and upload relay defaults follow `suiNetwork`
+- `embeddingModel` defaults to `text-embedding-3-small` (or `openai/text-embedding-3-small` for OpenRouter)
+- `walrusEpochs` defaults to `50` (storage duration)
+- All `@mysten/*` peer dependencies are loaded dynamically — users who only use the default `MemWal` client don't need them installed
diff --git a/docs/sdk/usage/memwal.md b/docs/sdk/usage/memwal.md
new file mode 100644
index 00000000..85919ed0
--- /dev/null
+++ b/docs/sdk/usage/memwal.md
@@ -0,0 +1,60 @@
+---
+title: "MemWal"
+description: "The recommended default client — relayer handles embeddings, SEAL, and storage."
+---
+
+The recommended default client. The relayer handles embeddings, SEAL encryption, Walrus upload, and vector indexing.
+
+## How It Works
+
+1. The SDK signs each request with your delegate key
+2. The relayer verifies delegate access
+3. `remember` encrypts via SEAL, uploads to Walrus, and indexes the vector embedding
+4. `recall` searches by Memory Space and returns decrypted matches
+
+```ts
+import { MemWal } from "@mysten/memwal";
+
+const memwal = MemWal.create({
+  key: "<your-ed25519-private-key>",
+  accountId: "<your-memwal-account-id>",
+  serverUrl: "https://your-relayer-url.com",
+  namespace: "chatbot-prod",
+});
+```
+
+## Core Methods
+
+```ts
+// Store a memory
+await memwal.remember("User prefers dark mode and works in TypeScript.");
+
+// Recall relevant memories
+const result = await memwal.recall("What do we know about this user?", 5);
+
+// Extract and store facts from longer text
+const analyzed = await memwal.analyze(
+  "I live in Hanoi, prefer dark mode, and usually work late at night."
+);
+console.log(analyzed.facts);
+
+// Check relayer health
+await memwal.health();
+```
+
+## Restore
+
+Rebuild missing indexed entries for one namespace. Incremental, namespace-scoped, and meant to
+repair PostgreSQL vector state from Walrus-backed memory.
+
+```ts
+const result = await memwal.restore("chatbot-prod", 50);
+```
+
+## Lower-Level Methods
+
+Use these when you already have a vector or encrypted payload:
+
+- `rememberManual({ blobId, vector, namespace? })`
+- `recallManual({ vector, limit?, namespace? })`
+- `embed(text)`
diff --git a/docs/sdk/usage/with-memwal.md b/docs/sdk/usage/with-memwal.md
new file mode 100644
index 00000000..2788e0c6
--- /dev/null
+++ b/docs/sdk/usage/with-memwal.md
@@ -0,0 +1,51 @@
+---
+title: "withMemWal"
+description: "Drop-in memory middleware for Vercel AI SDK apps."
+---
+
+Drop-in memory middleware for Vercel AI SDK apps.
+
+```ts
+import { generateText } from "ai";
+import { withMemWal } from "@mysten/memwal/ai";
+import { openai } from "@ai-sdk/openai";
+
+const model = withMemWal(openai("gpt-4o"), {
+  key: "<your-ed25519-private-key>",
+  accountId: "<your-memwal-account-id>",
+  serverUrl: "https://your-relayer-url.com",
+  namespace: "chatbot-prod",
+  maxMemories: 5,
+  autoSave: true,
+});
+
+const result = await generateText({
+  model,
+  messages: [{ role: "user", content: "What do you know about me?" }],
+});
+```
+
+## What It Does
+
+Before generation:
+
+- Reads the last user message
+- Runs `recall()` against MemWal
+- Filters by relevance
+- Injects memory context into the prompt
+
+After generation:
+
+- Optionally runs `analyze()` on the user message
+- Saves extracted facts asynchronously
+
+Set a namespace explicitly for each product surface that uses the middleware. Otherwise recalled
+and auto-saved memories fall back to `"default"`.
+
+## When To Use Direct SDK Calls Instead
+
+Use direct SDK methods when your app needs precise control over:
+
+- When memory is stored
+- Which text is analyzed
+- How recall results are displayed or filtered

From 7d986df75f4c456f7dafd15a490aa8c47bac6c5c Mon Sep 17 00:00:00 2001
From: Aaron1924 <planh21@clc.fitus.edu.vn>
Date: Tue, 24 Mar 2026 22:03:12 +0700
Subject: [PATCH 13/16] docs: surface network ids and reorder examples tab

---
 docs/contract/overview.md    | 22 ++++++++++++++++++++++
 docs/docs.json               | 22 +++++++++++-----------
 docs/relayer/self-hosting.md |  4 ++--
 3 files changed, 35 insertions(+), 13 deletions(-)

diff --git a/docs/contract/overview.md b/docs/contract/overview.md
index b505fac5..615e3adf 100644
--- a/docs/contract/overview.md
+++ b/docs/contract/overview.md
@@ -4,6 +4,28 @@ title: "Smart Contract Overview"
 
 The smart contract (`memwal::account`) defines the onchain account model for MemWal. It is a Move module deployed on Sui.
 
+## Network IDs
+
+These are the onchain IDs for the current public MemWal deployments:
+
+### Staging (Testnet)
+
+```env
+SUI_NETWORK=testnet
+MEMWAL_PACKAGE_ID=0xcf6ad755a1cdff7217865c796778fabe5aa399cb0cf2eba986f4b582047229c6
+MEMWAL_REGISTRY_ID=0xe80f2feec1c139616a86c9f71210152e2a7ca552b20841f2e192f99f75864437
+```
+
+### Production (Mainnet)
+
+```env
+SUI_NETWORK=mainnet
+MEMWAL_PACKAGE_ID=0xcee7a6fd8de52ce645c38332bde23d4a30fd9426bc4681409733dd50958a24c6
+MEMWAL_REGISTRY_ID=0x0da982cefa26864ae834a8a0504b904233d49e20fcc17c373c8bed99c75a7edd
+```
+
+For relayer setup and environment variable usage, see [Self-Hosting](/relayer/self-hosting) and [Environment Variables](/reference/environment-variables).
+
 ## What It Manages
 
 - **Ownership** — who owns a MemWal account
diff --git a/docs/docs.json b/docs/docs.json
index 3f7e4995..19194ada 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -48,17 +48,6 @@
           }
         ]
       },
-      {
-        "tab": "Examples",
-        "groups": [
-          {
-            "group": "Examples",
-            "pages": [
-              "examples/example-apps"
-            ]
-          }
-        ]
-      },
       {
         "tab": "Fundamentals",
         "groups": [
@@ -140,6 +129,17 @@
           }
         ]
       },
+      {
+        "tab": "Examples",
+        "groups": [
+          {
+            "group": "Examples",
+            "pages": [
+              "examples/example-apps"
+            ]
+          }
+        ]
+      },
       {
         "tab": "Reference",
         "groups": [
diff --git a/docs/relayer/self-hosting.md b/docs/relayer/self-hosting.md
index d941f325..d532429b 100644
--- a/docs/relayer/self-hosting.md
+++ b/docs/relayer/self-hosting.md
@@ -82,14 +82,14 @@ curl http://localhost:8000/health
 - if both are set, the key pool takes priority for uploads
 
 ## Package Contract IDs
-### TESTNET
+### Staging (Testnet)
 ```env
 SUI_NETWORK=testnet
 MEMWAL_PACKAGE_ID=0xcf6ad755a1cdff7217865c796778fabe5aa399cb0cf2eba986f4b582047229c6
 MEMWAL_REGISTRY_ID=0xe80f2feec1c139616a86c9f71210152e2a7ca552b20841f2e192f99f75864437
 
 ```
-### MAINNET
+### Production (Mainnet)
 ```env
 SUI_NETWORK=mainnet
 MEMWAL_PACKAGE_ID=0xcee7a6fd8de52ce645c38332bde23d4a30fd9426bc4681409733dd50958a24c6

From a845c40d82e8cb7d8bff2e92ec69efc61c2c4489 Mon Sep 17 00:00:00 2001
From: ducnmm <mauduckiengiang@gmail.com>
Date: Tue, 24 Mar 2026 22:04:42 +0700
Subject: [PATCH 14/16] fix: add VITE_DEMO_URLS to walrus deploy workflow

---
 .github/workflows/deploy-app-walrus.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/deploy-app-walrus.yml b/.github/workflows/deploy-app-walrus.yml
index ff5c5d3f..193b1299 100644
--- a/.github/workflows/deploy-app-walrus.yml
+++ b/.github/workflows/deploy-app-walrus.yml
@@ -64,6 +64,7 @@ jobs:
           VITE_MEMWAL_REGISTRY_ID: ${{ vars.VITE_MEMWAL_REGISTRY_ID }}
           VITE_SEAL_KEY_SERVERS: ${{ vars.VITE_SEAL_KEY_SERVERS }}
           VITE_DOCS_URL: ${{ vars.VITE_DOCS_URL }}
+          VITE_DEMO_URLS: ${{ vars.VITE_DEMO_URLS }}
 
       - name: Deploy to Walrus Site (Mainnet)
         id: deploy-mainnet

From d00e01a48724da2a151e2d9c88f7f80747fece5d Mon Sep 17 00:00:00 2001
From: Aaron1924 <planh21@clc.fitus.edu.vn>
Date: Tue, 24 Mar 2026 22:26:45 +0700
Subject: [PATCH 15/16] docs: update MemWal positioning copy

---
 docs/getting-started/what-is-memwal.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/getting-started/what-is-memwal.md b/docs/getting-started/what-is-memwal.md
index 96039af3..9a5c2daa 100644
--- a/docs/getting-started/what-is-memwal.md
+++ b/docs/getting-started/what-is-memwal.md
@@ -1,9 +1,9 @@
 ---
 title: "What is MemWal?"
-description: "Privacy-preserving, decentralized memory layer for humans and AI agents — powered by Walrus and Sui."
+description: "Persistent, verifiable memory for AI agents"
 ---
 
-MemWal is a privacy-preserving, decentralized memory layer for humans and AI agents — powered by Walrus and Sui. Store, recall, and share memory across apps, sessions, and agents.
+MemWal introduces a long-term, verifiable memory layer on Walrus, allowing agents to remember, share, and reuse information reliably.
 
 <CardGroup cols={2}>
   <Card title="End-to-End Encrypted" icon="lock">

From 998255fbd98488bd6bce907d0af41f1ab0e5638a Mon Sep 17 00:00:00 2001
From: Aaron1924 <planh21@clc.fitus.edu.vn>
Date: Tue, 24 Mar 2026 22:53:22 +0700
Subject: [PATCH 16/16] docs: remove duplicate examples tab

---
 docs/docs.json | 11 -----------
 1 file changed, 11 deletions(-)

diff --git a/docs/docs.json b/docs/docs.json
index 6e689994..19194ada 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -48,17 +48,6 @@
           }
         ]
       },
-      {
-        "tab": "Examples",
-        "groups": [
-          {
-            "group": "Examples",
-            "pages": [
-              "examples/example-apps"
-            ]
-          }
-        ]
-      },
       {
         "tab": "Fundamentals",
         "groups": [