記憶工具

記憶工具讓 Claude 能夠透過記憶檔案目錄在對話間儲存和檢索資訊。Claude 可以建立、讀取、更新和刪除在會話間持續存在的檔案，讓它能夠隨時間建立知識，而無需將所有內容保留在上下文視窗中。

記憶工具在客戶端運作——您可以透過自己的基礎設施控制資料的儲存位置和方式。

使用案例

• 在多個代理執行間維護專案上下文
• 從過去的互動、決策和回饋中學習
• 隨時間建立知識庫
• 啟用跨對話學習，讓 Claude 在重複工作流程中改進

運作方式

啟用後，Claude 會在開始任務前自動檢查其記憶目錄。Claude 可以在 /memories 目錄中建立、讀取、更新和刪除檔案，以儲存它在工作時學到的內容，然後在未來的對話中參考這些記憶，以更有效地處理類似任務或從中斷處繼續。

由於這是一個客戶端工具，Claude 會進行工具呼叫來執行記憶操作，而您的應用程式會在本地執行這些操作。這讓您完全控制記憶的儲存位置和方式。為了安全起見，您應該將所有記憶操作限制在 /memories 目錄中。

範例：記憶工具呼叫的運作方式

當您請求 Claude 協助處理任務時，Claude 會自動先檢查其記憶目錄。以下是典型互動的樣子：

1. 使用者請求：

"幫我回應這張客戶服務工單。"

2. Claude 檢查記憶目錄：

"我會幫您回應客戶服務工單。讓我檢查我的記憶以了解任何先前的上下文。"

Claude 呼叫記憶工具：

{
  "type": "tool_use",
  "id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories"
  }
}

3. 您的應用程式回傳目錄內容：

{
  "type": "tool_result",
  "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": "Directory: /memories\n- customer_service_guidelines.xml\n- refund_policies.xml"
}

4. Claude 讀取相關檔案：

{
  "type": "tool_use",
  "id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories/customer_service_guidelines.xml"
  }
}

5. 您的應用程式回傳檔案內容：

{
  "type": "tool_result",
  "tool_use_id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "content": "<guidelines>\n<addressing_customers>\n- Always address customers by their first name\n- Use empathetic language\n..."
}

6. Claude 使用記憶來協助：

"根據您的客戶服務指引，我可以幫您撰寫回應。請分享工單詳情..."

支援的模型

記憶工具可用於：

• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)

開始使用

要使用記憶工具：

1. 在您的 API 請求中包含測試標頭 context-management-2025-06-27
2. 將記憶工具新增到您的請求中
3. 實作記憶操作的客戶端處理器

基本用法

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-sonnet-4-5",
        "max_tokens": 2048,
        "messages": [
            {
                "role": "user",
                "content": "我正在開發一個 Python 網頁爬蟲，但它一直因為逾時錯誤而崩潰。這是有問題的函數：\n\n```python\ndef fetch_page(url, retries=3):\n    for i in range(retries):\n        try:\n            response = requests.get(url, timeout=5)\n            return response.text\n        except requests.exceptions.Timeout:\n            if i == retries - 1:\n                raise\n            time.sleep(1)\n```\n\n請幫我除錯這個問題。"
            }
        ],
        "tools": [{
            "type": "memory_20250818",
            "name": "memory"
        }]
    }'

工具命令

您的客戶端實作需要處理這些記憶工具命令：

view

顯示目錄內容或檔案內容，可選擇特定行範圍：

{
  "command": "view",
  "path": "/memories",
  "view_range": [1, 10]  // 可選：檢視特定行
}

create

建立或覆寫檔案：

{
  "command": "create",
  "path": "/memories/notes.txt",
  "file_text": "會議記錄：\n- 討論專案時程\n- 定義下一步\n"
}

str_replace

替換檔案中的文字：

{
  "command": "str_replace",
  "path": "/memories/preferences.txt",
  "old_str": "喜愛顏色：藍色",
  "new_str": "喜愛顏色：綠色"
}

insert

在特定行插入文字：

{
  "command": "insert",
  "path": "/memories/todo.txt",
  "insert_line": 2,
  "insert_text": "- 檢閱記憶工具文件\n"
}

delete

刪除檔案或目錄：

{
  "command": "delete",
  "path": "/memories/old_file.txt"
}

rename

重新命名或移動檔案/目錄：

