docs: Walrus Memory lifecycle and console guides (BEDU-904) by reemsabawi-mystenlabs · Pull Request #486 · MystenLabs/MemWal

reemsabawi-mystenlabs · 2026-07-22T17:04:13Z

Summary

Adds the lifecycle/console pages of the Walrus Memory docs spine (BEDU-904) and wires them into navigation.

Ticket	Page	Covers
BEDU-609	`fundamentals/architecture/tracking-agent-storage.md`	The object model for agent-owned blobs (encrypted blob, Sui `Blob` object, storage resource, rebuildable vector entry); three ways to discover what an agent owns (capture at write time, query onchain by owner + namespace via `restore`, read the `Blob` object); expiry/renewal tracking; ownership in sponsored writes.
BEDU-661	`guides/manage-your-memory.md`	Browse/search by meaning (`recall`) and preview; namespace organization; epoch renewal; both deletion paths (cross-linking the existing delete guides); rebuilding a stale index with `restore`.
BEDU-665	`guides/returning-user.md`	First-sign-in delegate-key recovery; why a new delegate key still decrypts existing memories; `restore`-based rediscovery; the "you own your data, re-upload — no migration" expectation; onchain wallet-visibility caveats.

Navigation (docs/docs.json): the two guides join the Guides group; the tracking page joins Fundamentals → Architecture next to funding-storage.

Notes for reviewers

Grounded in the repo. Every code sample's method and field names were verified against packages/sdk/src/ (recall({query,limit}), restore → {restored,skipped,total}, rememberBulkAndWait → results[].status/blob_id). The returning-user recovery flow matches the dashboard's actual isRecoveringExistingAccount / isNewAccount states in apps/app.
Measured where the UI is forward-looking. BEDU-661/665 sit in the "Walrus Console" project and describe some GA-timed UI. I described browse/renew at the capability level and cross-linked the concrete mechanics (recall, Blob extend, the existing delete guides) rather than inventing specific buttons. The guides target the MemWal dashboard (apps/app → memory.walrus.xyz).
Product-boundary check. Harbor (Seal-encrypted buckets) and Oyster (S3-compatible object storage) are sibling Walrus storage products, not Walrus Memory's console or storage layer, so their endpoints/terminology were intentionally not folded into these pages. If Walrus Memory's console or sign-in is meant to move under Harbor/Oyster, BEDU-665 (sign-in) and BEDU-661 (management UI) would need retargeting — worth a PM confirm before merge.
Style pass applied (US English, active voice, no em dashes / Latin abbreviations, "Seal" casing); docs.json validated and all internal links resolve.

🤖 Generated with Claude Code

https://claude.ai/code/session_016DHZxHQuhv7oxhnTs598fo

Generated by Claude Code

Add the lifecycle/console pages under the Walrus Memory docs spine: - Tracking Agent-Owned Blobs and Storage (fundamentals/architecture): object model for agent-owned blobs, a blob-lifecycle state diagram, three ways to discover what an agent owns, and expiry/renewal tracking. - Manage your memory (guides): browse/search by meaning, namespace organization, epoch renewal, deletion paths, and index rebuild. - Sign in as a returning user (guides): first-sign-in delegate-key recovery, restore-based memory rediscovery, the re-upload (no migration) expectation, and onchain wallet-visibility caveats. Wire all three into docs.json navigation. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016DHZxHQuhv7oxhnTs598fo

Remove the Mermaid state diagram; the lifecycle is covered by the prose steps that follow. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016DHZxHQuhv7oxhnTs598fo

jessiemongeon1 · 2026-07-22T17:24:08Z

Style Guide Audit

All 3 file(s) pass the style guide audit.

Style-guide word preference (may -> might) in the two lifecycle guides. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016DHZxHQuhv7oxhnTs598fo

Address review findings on the lifecycle/console guides: - restore().total is bounded by `limit` (default 10, newest-first) and is the number of blobs inspected in that call, not an authoritative count of the namespace. Reworded in tracking-agent-storage, manage-your-memory, and returning-user; point to an onchain query for an exact count. - The search index lives in the relayer's database (owner + namespace), not the browser. A returning user on a new device recalls existing memories as soon as they hold a delegate key; restore is for a lost/incomplete relayer index, not routine device switches. - Dashboard renewal is not shipped: frame epoch renewal as a storage-layer Blob extend today, with the one-click dashboard control noted as planned. Tie preview to the shipped delete panel and add the SDK recall path. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016DHZxHQuhv7oxhnTs598fo

reemsabawi-mystenlabs · 2026-07-22T19:36:57Z

Thanks — all three fixed in 4aa3430.

