Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.memwal.ai/llms.txt

Use this file to discover all available pages before exploring further.

This page explains what @mysten-incubation/memwal-mcp actually does on the client machine.

​
Runtime modes

The package has two main runtime modes.

​
Auth-required mode

This mode runs when:
  • the package was launched by an MCP host such as Cursor, Claude Desktop, Claude Code, Codex, or Antigravity
  • ~/.memwal/credentials.json does not exist yet
Instead of exiting, the package starts a minimal MCP server that:
  • responds to initialize
  • advertises the normal MemWal memory tools
  • also advertises memwal_login
  • returns an actionable error for the memory tools until sign-in completes
That is intentional. It avoids the bad UX where the MCP host only shows a vague server-start failure and gives the user no recovery path.

​
Bridged mode

This mode runs after credentials exist. The package:
  • loads the saved delegate key + account metadata from ~/.memwal/credentials.json
  • opens an authenticated SSE bridge to the relayer
  • forwards stdio MCP traffic from the local client to the relayer
  • intercepts memwal_login and memwal_logout locally instead of forwarding them upstream

​
First-run flow

​
Credential file

The package stores credentials here: 
~/.memwal/credentials.json
It contains:
  • delegate private key
  • delegate public key
  • delegate address
  • wallet address
  • MemWal account ID
  • package ID
  • relayer URL
  • label
  • creation timestamp
The file is written with restrictive permissions (0600) on supported systems.
The delegate private key in this file is a sensitive long-lived credential. Treat it like an API key. Do not commit it, do not share it in screenshots, and do not paste it into public MCP configs.

​
Local-only tools

These tools are handled locally by the package:
  • memwal_login
  • memwal_logout
They do not round-trip to the relayer. That matters because login needs to open a browser on the client machine, and logout should only remove local credentials without mutating server state.

​
Why login returns a URL instead of waiting

memwal_login is intentionally designed to return a click-able URL quickly instead of blocking until wallet approval finishes. That design avoids a few common MCP-host failure modes:
  • tool-call timeouts while the user approves in wallet
  • browser tabs opening in the background
  • agents paraphrasing a timeout error and dropping the actual login URL
The local listener stays alive in the background for up to 5 minutes. After the browser flow completes, the next MemWal tool call picks up the saved credentials automatically.

​
Remote memory tools

These tools go through the relayer:
  • memwal_remember
  • memwal_recall
  • memwal_analyze
  • memwal_restore
Those requests hit the same relayer-backed MemWal stack used by direct SDK clients:
  • embeddings
  • SEAL encryption and decryption
  • Walrus storage
  • relayer-side indexing and retrieval

​
stdio package vs Streamable HTTP

​
stdio package

Use the package when your MCP host expects a local command: 
{
  "mcpServers": {
    "memwal": {
      "command": "npx",
      "args": ["-y", "@mysten-incubation/memwal-mcp"]
    }
  }
}
This is the path that supports inline memwal_login. In bridged mode, the package also:
  • opens an authenticated SSE session to the relayer
  • forwards stdio MCP requests upstream
  • splices memwal_login and memwal_logout into tools/list
  • transparently reconnects if the SSE session drops

​
Streamable HTTP

Use HTTP transport when the MCP host can connect directly to a remote MCP URL and attach headers. The typical endpoint is: 
https://relayer.memwal.ai/api/mcp
with request headers:
  • Authorization: Bearer <delegatePrivateKey>
  • x-memwal-account-id: <accountId>
This is a different surface from the local stdio package. The auth and session flow are not identical.

​
Safety decisions in the runtime

Some runtime behavior is opinionated on purpose:
  • 401 does not auto-delete credentials: a relayer 401 is surfaced loudly, but the local credentials file is left untouched so transient proxy, WAF, or local-network issues do not wipe the user’s saved delegate key
  • --relayer override is transient-only: if a saved credentials file points at one relayer and the current process passes another --relayer, the override applies only to that process and does not silently rewrite the saved file
  • Login callback is loopback-only: the browser callback listener binds to 127.0.0.1, checks the request Origin, validates the Host, and compares a one-time state token before writing credentials

​
Environment presets

The package supports presets that set both relayer and dashboard URLs together:
  • --prod
  • --dev
  • --staging
  • --local
This matters because login should open the dashboard that matches the relayer environment. For example, --dev should route the user to the dev dashboard and save dev relayer credentials, not silently fall back to prod.

​
What logout does and does not do

memwal_logout or --logout:
  • deletes ~/.memwal/credentials.json
  • removes local access from this machine
It does not:
  • revoke the on-chain delegate key
  • remove the delegate from the MemWal dashboard
If you need full revocation, remove the delegate key from the dashboard too.

​
Why docs say “retry the tool call”

memwal_login returns a click-able URL quickly and lets the browser flow finish in the background. That avoids MCP tool-call timeouts when:
  • the user takes time to approve in wallet
  • the browser tab is not focused immediately
  • the wallet requires extra review or hardware confirmation
Once the browser shows the connection succeeded, the next MemWal tool call picks up the saved credentials.