{
  "command": "rename",
  "old_path": "/memories/draft.txt",
  "new_path": "/memories/final.txt"
}

提示指引

當包含記憶工具時，我們會自動將此指令加入系統提示：

重要：在做任何其他事情之前，請務必檢視您的記憶目錄。
記憶協定：
1. 使用您的 `memory` 工具的 `view` 命令檢查先前的進度。
2. ...（處理任務）...
     - 在您取得進展時，將狀態/進度/想法等記錄在您的記憶中。
假設中斷：您的上下文視窗可能隨時重設，因此您有失去未記錄在記憶目錄中的任何進度的風險。

如果您觀察到 Claude 建立雜亂的記憶檔案，您可以包含此指令：

注意：編輯記憶資料夾時，請始終保持其內容的最新、連貫和有組織。您可以重新命名或刪除不再相關的檔案。除非必要，否則不要建立新檔案。

您也可以指導 Claude 寫入記憶的內容，例如：「只在您的記憶系統中記錄與<主題>相關的資訊。」

安全考量

以下是實作記憶儲存時的重要安全考量：

敏感資訊

Claude 通常會拒絕在記憶檔案中寫下敏感資訊。然而，您可能想要實作更嚴格的驗證，以過濾掉潛在的敏感資訊。

檔案儲存大小

考慮追蹤記憶檔案大小，並防止檔案變得過大。考慮為記憶讀取命令可以回傳的最大字元數設定限制，並讓 Claude 分頁瀏覽內容。

記憶過期

考慮定期清除長時間未存取的記憶檔案。

路徑遍歷保護

考慮這些安全措施：

• 驗證所有路徑都以 /memories 開頭
• 將路徑解析為其標準形式，並驗證它們仍在記憶目錄內
• 拒絕包含 ../、..\\ 或其他遍歷模式的路徑
• 注意 URL 編碼的遍歷序列（%2e%2e%2f）
• 使用您語言的內建路徑安全工具（例如 Python 的 pathlib.Path.resolve() 和 relative_to()）

錯誤處理

記憶工具使用與文字編輯器工具相同的錯誤處理模式。常見錯誤包括找不到檔案、權限錯誤和無效路徑。

與上下文編輯一起使用

記憶工具可以與上下文編輯結合使用，當對話上下文超過配置的閾值時，會自動清除舊的工具結果。這種組合能夠實現長時間運行的代理工作流程，否則會超過上下文限制。

它們如何協同工作

當啟用上下文編輯且您的對話接近清除閾值時，Claude 會自動收到警告通知。這會提示 Claude 在這些結果從上下文視窗中清除之前，將工具結果中的任何重要資訊保存到記憶檔案中。

工具結果清除後，Claude 可以在需要時從記憶檔案中檢索儲存的資訊，有效地將記憶視為其工作上下文的延伸。這讓 Claude 能夠：

• 繼續複雜的多步驟工作流程而不會失去關鍵資訊
• 即使在工具結果被移除後也能參考過去的工作和決策
• 在超過典型上下文限制的對話中維持連貫的上下文
• 隨時間建立知識庫，同時保持活躍上下文視窗的可管理性

範例工作流程

考慮一個有許多檔案操作的程式碼重構專案：

1. Claude 對檔案進行大量編輯，產生許多工具結果
2. 隨著上下文增長並接近您的閾值，Claude 收到警告
3. Claude 將到目前為止所做的變更總結到記憶檔案中（例如 /memories/refactoring_progress.xml）
4. 上下文編輯自動清除較舊的工具結果
5. Claude 繼續工作，在需要回憶已完成的變更時參考記憶檔案
6. 工作流程可以無限期地繼續，Claude 管理活躍上下文和持久記憶

配置

要同時使用兩個功能：

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=4096,
    messages=[...],
    tools=[
        {
            "type": "memory_20250818",
            "name": "memory"
        },
        # 您的其他工具
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {
                    "type": "input_tokens",
                    "value": 100000
                },
                "keep": {
                    "type": "tool_uses",
                    "value": 3
                }
            }
        ]
    }
)

您也可以排除記憶工具呼叫被清除，以確保 Claude 始終能夠存取最近的記憶操作：

context_management={
    "edits": [
        {
            "type": "clear_tool_uses_20250919",
            "exclude_tools": ["memory"]
        }
    ]
}