Memory Tool 原理

Memory 是 HyperAI Relay 最重要的一块差异化,也是我花最多时间打磨的一块。这篇文档讲它到底是什么、跟 claude.ai 的 Memory 有什么区别、为什么我们永远免费。

什么是 Memory Tool

Anthropic 在 2025 年 8 月发布了一个 client-side tool 规范,类型名叫 memory_20250818。它不是一个自动运行的功能,而是一组由客户端实现的文件系统操作,Claude 会在需要时主动调用:

命令 含义
view 查看 /memories 目录或某个文件的内容
create 创建一个新 memory 文件(路径 + 内容)
str_replace 对已有文件做字符串替换(精确编辑)
insert 在指定行号插入新内容
delete 删除文件或目录

Anthropic 只定义了协议,不提供后端存储。客户端(通常就是 SDK 用户)自己决定这些文件存哪里。

HyperAI Relay 做的事:在我们的 gateway 里实现了一整套 memory tool 后端,存储用 PostgreSQL,每条 memory 绑定你的 user_id,跨会话自动生效。你调任何客户端(Cursor / Claude Code / API),只要请求里带了 memory_20250818 tool,都走同一份数据。

跟 claude.ai 的 Memory 有什么区别

Anthropic 官方的 claude.ai 也有 Memory,但那是完全不同的一个系统:

维度 claude.ai Memory HyperAI Relay Memory
你能看到每条内容吗? 只能看到"它记住了这些大概" 每一条都能精确看到原文
你能删除单条吗? 只能整体清空 单条删除
你能编辑吗? 不能 str_replace / insert 精确编辑
你能导出吗? 不能 一键导出 JSON
协议开放吗? 黑盒,只在 claude.ai web 里 标准 memory_20250818,任何 SDK 都能用
跨客户端共享吗? 只在 claude.ai Cursor / Claude Code / API / MCP 全共享
数据所有权 在 Anthropic 在你,导出后可以带到任何地方

一句话总结:claude.ai 的 Memory 是"让 Claude 更懂你"的 UX 糖;HyperAI Relay 的 Memory 是"让你真正拥有记忆数据"的基础设施。

为什么我们把 Memory 做白盒

四个长期护城河机制(摘自内部路线图,用户视角):

# 机制 对你的意义
1 数量积累 Memory 随时间单调增长,存的越久越有价值。我们在 UI 上把"已记住 N 条 · 已陪伴 M 天"做成勋章
2 语义结构 Claude 基于你的 Memory 形成的理解是有机的,不可机械复现;即使把 JSON 搬到别的平台,那边的模型也要重新"磨合"
3 工作流锁定 Memory 可以按项目分组(/memories/project-X/),每个项目是一条独立工作链
4 摩擦导出 我们给完整的导出能力,但不对齐任何竞品格式 —— 数据可以带走,生态粘合要用户自己做

这四点的核心认知是:数据可携带是原则,生态不兼容是事实。我们给你最大的所有权,同时信任自己的工程质量能让你留下来。

为什么 Memory 永远免费

这是很多人会疑惑的:"你们做了这么多 Memory 功能,不应该做 Pro 功能卖吗?"

不。原因很简单:

  1. Memory 是所有用户的护城河,不是 Pro 的卖点。把它藏在付费墙后等于自己拆护城河。
  2. Pro Plan 卖的是 quota 和隔离,不是功能。标准版 50MB,Pro 版 500MB —— 区别只有"能存多大",功能完全一致。
  3. 诚实派:我们的定价哲学是"不藏 feature,只卖确定性",详见 诚实派定价哲学。

所以:

  • 注册后就能用全套 Memory 功能
  • /app/memories 浏览 / 删除 / 导出都是免费的
  • /try 沙盒里甚至不登录就能体验 Memory
  • 只有当你的 Memory 真的撑爆 50MB,才需要考虑 Pro Plan

怎么开始用

最小代码示例(Python + 官方 SDK):

from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.hyper-ailab.com",
    api_key="sk-relay-xxx",
)

msg = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    tools=[{"type": "memory_20250818", "name": "memory"}],
    messages=[
        {"role": "user", "content": "请先 view 一下 /memories,看看我之前存过什么"},
    ],
)

第一次调用 /memories 目录是空的(或者只有 /try 带过来的数据)。你正常聊天,告诉 Claude 一些关于你的事情:项目上下文、技术栈、口味偏好、待办事项。它会自主决定要不要调 create 把这些存下来。

下次打开任何客户端 —— 只要带同一个 API Key、带同一套 tools=[{"type": "memory_20250818", ...}],Claude 就会自动从 /memories 读取,表现出"认识你"的感觉。

最快的体验路径:访问 /try,不登录、不装任何东西,直接在浏览器里跟 Claude 聊 5 分钟,然后刷新页面 —— 你会亲眼看到它记住的东西。

常见误解

误解 1:"Memory 会自动存所有对话" 错。Claude 只在它主动判断需要时才调 memory tool,不是每句话都存。这是设计决定,不是 bug —— 自动存会让 Memory 迅速膨胀到噪声。如果你希望强制它存某件事,直接告诉它:"记住:X"。

误解 2:"Memory 就是长上下文 window" 不是。长上下文 window 是单次请求里塞很多 token,成本和 token 用量线性增长。Memory 是跨会话的持久化存储,只在 Claude 调用 view 时消耗 token 去读,不读就没消耗。

误解 3:"Memory 会被其他用户看到" 绝对不会。Memory 的存储按 user_id 硬隔离,gateway 在每次请求时强制注入你的 user_id 作为 scope。admin 甚至都不能看 Memory 内容(只能看 size_bytes 统计)。详见 Memory 面板与配额 的隐私章节。

下一步