restore().total: reworded across the three pages to "blobs inspected in that call (bounded by limit, newest-first)," not an authoritative namespace count; readers are pointed to an onchain query or repeated restore for an exact count.
Index location: corrected — the index is the relayer's Postgres (owner + namespace), not browser-local. A returning user on a new device recalls immediately once they hold a delegate key; restore is now scoped to a lost/incomplete relayer index.
Dashboard UI: renewal reframed as a storage-layer Blob extend with the one-click control marked planned; preview tied to the shipped delete panel + the SDK recall path.

Generated by Claude Code

Second round of review fixes: - restore has no pagination cursor: a repeat call at the same limit re-inspects the same newest blobs and returns nothing new. Reworded the three pages to say rerun with a progressively higher limit, and explain why. - tracking-agent-storage no longer presents renewal as a shipped dashboard control; the one-click control is marked planned, storage-layer extend is the path today. - manage-your-memory no longer describes a dashboard memory-list/preview/ delete panel as shipped; it leads with the SDK recall path and defers the dashboard delete/preview flow to the existing Delete old memories guide. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016DHZxHQuhv7oxhnTs598fo

reemsabawi-mystenlabs · 2026-07-22T19:54:44Z

Fixed in b733024.

restore pagination: corrected — no pagination cursor, so a same-limit repeat re-inspects the same newest blobs and returns nothing new. All three pages now say to rerun with a progressively higher limit until restored stops increasing, and explain why.
dashboard UI: tracking-agent-storage marks the one-click renewal control as planned (storage-layer Blob extend today). manage-your-memory no longer describes a memory list/preview/delete panel as shipped — it leads with the SDK recall path and defers the dashboard delete/preview flow to the existing Delete old memories guide.

Generated by Claude Code

- Apply reviewer suggestions verbatim (intro, Blob-object sentence, renew paragraph, heading renames). - Bold table headers; number the subheadings under "Three ways..."; number the delete-options list. - Remove the now auto-generated Related links footers from all three pages. - Drop "this page"/"this guide" preambles for AEO/GEO. - Rename headings to be concise (Renew memories, Delete memories, Rebuild the index, Browse and search) and clarify two returning-user headings. - Title-case the guide page titles; convert "Before you begin" to a Prerequisites section with a list. - Tighten wordy sentences. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016DHZxHQuhv7oxhnTs598fo

- returning-user: rename the confusing "What your wallet reveals onchain" heading to "Onchain privacy" (the actual line-74 comment). - manage-your-memory: remove the redundant "Search by meaning" subheading and simplify the confusing browse intro (line-25 comment). - Convert the clear "X is <verb>ed by Y" passives to active voice across all three pages, per the style guide. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016DHZxHQuhv7oxhnTs598fo

Apply the audit bot's suggested active rephrasings in manage-your-memory: "the memory is gone" -> "disappears", "might be missing rows" -> "might lack rows", "blobs already indexed" -> "blobs the relayer already indexed". Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016DHZxHQuhv7oxhnTs598fo

claude added 2 commits July 22, 2026 16:25

docs: drop blob-lifecycle diagram from tracking-agent-storage

172d9e1

Remove the Mermaid state diagram; the lifecycle is covered by the prose steps that follow. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016DHZxHQuhv7oxhnTs598fo

claude added 2 commits July 22, 2026 18:32

docs: use 'might' not 'may' per style guide

d7b1158

Style-guide word preference (may -> might) in the two lifecycle guides. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016DHZxHQuhv7oxhnTs598fo

jessiemongeon1 requested changes Jul 22, 2026

View reviewed changes

jessiemongeon1 mentioned this pull request Jul 22, 2026

docs(style-guide): add rules from repeated PR feedback MystenLabs/sui#27413

Open

3 tasks

claude added 2 commits July 22, 2026 23:18

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: Walrus Memory lifecycle and console guides (BEDU-904)#486

docs: Walrus Memory lifecycle and console guides (BEDU-904)#486
reemsabawi-mystenlabs wants to merge 8 commits into
devfrom
claude/walrus-memory-docs-nq7pv8

reemsabawi-mystenlabs commented Jul 22, 2026

Uh oh!

jessiemongeon1 commented Jul 22, 2026 •

edited

Loading

Uh oh!

reemsabawi-mystenlabs commented Jul 22, 2026

Uh oh!

reemsabawi-mystenlabs commented Jul 22, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

reemsabawi-mystenlabs commented Jul 22, 2026

Summary

Notes for reviewers

Uh oh!

jessiemongeon1 commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Style Guide Audit

Uh oh!

reemsabawi-mystenlabs commented Jul 22, 2026

Uh oh!

reemsabawi-mystenlabs commented Jul 22, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jessiemongeon1 commented Jul 22, 2026 •

edited

Loading