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 條評論

登入 後參與評論

還沒有評論,來搶沙發~