walrus-memory

Walrus Memory

来源限制： 本技能的所有信息均来自 Walrus Memory 文档和 MystenLabs/MemWal 仓库。 扩展本技能时，只能使用这些来源。

Walrus Memory 基于 Walrus（去中心化存储）和 Sui（链上访问控制），为 AI Agent 提供持久、可移植的记忆。中继器（或手动流程中的客户端）使用 Seal 加密每条记忆，将其作为 blob 存储在 Walrus 上，并通过向量嵌入建立索引，以便进行语义搜索。所有者可控制谁能够读写，委托密钥则支持多个 Agent 共享访问。

常见集成错误：

1. 忘记生成账号 ID 和委托密钥。 SDK 运行前需要这两者。请在 memory.walrus.xyz 生成。
2. 未等待异步 remember 作业完成。 remember() 会立即返回作业 ID。上传将在后台运行。使用 waitForRememberJob() 或 rememberAndWait() 确认存储完成。
3. 未指定命名空间。 未指定时，所有内容都会存入 "default"。请为每个产品界面设置独立的命名空间，以隔离记忆。
4. 使用了错误的中继器 URL。 生产环境（主网）为 https://relayer.memory.walrus.xyz。预发布环境（测试网）为 https://relayer-staging.memory.walrus.xyz。

---

参考文件

ts-sdk — TypeScript SDK 参考

路径： ts-sdk.md 加载时机： 使用 @mysten-incubation/memwal 编写 TypeScript 代码，使用 MemWal、MemWalManual 或 withMemWal，调用 remember/recall/analyze/restore，或调试 SDK 错误时。 涵盖内容： 安装、三个入口（MemWal、MemWalManual、withMemWal）、配置、完整 API（remember、rememberAndWait、rememberBulk、带 RecallParams 的 recall、analyze、restore、health）、底层方法、账号管理、与 Vercel AI SDK 的 AI 中间件集成。

python-sdk — Python SDK 参考

路径： python-sdk.md 加载时机： 使用 PyPI 包 memwal 编写 Python 代码，使用 MemWal、MemWalSync 或 with_memwal_langchain/with_memwal_openai 中间件时。 涵盖内容： 安装、异步与同步客户端、env 预设（prod/staging）、RecallParams、ask 方法、LangChain 和 OpenAI 中间件、Colab 笔记本。

mcp — MCP 服务参考

路径： mcp.md 加载时机： 在 Cursor、Claude Desktop、Claude Code、Codex 或其他 MCP 客户端中设置 Walrus Memory 时。配置 memwal-mcp 包、调试登录/身份验证问题或使用 Streamable HTTP 传输时也适用。 涵盖内容： 通过 npx 安装、登录流程、客户端配置（Cursor、Claude Desktop、Claude Code、Codex）、八个 MCP 工具、需要身份验证的模式、默认命名空间、环境切换、Streamable HTTP 设置。

---

相关技能

主题	技能	加载时机
Walrus blob 存储	walrus-overview	了解 Walrus 本身
Seal 加密	walrus-data-security	了解 Seal 加密的底层工作方式
Sui Move 合约	sui-move	了解 MemWal Move 模块
故障排除	walrus-troubleshooting	了解常见 Walrus 错误消息

---

路由指南

任务	加载
在 TypeScript 应用中集成记忆	ts-sdk.md
在 Python 应用中集成记忆	python-sdk.md
为 Cursor / Claude / Codex 设置 MCP	mcp.md
了解 Walrus Memory 是什么	下方的技能内容
选择集成方式	下方的技能内容
管理账号和委托密钥	ts-sdk.md（账号管理部分）
自托管中继器	下方的技能内容 + 中继器文档
使用 AI 中间件（Vercel AI SDK）	ts-sdk.md（withMemWal 部分）
使用 AI 中间件（LangChain / OpenAI）	python-sdk.md

---

技能内容

核心概念

• 记忆空间。 隔离的存储单元，由 owner address + namespace + app ID (package ID) 唯一确定。一个空间中的记忆不会与其他空间混在一起。使用命名空间来区分不同用途（例如，personal、work、research）。

• 四项核心操作。

  • 记住 — 使用语义嵌入存储记忆。异步操作：立即返回作业 ID。
  • 回忆 — 通过自然语言查询搜索记忆。返回按余弦距离排序的匹配结果。
  • 分析 — 使用 LLM 从文本中提取结构化事实。每条事实都会作为独立记忆存储。
  • 提问 — 回忆 + LLM 推理。查询记忆并获取 AI 生成的回答。可通过 Python SDK、relayer HTTP API（POST /api/ask）使用，TypeScript SDK 尚未封装此功能。

• 所有者和委托方。 所有者是创建账户的 Sui 钱包。委托方是由所有者授予访问权限的 Ed25519 密钥对。委托方可以存储、回忆和解密，但不能管理密钥或转移所有权。访问权限由 Sui 上的 Move 智能合约强制执行。

• 加密。 relayer 会在所有记忆内容到达 Walrus 前使用 Seal 加密；在手动客户端流程中，则由客户端加密，因此 relayer 永远看不到明文。只有所有者和经授权的委托方可以解密。

• 忘记和删除。 POST /api/forget 会删除某个命名空间的向量索引行；加密的 Walrus blob 会保留，因此之后可以通过 restore 重新建立索引。对于永久删除 blob，启用了 Security Delete API 的部署提供了钱包认证流程，用于准备由赞助方支付的 Sui 删除交易；请参阅以编程方式删除记忆和仪表板指南删除旧记忆。

