main <- staging

.github/workflows/deploy-app-walrus.yml

@@ -67,6 +67,7 @@ jobs:
           VITE_GOOGLE_CLIENT_ID: ${{ vars.VITE_GOOGLE_CLIENT_ID }}
           VITE_DOCS_URL: ${{ vars.VITE_DOCS_URL }}
           VITE_DEMO_URLS: ${{ vars.VITE_DEMO_URLS }}
+          VITE_GA_MEASUREMENT_ID: ${{ vars.VITE_GA_MEASUREMENT_ID }}
 
       - name: Deploy to Walrus Site (Mainnet)
         id: deploy-mainnet

README.md

@@ -37,7 +37,7 @@ const memwal = MemWal.create({
 
 const job = await memwal.remember("User prefers dark mode and uses TypeScript.");
 await memwal.waitForRememberJob(job.job_id);
-const memories = await memwal.recall("What are the user's preferences?");
+const memories = await memwal.recall({ query: "What are the user's preferences?" });
 await memwal.restore("demo");
 ```
 

SKILL.md

@@ -103,7 +103,7 @@ await memwal.rememberAndWait(
 );
 
 // Recall by meaning
-const result = await memwal.recall("What are the user's preferences?");
+const result = await memwal.recall({ query: "What are the user's preferences?" });
 console.log(result.results);
 
 // Extract facts from free-form text and wait until all accepted facts are indexed.
@@ -152,7 +152,7 @@ const stored = await memwal.waitForRememberJob(accepted.job_id, {
 |---|---|---|
 | `remember(text, namespace?)` | Accept one memory job immediately | `{ job_id, status }` |
 | `rememberAndWait(text, namespace?, opts?)` | Store one memory and wait for completion | `{ id, job_id, blob_id, owner, namespace }` |
-| `recall(query, limitOrOptions?, namespace?)` | Semantic search for memories | `{ results: [{ blob_id, text, distance }], total }` |
+| `recall({ query, limit?, namespace?, maxDistance? })` *(preferred)* or `recall(query, limit?, namespace?)` | Semantic search for memories | `{ results: [{ blob_id, text, distance }], total }` |
 | `analyze(text, namespace?)` | Extract facts and accept one memory job per fact | `{ job_ids, facts, fact_count, status, owner }` |
 | `analyzeAndWait(text, namespace?, opts?)` | Extract facts and wait for all fact jobs to complete | `{ results, facts, total, succeeded, failed, owner }` |
 | `restore(namespace, limit?)` | Rebuild missing index entries from Walrus | `{ restored, skipped, total, namespace, owner }` |
@@ -307,6 +307,79 @@ interface HealthResult {
 aligns with the accepted fact jobs; use `analyzeAndWait()` when the UI needs
 those facts indexed before continuing.
 
+### Namespace Semantics
+
+A namespace is an **opaque, flat string label** scoped to a single owner. It is the unit of memory isolation: a recall in namespace `A` will never surface entries written to namespace `B`, even for the same owner, and never surfaces other owners' entries even in the same namespace.
+
+#### Validation
+
+The server accepts any non-empty string as a namespace. There is no length cap, no character whitelist, no normalization (whitespace, case, Unicode). Whatever you send is stored verbatim and matched with exact equality. If you omit the namespace, the server falls back to the literal string `"default"`.
+
+> **Implication:** `"my-app"`, `" my-app"` (leading space), `"My-App"`, and `"my-app/"` are four distinct namespaces. Pick a convention and stick to it.
+
+#### Flat, not hierarchical
+
+Slashes and dots have **no special meaning**. `"chat/user-42"` is a single opaque label, not a path. The server uses `WHERE namespace = $1` exact-equality for every read; there is no prefix matching, no parent/child traversal, and no wildcard query. If you need hierarchy, build it in the application layer (e.g. recall across known namespaces and merge client-side).
+
+#### Overwrite behavior — `remember()` is **always append, never upsert**
+
+Every accepted `remember()` call creates a **new memory entry** with a freshly generated UUID. Sending the same text to the same `(owner, namespace)` twice will produce **two separate entries** that both surface in future recalls. The namespace is metadata for filtering, not a key for deduplication.
+
+```ts
+await memwal.remember("I prefer dark mode", "prefs");
+await memwal.remember("I prefer dark mode", "prefs");
+// recall("preferences", { namespace: "prefs" }) → 2 entries, both with the same text
+```
+
+If you need uniqueness, either dedupe before calling `remember()`, or delete the prior entry first.
+
+#### Isolation guarantees
+
+| Scenario | Visible to recall? |
+|---|---|
+| Same owner, same namespace | ✅ |
+| Same owner, different namespace | ❌ |
+| Different owner, same namespace | ❌ |
+| Different owner, different namespace | ❌ |
+
+Cross-namespace and cross-owner reads are not just filtered out of results — the server's SQL `WHERE` clause excludes them entirely, so they are never decrypted or transferred.
+
+### Restore Semantics
+
+`restore(namespace, limit?)` rebuilds **missing** local index entries for a namespace from Walrus. It is a recovery operation, not a sync — already-indexed blobs are left alone.
+
+#### Response fields
+
+| Field | Counts | Notes |
+|---|---|---|
+| `restored` | Blobs the relayer just rebuilt this call | Pulled from Walrus → SEAL decrypted → re-embedded → inserted as a new row |
+| `skipped` | On-chain blobs already in the local index | No work needed; relayer left them as-is |
+| `total` | All on-chain blobs the relayer saw for `(owner, namespace)` | Before the limit was applied |
+| `namespace` | Echo of the request | |
+| `owner` | Resolved owner address | |
+
+**Silent drops.** A blob that *cannot* be decrypted or embedded (e.g. wrong delegate key, malformed ciphertext, embedding API down) is dropped without counting in `restored` *or* `skipped`. `restored + skipped` is therefore a lower bound on healthy entries, not a strict equality with `total`.
+
+#### Default and limit
+
+* `limit` defaults to `10` in both TypeScript and Python SDKs and matches the server-side default. The Python SDK historically defaulted to `50`; it is now realigned with the server.
+* `limit` caps the **inspected** blob set, newest-first. It does not cap `restored` independently — if all 10 inspected blobs are already indexed, `restored = 0` and `skipped = 10`.
+* There is no enforced server-side maximum, but very large limits will dominate latency (see below).
+
+#### Pagination
+
+**Restore is single-shot — there is no cursor.** To rebuild a namespace larger than your chosen `limit`, call again with a larger `limit`, or delete local rows you want re-imported first. Pagination is on the roadmap; until it lands, treat `restore()` as a "top up to N most recent" operation.
+
+#### Performance
+
+Latency scales linearly in `limit`:
+
+* Up to **10 concurrent** Walrus aggregator downloads
+* Up to **3 concurrent** SEAL decrypts (CPU-bound, capped intentionally)
+* Embedding requests in parallel (bounded by the relayer's embedding pool)
+
+Expect **seconds per blob** on a cold cache. Use small limits (≤ 50) for interactive flows and run larger restores out-of-band.
+
 ### Recall Distance and Filtering
 
 `recall()` returns the closest K memories by vector distance. There is no
@@ -325,8 +398,9 @@ Lower distance means more similar:
 Use SDK-side filtering when you only want clearly relevant results:
 
 ```ts
-const memories = await memwal.recall("what did I eat yesterday?", {
-  topK: 10,
+const memories = await memwal.recall({
+  query: "what did I eat yesterday?",
+  limit: 10,
   namespace: "reading-tracker",
   maxDistance: 0.7,
 });
@@ -335,7 +409,11 @@ const memories = await memwal.recall("what did I eat yesterday?", {
 Equivalent manual filtering:
 
 ```ts
-const memories = await memwal.recall("what did I eat yesterday?", 10, "reading-tracker");
+const memories = await memwal.recall({
+  query: "what did I eat yesterday?",
+  limit: 10,
+  namespace: "reading-tracker",
+});
 const relevant = memories.results.filter((memory) => memory.distance < 0.7);
 ```
 
@@ -488,6 +566,17 @@ Lifecycle hooks run automatically:
 
 ---
 
+## Brand Terminology
+
+Until product confirms a canonical naming pass, these are the **working** assumptions reflected across this doc, the SDKs, and the relayer. Treat them as descriptive, not authoritative.
+
+| Surface | Canonical term | Notes |
+|---|---|---|
+| Product / docs / UI | **Walrus Memory** | Used in marketing copy, user-facing dashboards, and prose docs |
+| Package / env vars / internal shorthand | **memwal** | Used in `@mysten-incubation/memwal`, `pip install memwal`, `MEMWAL_*` env vars, internal logs, and codepaths |
+
+If you're writing user-facing copy, prefer "Walrus Memory". If you're writing an env var, import path, or grep-target, prefer `memwal`. Don't mass-rename existing identifiers — that requires a coordinated migration outside this skill's scope.
+
 ## Links
 
 - **Docs**: https://docs.memwal.ai

apps/app/.env.example

@@ -21,6 +21,9 @@ VITE_DOCS_URL=http://localhost:5174
 # Example: VITE_DEMO_URLS=Chat Demo|https://chat.example.com,Agent Demo|https://agent.example.com
 VITE_DEMO_URLS=
 
+# Google Analytics 4 Measurement ID. Leave blank to disable analytics.
+VITE_GA_MEASUREMENT_ID=
+
 # ══════════════════════════════════════════════════════════════
 # ▷ INACTIVE: MAINNET  (uncomment below, comment out TESTNET above)
 # ══════════════════════════════════════════════════════════════

apps/app/Dockerfile

@@ -36,6 +36,7 @@ ARG VITE_ENOKI_API_KEY
 ARG VITE_GOOGLE_CLIENT_ID
 ARG VITE_DOCS_URL
 ARG VITE_DEMO_URLS
+ARG VITE_GA_MEASUREMENT_ID
 
 ENV VITE_MEMWAL_SERVER_URL=$VITE_MEMWAL_SERVER_URL
 ENV VITE_MEMWAL_PACKAGE_ID=$VITE_MEMWAL_PACKAGE_ID
@@ -44,7 +45,8 @@ 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
+ENV VITE_DEMO_URLS=$VITE_DEMO_URLS
+ENV VITE_GA_MEASUREMENT_ID=$VITE_GA_MEASUREMENT_ID
 
 RUN pnpm --filter @memwal/app build
 

apps/app/src/App.tsx

@@ -25,6 +25,7 @@ import Dashboard from './pages/Dashboard'
 import SetupWizard from './pages/SetupWizard'
 import Playground from './pages/Playground'
 import ConnectMcp from './pages/ConnectMcp'
+import { useRouteAnalytics } from './hooks/useRouteAnalytics'
 
 
 import '@mysten/dapp-kit/dist/index.css'
@@ -60,7 +61,7 @@ interface DelegateKeyContextType extends DelegateKeyState {
 
 const DelegateKeyContext = createContext<DelegateKeyContextType | null>(null)
 
-// LOW-32: tunable idle-timeout. 15 minutes by default. Exported so callers/tests can read it.
+// tunable idle-timeout. 15 minutes by default. Exported so callers/tests can read it.
 export const INACTIVITY_TIMEOUT_MS = 15 * 60 * 1000
 
 // Debounce interval for activity events to avoid excessive timer resets.
@@ -104,7 +105,7 @@ function DelegateKeyProvider({ children }: { children: React.ReactNode }) {
   }, [])
 
   // ============================================================
-  // LOW-32: Idle-timeout — wipe in-memory key material and disconnect after inactivity.
+  // Idle-timeout — wipe in-memory key material and disconnect after inactivity.
   // ============================================================
   const { mutateAsync: disconnect } = useDisconnectWallet()
   const hasKey = state.delegateKey !== null
@@ -219,13 +220,19 @@ function AppContent() {
   )
 }
 
+function AnalyticsTracker() {
+  useRouteAnalytics()
+  return null
+}
+
 // ============================================================
 // Root App
 // ============================================================
 
 export default function App() {
   return (
     <BrowserRouter>
+      <AnalyticsTracker />
       <QueryClientProvider client={queryClient}>
         <SuiClientProvider networks={networkConfig} defaultNetwork={config.suiNetwork}>
           <RegisterEnokiWallets />

apps/app/src/config.ts

@@ -14,6 +14,7 @@ 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 || '',
+    gaMeasurementId: import.meta.env.VITE_GA_MEASUREMENT_ID as string || '',
     demoUrls: (import.meta.env.VITE_DEMO_URLS as string || '')
         .split(',').map(s => s.trim()).filter(Boolean)
         .map(entry => {

apps/app/src/hooks/useRouteAnalytics.ts

@@ -0,0 +1,85 @@
+import { useCallback, useEffect, useRef } from 'react'
+import { useLocation } from 'react-router-dom'
+import { initAnalytics, trackEvent, trackPageView } from '../utils/analytics'
+
+const SCROLL_THRESHOLDS = [25, 50, 75, 90] as const
+
+interface PageSession {
+    path: string
+    startedAt: number
+    reportedScrollDepths: Set<number>
+}
+
+export function useRouteAnalytics() {
+    const location = useLocation()
+    const pageSessionRef = useRef<PageSession | null>(null)
+
+    const flushPageTime = useCallback(() => {
+        const pageSession = pageSessionRef.current
+        if (!pageSession) return
+
+        const durationSeconds = Math.round((Date.now() - pageSession.startedAt) / 1000)
+        if (durationSeconds <= 0) return
+
+        trackEvent('page_time', {
+            page_path: pageSession.path,
+            duration_seconds: durationSeconds,
+        })
+        pageSession.startedAt = Date.now()
+    }, [])
+
+    useEffect(() => {
+        initAnalytics()
+
+        const path = `${location.pathname}${location.search}`
+        flushPageTime()
+        pageSessionRef.current = {
+            path,
+            startedAt: Date.now(),
+            reportedScrollDepths: new Set<number>(),
+        }
+        trackPageView(path)
+    }, [flushPageTime, location.pathname, location.search])
+
+    useEffect(() => {
+        const reportScrollDepth = () => {
+            const pageSession = pageSessionRef.current
+            if (!pageSession) return
+
+            const scrollableHeight = document.documentElement.scrollHeight - window.innerHeight
+            const percentScrolled = scrollableHeight <= 0
+                ? 100
+                : Math.min(100, Math.round((window.scrollY / scrollableHeight) * 100))
+
+            for (const threshold of SCROLL_THRESHOLDS) {
+                if (percentScrolled < threshold || pageSession.reportedScrollDepths.has(threshold)) continue
+                pageSession.reportedScrollDepths.add(threshold)
+                trackEvent('scroll_depth', {
+                    page_path: pageSession.path,
+                    percent_scrolled: threshold,
+                })
+            }
+        }
+
+        window.addEventListener('scroll', reportScrollDepth, { passive: true })
+        reportScrollDepth()
+
+        return () => window.removeEventListener('scroll', reportScrollDepth)
+    }, [location.pathname, location.search])
+
+    useEffect(() => {
+        const onVisibilityChange = () => {
+            if (document.visibilityState === 'hidden') flushPageTime()
+        }
+        const onBeforeUnload = () => flushPageTime()
+
+        document.addEventListener('visibilitychange', onVisibilityChange)
+        window.addEventListener('beforeunload', onBeforeUnload)
+
+        return () => {
+            document.removeEventListener('visibilitychange', onVisibilityChange)
+            window.removeEventListener('beforeunload', onBeforeUnload)
+            flushPageTime()
+        }
+    }, [flushPageTime])
+}

apps/app/src/hooks/useSponsoredTransaction.ts

@@ -30,7 +30,7 @@ export function useSponsoredTransaction() {
         try {
             // 1. Build TransactionKind bytes (without gas data)
             const kindBytes = await transaction.build({
-                client: suiClient as any,
+                client: suiClient,
                 onlyTransactionKind: true,
             })
             const kindBase64 = uint8ArrayToBase64(kindBytes)