Claude API Memory Tool(记忆工具)怎么用:跨会话文件存取、目录约定与客户端实现步骤

想让自建智能体关掉窗口再打开时还能记住用户偏好与上次进度?本文按官方 Memory tool 文档,讲清 memory_20250818 工具类型、/memories 虚拟目录约定、六大文件操作子命令与防路径穿越实现步骤。

NNathaniel bigo··原创首发·AI 辅助撰写
11 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 其他 账号

结论先说

  1. 文件系统隐喻 + 客户端自有存储:启用 memory_20250818 工具后,Claude 会把 /memories 当成它的专属长期笔记本进行读写,而底层到底存成本地文件、PostgreSQL 记录还是云端对象存储,完全由你的后端代码决定。
  2. 开局自动先查记忆,无需手写冗长提示词:只要挂载了该工具,服务端会自动向模型注入标准系统指引,让它在处理任务前先检查 /memories 目录有没有历史记录,并在习得关键偏好或阶段性结论时主动更新文件。
  3. 内置六个标准子命令:客户端只需按约定实现 view、create、str_replace、insert、delete 和 rename 六个分支,并通过 tool_result 返回文本反馈。
  4. 安全第一条是防目录穿越:客户端必须强制校验所有目标路径落在当前用户的隔离 /memories 根目录内,拦截一切 .. 或符号链接跳出行为。
  5. 国内免卡开通与账号服务入口:自有账号免上号自助开通可见本站 Claude Pro 充值页 与 Claude Max 充值页;缺可用账号或遇身份核验可查看 Claude 注册说明 与 Claude KYC 认证协助。

Memory Tool 跨会话文件记忆四步

图:本站根据 Claude 官方文档:Memory tool 整理的示意图

本文根据 Claude 开发者平台官方文档《Memory tool》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Anthropic 官方网站。

适用于谁

  • 搜「claude api memory tool」「memory_20250818 怎么用」,想给自研客服、助理或研发智能体加上跨会话长期记忆的开发者;
  • 不想一上来就搭一套笨重的向量检索(RAG)管线,希望让模型像记 Markdown 笔记一样自己增删改查结构化记忆的人;
  • 需要把用户记忆完全留在自有数据库或内网存储里以满足数据合规要求的团队。

如果你只是在 claude.ai 网页版里使用官方现成的个人对话记忆功能,请直接看 /guides/claude-memory。

一、最小请求写法与 /memories 目录约定

在 Messages API 请求里挂载记忆工具非常简洁,type 填 memory_20250818,name 固定填 memory(若搭配服务端上下文管理策略使用,可在 SDK 的 betas 参数中一并带上 context-management-2025-06-27):

python
import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=2048,
    tools=[
        {
            "type": "memory_20250818",
            "name": "memory",
        }
    ],
    messages=[
        {"role": "user", "content": "继续帮我跟进上周的接口重构方案,记得按我习惯的测试框架写。"}
    ],
    betas=["context-management-2025-06-27"],
)

for block in response.content:
    if block.type == "tool_use" and block.name == "memory":
        print(block.input)

发出这条请求后,模型第一反应通常是产出一个 tool_use 块:{"command": "view", "path": "/memories"}。

这里的 /memories 是模型视角下的逻辑虚拟根目录,绝不是让你真的去写宿主服务器操作系统的根分区 /memories。在多用户 Web 应用里,标准做法是在后端把它映射成 ./storage/users/{user_id}/memories/ 或数据库里的 (user_id, virtual_path, content) 行记录。对模型而言它始终在操作干净的 /memories/preferences.md,而不同租户的数据在物理层彻底隔离。

二、客户端六个子命令的实现规格

和普通工具调用一样(基础循环见 /guides/claude-tool-use-basics),收到 name == "memory" 的调用后,你的后端需要根据 input["command"] 分发处理并返回纯文本结果:

子命令关键输入参数客户端应执行的动作与返回格式
viewpath、可选 view_range若是目录,列出其下文件名与子目录;若是文件,返回带行号的文件内容(支持按起止行号截取)
createpath、file_text在指定虚拟路径新建或覆盖记忆文件,成功后返回创建确认提示
str_replacepath、old_str、new_str在目标记忆文件中查找唯一匹配的 old_str 并替换为 new_str;匹配不到或多处匹配时返回 is_error: True
insertpath、insert_line、new_str在第 insert_line 行之后插入新段落(0 表示插在首行前)
deletepath删除已过期的单个记忆文件或子目录,防止旧结论干扰后续任务
renameold_path、new_path重命名或移动记忆文件,便于模型整理目录分类