• Relayer。 后端服务（Rust + TypeScript sidecar），通过 REST API 处理嵌入、加密、Walrus 上传和向量搜索。托管的 relayer 由 Walrus Foundation 提供。你也可以自行托管。

• 恢复。 如果向量数据库丢失，恢复流程会从 Walrus 重建数据库：重新发现链上 blob、解密、重新嵌入并重新建立索引。Walrus 是永久的事实来源。

架构

Your App → SDK → Relayer → { Seal encrypt, Walrus upload, pgvector index }
                         ← { pgvector search, Walrus download, Seal decrypt }

六个组件：

1. SDK（TypeScript 或 Python）— 签署请求并调用 relayer
2. Relayer（Rust + TS sidecar）— 嵌入、加密、存储、搜索
3. 智能合约（Sui 上的 memwal::account）— 所有权、委托密钥、Seal 访问权限
4. 索引器 — 将合约事件同步到 PostgreSQL，以便快速查询
5. Walrus — 用于存储加密 blob 的去中心化存储
6. PostgreSQL + pgvector — 用于语义搜索的向量嵌入

选择集成方式

方式	适用场景
MemWal（默认 SDK）	适用于大多数团队。所有操作均由 relayer 处理。
MemWalManual	需要客户端加密。relayer 永远看不到明文。
withMemWal（AI 中间件）	使用 Vercel AI SDK，并希望自动回忆 + 自动保存。
Python SDK	适用于 Python 应用。使用相同的 relayer 和身份验证，并与 TypeScript API 保持一致。
MCP 服务	通过 MCP 工具为 Cursor/Claude/Codex 提供记忆功能。无需编写自定义代码。
自行托管的 relayer	完全控制信任边界。使用你自己的基础设施和凭据。

账户设置

1. 前往 memory.walrus.xyz（主网）或 staging.memory.walrus.xyz（测试网）
2. 连接你的 Sui 钱包
3. 创建 Walrus Memory 账户（每个 Sui 地址创建一个）
4. 生成委托密钥（Ed25519 密钥对）
5. 在 SDK 中使用 key（私钥十六进制字符串）和 accountId（Sui 对象 ID）

中继器端点

网络	中继器 URL	控制面板
生产环境（Mainnet）	https://relayer.memory.walrus.xyz	https://memory.walrus.xyz
预发布环境（Testnet）	https://relayer-staging.memory.walrus.xyz	https://staging.memory.walrus.xyz

合约 ID

网络	Package ID	Registry ID
Mainnet	0xcee7a6fd8de52ce645c38332bde23d4a30fd9426bc4681409733dd50958a24c6	0x0da982cefa26864ae834a8a0504b904233d49e20fcc17c373c8bed99c75a7edd
Testnet	0xcf6ad755a1cdff7217865c796778fabe5aa399cb0cf2eba986f4b582047229c6	0xe80f2feec1c139616a86c9f71210152e2a7ca552b20841f2e192f99f75864437

速率限制（托管中继器）

范围	限制
每个账户（突发）	60 点/分钟
每个账户（持续）	500 点/小时
每个委托密钥	30 点/分钟
存储配额	每个账户 1 GB

点数消耗：remember/bulk = 10，analyze = 5，remember = 5，restore / remember/manual = 3，ask = 2，其他所有操作（recall、recall/manual 等）= 1。

规则

1. 先生成账户 ID 和委托密钥。 SDK 必须有它们才能运行。请使用控制面板 memory.walrus.xyz。
2. 明确设置命名空间。 如果不设置，所有记忆都会进入 "default"。请按产品界面、环境或领域分别设置。
3. remember() 是异步的。 它会立即返回一个任务 ID。使用 rememberAndWait() 或轮询 waitForRememberJob()，以确认存储完成。
4. 为网络使用正确的中继器 URL。 Mainnet：relayer.memory.walrus.xyz。Testnet：relayer-staging.memory.walrus.xyz。
5. 委托密钥不是钱包。 它们是由所有者授权的 Ed25519 密钥对。它们可以存储和检索记忆，但无法管理账户。
6. 所有内容都会加密。 中继器默认使用 Seal 加密。如果不希望中继器看到明文，请使用 MemWalManual。
7. Walrus 是事实来源。 如果数据库丢失，restore() 会从 Walrus 重建数据库。数据库只是一个运行缓存。
8. 每个账户最多可有 20 个委托密钥。

常见错误

• 在调用 remember 后未等待就立即调用 recall。 记忆任务是异步的。请等待任务完成后再检索，否则记忆不会出现在结果中。
• 使用 remember 存储段落中的许多小事实。 请改用 analyze。它会提取单个事实并分别存储，从而实现更精确的检索。
• 硬编码中继器 URL，却未使其与网络匹配。 Mainnet 账户无法在预发布中继器上使用，反之亦然。
• 未关闭 Python 客户端。 完成后调用 await memwal.close()，以清理 HTTP 客户端。
• 在非交互式 shell 中运行 MCP 登录。 login 命令会打开浏览器。请在支持 TTY 的真实终端中运行，而不要在 IDE 的嵌入式终端中运行。
• 期望 restore() 一次处理所有 blob。 它有可配置的 limit（默认值：10）。恢复大型记忆空间时，请多次调用。