如果你想让模型只记某几类特定信息(例如「只记客户的编码规范与数据库连接约定,不记闲聊」),可以在请求的 system 提示词里补充两句业务层面的记录准则,它会与内置的 /memories 操作习惯叠加生效。

三、路径安全校验与防污染清单

Memory Tool 客户端安全与目录约定清单

图:本站根据 Claude 官方文档:Memory tool 整理的示意图

因为记忆文件一旦写入就会在未来的新会话里被模型自动读回,官方文档特别提醒开发者在客户端做好四道防护:

  1. 严格校验虚拟前缀与真实路径:先检查传入的 path(以及 rename 里的 old_path 和 new_path)是否以 /memories 开头;拼成宿主机物理路径后再调 Path.resolve(),确认解析后的绝对路径确实位于该用户专属目录之下,直接拒绝 ../、URL 编码 %2e%2e 和软链接越界:
python
from pathlib import Path

def resolve_safe_memory_path(user_root: Path, virtual_path: str) -> Path:
    if not virtual_path.startswith("/memories"):
        raise ValueError("Path must start with /memories")
    rel = virtual_path[len("/memories"):].lstrip("/")
    target = (user_root / rel).resolve()
    root_resolved = user_root.resolve()
    if target != root_resolved and root_resolved not in target.parents:
        raise ValueError("Path traversal blocked")
    return target
  1. 设单文件体积与总配额上限:限制单个记忆文件不超过几十 KB、每个用户目录总大小受控,避免异常循环把大段原始日志原封不动塞进 /memories;
  2. 防范跨会话提示词注入固化:如果智能体同时接入了联网抓取(见 /guides/claude-api-web-search-tool)或读取不受信任的外部邮件,恶意页面可能诱导模型把违规指令写进记忆文件长期潜伏。建议在前端给用户提供「查看并编辑记忆文件」的透明面板;
  3. 现成开发框架选型:如果你是围绕本地代码仓库做开发辅助,其实无需自己实现这套存储层——官方命令行工具已经内置了项目指令与自动记忆机制(详见 /guides/claude-code-getting-started),日常个人开发直接搭配 Claude Pro 订阅 或 Claude Code 充值方案 即可开箱使用。

常见问题

问:用了 Memory Tool 之后,当前会话的上下文窗口会自动变小吗?

答:不会直接缩小当前轮次的对话历史。记忆工具解决的是「把关键结论安全存到会话外部」以及「跨会话复用」;想把当前长对话里已经读完的旧工具输出清掉省 token,需要配合 Context Editing(上下文编辑)一起使用。

问:底层不想写磁盘文件,存在关系型数据库里可以吗?

答:完全可以。Claude 只关心发出的 view、create、str_replace 等命令能不能收到符合文件目录逻辑的文本响应,后端用数据库表模拟路径树反而更方便做多实例横向扩容与备份。

问:为什么有时新开对话模型没有读取某个子文件夹里的笔记?

答:模型开局通常先 view 顶层 /memories 目录列表,再挑文件名相关的打开细读。建议通过系统提示词引导模型起直观的文件名(如 api_conventions.md),或维护一份简短的 /memories/index.md 索引。

问:人在国内没有外币信用卡,怎么订阅或升级 Claude 付费套餐?

答:可在本站 AI 会员充值总览页 选择 Claude Pro 自助充值 或 Claude Max 充值,付款后即时发卡密、24 小时自助兑换且可开具增值税发票;实时价格与售后边界(含封号不质保)以商品页当天展示为准。

相关教程

参考资料

  • Claude 开发者平台文档:Memory tool — https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool

Nathaniel 的更多内容

  1. 01

    独立开发者用 ChatGPT + Codex 跑通产品全流程:市场验证、PRD、原型到代码上线复盘清单

    单人做独立产品最容易陷入「闭门写两个月代码上线零用户」或「AI 写到一半目录越改越崩」。本文整理「ChatGPT 负责市场验证、PRD 与复盘 + Codex 负责工程实现与测试」的五阶段双轨流程,附起手提示词与 7 项上线复盘清单。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成规范文件命名规则、整理混乱目录树与合并零散发票抬头清单脚本

    面对满桌面的「新建文件夹」「最终版2」和上百张零散电子发票,手工改名抄台账耗时又容易漏重。本文分享先脱敏取样、再用 ChatGPT 生成带预演和回滚日志的本地 Python 脚本,离线安全完成目录整理与发票抬头合并去重的实战流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外邮件营销(EDM)受众分层文案、A/B 主题行测试与防进垃圾箱自检

    做海外独立站或出海 SaaS 邮件营销(EDM),最怕千人一面群发被直接送进垃圾箱。本文结合 Gmail/Yahoo 批量发件人规范,梳理用 ChatGPT 设计受众分层文案、批量生成 A/B 主题行矩阵并开展发前垃圾词与合规自检的实战提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写 Notion Formula 2.0 公式、Obsidian Dataview 查询与 Airtable 自动化脚本

    给 Notion 数据库写多条件 Formula 2.0 公式、给 Obsidian 写 Dataview 动态看板,或在 Airtable 里写自动化脚本,经常因为一个小括号或类型不匹配报错半天。本文整理三大工具的通用上下文喂料规范与三套直接可复制的生成提示词。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 处理复杂 JSON / YAML / XML 字段映射、格式转换与校验规则编写实战

    对接第三方 API、迁移 Kubernetes 配置或解析政企 XML 报文时,手工对照几百行嵌套字段既慢又容易漏掉空值与类型边界。本文整理用 ChatGPT 完成字段映射表梳理、生成确定性转换脚本以及编写 JSON Schema / Pydantic / XSD 校验规则的实战流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 准备本科/硕士毕业论文答辩:提炼答辩 PPT 结构、模拟导师犀利追问与 3 分钟自述稿

    毕业论文写完后,要在 3–5 分钟内讲清研究价值并顶住答辩评委的连环追问并不轻松。本文整理在严格遵守高校学术规范的前提下,用 ChatGPT 提炼答辩 PPT 结构、打磨 3 分钟口语自述稿并开展模拟导师犀利追问的排练流程与提示词。

    ChatGPT0

同产品的其他教程

  1. 01

    Anthropic Contextual Retrieval(上下文增强检索)是什么、怎么实现:给文档块自动补背景摘要结合缓存降失误率

    长文档切成小块后丢了公司名、年份和主语指代导致 RAG 频频搜错?本文按 Anthropic 官方技术文章详解 Contextual Retrieval 原理、官方公开评测失误率下降 49% 至 67% 的组合架构,以及用 Claude 提示词缓存低成本批量生成切片背景的完整 Python 代码。

    Claude其他 AI 工具0
  2. 02

    RAG 知识库回答不准怎么调优:切片大小(Chunking)、BM25 + 向量混合检索与 Rerank 重排序三步排查法

    搭好的 RAG 企业知识库一问具体型号、报错码或跨行表格就答非所问?本文按 OpenAI 与 Anthropic 官方检索文档,给出先隔离检索与生成故障、再按结构化切片(Chunking)、BM25 加向量混合召回(RRF)与 Rerank 重排序逐层调优的三步法。

    Claude其他 AI 工具0
  3. 03

    Langfuse 开源本地部署(Docker Compose)与提示词版本管理(Prompt Management)从零上手教程

    企业内网严禁业务日志出境,又想免费拥有大模型调用链追踪与不发版热更新提示词的能力?本文按 Langfuse 官方文档整理 Docker Compose 本地一键启动(含 ClickHouse 架构注意事项)、密钥配置与 Prompt Management 标签化版本管理全流程。

    Claude其他 AI 工具0
  4. 04

    LangSmith 入门教程:给 LangGraph 与原生 OpenAI / Claude 接口加调用链追踪、Token 成本统计与免费层限额

    智能体多步调用总是找不到哪一轮提示词跑偏、单次请求到底烧了多少 Token?本文按 LangSmith 官方文档讲清环境变量零侵入接入 LangGraph、用 wrap_openai / wrap_anthropic 与 @traceable 追踪原生接口,以及 Developer 免费层额度与留存规则。

    Claude其他 AI 工具0
  5. 05

    Zotero 搭配 Claude / ChatGPT 高效读英文文献:PDF 翻译插件、批注导出精读与防捏造参考文献流程

    在 Zotero 里读英文顶会论文怎么无缝联动 Claude 与 ChatGPT?本文整理 Translate for Zotero 划词翻译配置、高亮批注导出精读提示词,以及杜绝 AI 捏造假 DOI 参考文献的核验闭环。

    Claude其他 AI 工具0
  6. 06

    Obsidian 接入 Claude、ChatGPT 与本地 Ollama 做个人双链笔记问答:主流插件配置与隐私脱敏边界

    想在 Obsidian 里基于自己的双链笔记库做 AI 问答又担心隐私外泄?本文对比 Copilot 与 Smart Connections 插件,整理接入 Claude、OpenAI 官方 API 与本地 Ollama 的步骤及敏感目录隔离规则。

    Claude其他 AI 工具0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~