記憶工具

建構工具

記憶工具

記憶工具使 Claude 能夠通過記憶文件目錄在對話之間存儲和檢索信息。

記憶工具使 Claude 能夠通過記憶文件目錄在對話之間存儲和檢索信息。Claude 可以創建、讀取、更新和刪除在會話之間持久存在的文件，允許它隨著時間的推移建立知識，而無需將所有內容保留在上下文窗口中。

這是即時上下文檢索的關鍵原語：代替預先加載所有相關信息，代理將其學到的內容存儲在記憶中，並根據需要將其拉回。這使活動上下文專注於當前相關的內容，對於長期運行的工作流至關重要，其中一次加載所有內容會使上下文窗口不堪重負。有關更廣泛的模式，請參閱有效的上下文工程。

記憶工具在客戶端運行：您通過自己的基礎設施控制數據的存儲位置和方式。

通過反饋表單分享您對此功能的反饋。

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

用例

在多個代理執行中維護項目上下文
從過去的交互、決策和反饋中學習
隨著時間的推移構建知識庫
啟用跨對話學習，其中 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": "Here're the files and directories up to 2 levels deep in /memories, excluding hidden items and node_modules:\n4.0K\t/memories\n1.5K\t/memories/customer_service_guidelines.xml\n2.0K\t/memories/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": "Here's the content of /memories/customer_service_guidelines.xml with line numbers:\n     1\t<guidelines>\n     2\t<addressing_customers>\n     3\t- Always address customers by their first name\n     4\t- Use empathetic language\n..."
}

6. Claude 使用記憶來幫助：

"根據您的客戶服務指南，我可以幫助您起草回應。請分享工單詳情..."

有關模型支持，請參閱工具參考。

入門

要使用記憶工具：

將記憶工具添加到您的請求中
為記憶操作實現客戶端處理程序

要在您的應用程序中處理記憶工具操作，您需要為每個記憶命令實現處理程序。SDK 提供記憶工具幫助程序，可以處理工具界面。您可以子類化 BetaAbstractMemoryTool（Python）或使用 betaMemoryTool（TypeScript）來實現您自己的記憶後端（基於文件、數據庫、雲存儲、加密文件等）。

有關工作示例，請參閱：

Python：examples/memory/basic.py
TypeScript：examples/tools-helpers-memory.ts

基本用法

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": "I'm working on a Python web scraper that keeps crashing with a timeout error. Here's the problematic function:\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\nPlease help me debug this.",
        }
    ],
    tools=[{"type": "memory_20250818", "name": "memory"}],
)

print(message)

工具命令

您的客戶端實現需要處理這些記憶工具命令。雖然這些規範描述了 Claude 最熟悉的推薦行為，但您可以根據您的用例修改實現並根據需要返回字符串。

view

顯示目錄內容或文件內容，帶有可選的行範圍：

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

返回值

對於目錄： 返回一個列表，顯示文件和目錄及其大小：

Here're the files and directories up to 2 levels deep in {path}, excluding hidden items and node_modules:
{size}    {path}
{size}    {path}/{filename1}
{size}    {path}/{filename2}

列出最多 2 級深度的文件
顯示人類可讀的大小（例如，5.5K、1.2M）
排除隱藏項（以 . 開頭的文件）和 node_modules
在大小和路徑之間使用製表符

對於文件： 返回帶有標題和行號的文件內容：

Here's the content of {path} with line numbers:
{line_numbers}{tab}{content}

行號格式：

寬度：6 個字符，右對齐，用空格填充
分隔符：行號和內容之間的製表符
索引：1 索引（第一行是第 1 行）
行限制：超過 999,999 行的文件應返回錯誤："File {path} exceeds maximum line limit of 999,999 lines."

示例輸出：

Here's the content of /memories/notes.txt with line numbers:
     1	Hello World
     2	This is line two
    10	Line ten
   100	Line one hundred

錯誤處理

文件/目錄不存在："The path {path} does not exist. Please provide a valid path."

create

創建新文件：

{
  "command": "create",
  "path": "/memories/notes.txt",
  "file_text": "Meeting notes:\n- Discussed project timeline\n- Next steps defined\n"
}

返回值

成功："File created successfully at: {path}"

錯誤處理

文件已存在："Error: File {path} already exists"

str_replace

替換文件中的文本：

{
  "command": "str_replace",
  "path": "/memories/preferences.txt",
  "old_str": "Favorite color: blue",
  "new_str": "Favorite color: green"
}

返回值

成功："The memory file has been edited." 後跟編輯文件的片段，帶有行號

錯誤處理

文件不存在："Error: The path {path} does not exist. Please provide a valid path."
未找到文本："No replacement was performed, old_str `\{old_str}` did not appear verbatim in {path}."
重複文本：當 old_str 出現多次時，返回："No replacement was performed. Multiple occurrences of old_str `\{old_str}` in lines: {line_numbers}. Please ensure it is unique"

目錄處理

如果路徑是目錄，返回"文件不存在"錯誤。

insert

在特定行插入文本：

{
  "command": "insert",
  "path": "/memories/todo.txt",
  "insert_line": 2,
  "insert_text": "- Review memory tool documentation\n"
}

返回值

成功："The file {path} has been edited."

錯誤處理

文件不存在："Error: The path {path} does not exist"
無效的行號："Error: Invalid `insert_line` parameter: {insert_line}. It should be within the range of lines of the file: [0, {n_lines}]"

目錄處理

如果路徑是目錄，返回"文件不存在"錯誤。

delete

刪除文件或目錄：

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

返回值

成功："Successfully deleted {path}"

錯誤處理

文件/目錄不存在："Error: The path {path} does not exist"

目錄處理

遞歸刪除目錄及其所有內容。

rename

重命名或移動文件/目錄：

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

返回值

成功："Successfully renamed {old_path} to {new_path}"

錯誤處理

源不存在："Error: The path {old_path} does not exist"
目標已存在：返回錯誤（不覆蓋）："Error: The destination {new_path} already exists"

目錄處理

重命名目錄。

提示指導

啟用記憶工具時，此指令會自動包含在系統提示中：

IMPORTANT: ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE.
MEMORY PROTOCOL:
1. Use the `view` command of your `memory` tool to check for earlier progress.
2. ... (work on the task) ...
     - As you make progress, record status / progress / thoughts etc in your memory.
ASSUME INTERRUPTION: Your context window might be reset at any moment, so you risk losing any progress that is not recorded in your memory directory.

如果您觀察到 Claude 創建混亂的記憶文件，您可以包含此指令：

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

您也可以指導 Claude 寫入記憶的內容。例如："只在您的記憶系統中寫下與 <topic> 相關的信息。"

安全考慮

以下是實現記憶存儲時的重要安全問題：

敏感信息

Claude 通常會拒絕在記憶文件中寫下敏感信息。但是，您可能想實現更嚴格的驗證，以剝離潛在的敏感信息。

文件存儲大小

考慮跟蹤記憶文件大小，並防止文件增長過大。考慮添加記憶讀取命令可以返回的最大字符數，並讓 Claude 通過內容分頁。

記憶過期

考慮定期清除在較長時間內未被訪問的記憶文件。

路徑遍歷保護

惡意路徑輸入可能會嘗試訪問 /memories 目錄外的文件。您的實現必須驗證所有路徑以防止目錄遍歷攻擊。

考慮這些保護措施：

驗證所有路徑都以 /memories 開頭
將路徑解析為其規範形式，並驗證它們保持在記憶目錄內
拒絕包含 ../、..\ 或其他遍歷模式的路徑
監視 URL 編碼的遍歷序列（%2e%2e%2f）
使用您的語言的內置路徑安全實用程序（例如，Python 的 pathlib.Path.resolve() 和 relative_to()）

錯誤處理

記憶工具使用與文本編輯器工具類似的錯誤處理模式。有關詳細的錯誤消息和行為，請參閱上面的各個工具命令部分。常見錯誤包括文件未找到、權限錯誤、無效路徑和重複文本匹配。

上下文編輯集成

記憶工具與上下文編輯配對以管理長期運行的對話。有關詳情，請參閱上下文編輯。

與壓縮一起使用

記憶工具也可以與壓縮配對，它提供舊對話上下文的服務器端摘要。雖然上下文編輯在客戶端清除特定工具結果，但壓縮在服務器端自動摘要整個對話，當它接近上下文窗口限制時。

對於跨越多個代理會話的長期運行工作流，考慮同時使用兩者：壓縮使活動上下文可管理，無需客戶端記錄，記憶在壓縮邊界之間持久化重要信息，以便在摘要中不會丟失任何關鍵內容。

多會話軟件開發模式

對於跨越多個代理會話的長期運行軟件項目，記憶文件需要有意引導，而不是隨著工作進展而臨時寫入。下面的模式將記憶轉變為結構化恢復機制，因此每個新會話都可以從上一個會話停止的地方繼續。

工作原理

初始化會話： 第一個會話在任何實質性工作開始之前設置記憶工件。這包括進度日誌（跟蹤已完成的內容和接下來的內容）、功能清單（定義工作範圍）以及對項目需要的任何啟動或初始化腳本的引用。
後續會話： 每個新會話通過讀取這些記憶工件來打開。這在幾秒鐘內恢復項目的完整狀態，無需重新探索代碼庫或重新追蹤早期決策。
會話結束更新： 在會話結束之前，它使用已完成的內容和剩餘內容更新進度日誌。這確保下一個會話有準確的起點。

關鍵原則

一次處理一個功能。只有在端到端驗證確認其有效後才標記功能完成，而不是在代碼編寫後。這使進度日誌值得信賴，並防止範圍蔓延在會話中複合。

有關此模式實踐中的詳細案例研究，包括初始化腳本、進度文件結構和基於 git 的恢復，請參閱長期運行代理的有效工具。

後續步驟

查看所有工具

Anthropic 提供的工具及其屬性的目錄。

上下文編輯

與記憶一起管理對話長度。

Was this page helpful?

建構工具

記憶工具

記憶工具使 Claude 能夠通過記憶文件目錄在對話之間存儲和檢索信息。

記憶工具在客戶端運行：您通過自己的基礎設施控制數據的存儲位置和方式。

通過反饋表單分享您對此功能的反饋。

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

用例

在多個代理執行中維護項目上下文
從過去的交互、決策和反饋中學習
隨著時間的推移構建知識庫
啟用跨對話學習，其中 Claude 在重複工作流中改進

工作原理

示例：記憶工具調用如何工作

當您要求 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": "Here're the files and directories up to 2 levels deep in /memories, excluding hidden items and node_modules:\n4.0K\t/memories\n1.5K\t/memories/customer_service_guidelines.xml\n2.0K\t/memories/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": "Here's the content of /memories/customer_service_guidelines.xml with line numbers:\n     1\t<guidelines>\n     2\t<addressing_customers>\n     3\t- Always address customers by their first name\n     4\t- Use empathetic language\n..."
}

6. Claude 使用記憶來幫助：

"根據您的客戶服務指南，我可以幫助您起草回應。請分享工單詳情..."

有關模型支持，請參閱工具參考。

入門

要使用記憶工具：

將記憶工具添加到您的請求中
為記憶操作實現客戶端處理程序

有關工作示例，請參閱：

Python：examples/memory/basic.py
TypeScript：examples/tools-helpers-memory.ts

基本用法

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": "I'm working on a Python web scraper that keeps crashing with a timeout error. Here's the problematic function:\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\nPlease help me debug this.",
        }
    ],
    tools=[{"type": "memory_20250818", "name": "memory"}],
)

print(message)

工具命令

您的客戶端實現需要處理這些記憶工具命令。雖然這些規範描述了 Claude 最熟悉的推薦行為，但您可以根據您的用例修改實現並根據需要返回字符串。

view

顯示目錄內容或文件內容，帶有可選的行範圍：

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

返回值

對於目錄： 返回一個列表，顯示文件和目錄及其大小：

Here're the files and directories up to 2 levels deep in {path}, excluding hidden items and node_modules:
{size}    {path}
{size}    {path}/{filename1}
{size}    {path}/{filename2}

列出最多 2 級深度的文件
顯示人類可讀的大小（例如，5.5K、1.2M）
排除隱藏項（以 . 開頭的文件）和 node_modules
在大小和路徑之間使用製表符

對於文件： 返回帶有標題和行號的文件內容：

Here's the content of {path} with line numbers:
{line_numbers}{tab}{content}

行號格式：

寬度：6 個字符，右對齐，用空格填充
分隔符：行號和內容之間的製表符
索引：1 索引（第一行是第 1 行）
行限制：超過 999,999 行的文件應返回錯誤："File {path} exceeds maximum line limit of 999,999 lines."

示例輸出：

Here's the content of /memories/notes.txt with line numbers:
     1	Hello World
     2	This is line two
    10	Line ten
   100	Line one hundred

錯誤處理

文件/目錄不存在："The path {path} does not exist. Please provide a valid path."

create

創建新文件：

{
  "command": "create",
  "path": "/memories/notes.txt",
  "file_text": "Meeting notes:\n- Discussed project timeline\n- Next steps defined\n"
}

返回值

成功："File created successfully at: {path}"

錯誤處理

文件已存在："Error: File {path} already exists"

str_replace

替換文件中的文本：

{
  "command": "str_replace",
  "path": "/memories/preferences.txt",
  "old_str": "Favorite color: blue",
  "new_str": "Favorite color: green"
}

返回值

成功："The memory file has been edited." 後跟編輯文件的片段，帶有行號

錯誤處理

文件不存在："Error: The path {path} does not exist. Please provide a valid path."
未找到文本："No replacement was performed, old_str `\{old_str}` did not appear verbatim in {path}."
重複文本：當 old_str 出現多次時，返回："No replacement was performed. Multiple occurrences of old_str `\{old_str}` in lines: {line_numbers}. Please ensure it is unique"

目錄處理

如果路徑是目錄，返回"文件不存在"錯誤。

insert

在特定行插入文本：

{
  "command": "insert",
  "path": "/memories/todo.txt",
  "insert_line": 2,
  "insert_text": "- Review memory tool documentation\n"
}

返回值

成功："The file {path} has been edited."

錯誤處理

文件不存在："Error: The path {path} does not exist"
無效的行號："Error: Invalid `insert_line` parameter: {insert_line}. It should be within the range of lines of the file: [0, {n_lines}]"

目錄處理

如果路徑是目錄，返回"文件不存在"錯誤。

delete

刪除文件或目錄：

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

返回值

成功："Successfully deleted {path}"

錯誤處理

文件/目錄不存在："Error: The path {path} does not exist"

目錄處理

遞歸刪除目錄及其所有內容。

rename

重命名或移動文件/目錄：

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

返回值

成功："Successfully renamed {old_path} to {new_path}"

錯誤處理

源不存在："Error: The path {old_path} does not exist"
目標已存在：返回錯誤（不覆蓋）："Error: The destination {new_path} already exists"

目錄處理

重命名目錄。

提示指導

啟用記憶工具時，此指令會自動包含在系統提示中：

IMPORTANT: ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE.
MEMORY PROTOCOL:
1. Use the `view` command of your `memory` tool to check for earlier progress.
2. ... (work on the task) ...
     - As you make progress, record status / progress / thoughts etc in your memory.
ASSUME INTERRUPTION: Your context window might be reset at any moment, so you risk losing any progress that is not recorded in your memory directory.

如果您觀察到 Claude 創建混亂的記憶文件，您可以包含此指令：

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

您也可以指導 Claude 寫入記憶的內容。例如："只在您的記憶系統中寫下與 <topic> 相關的信息。"

安全考慮

以下是實現記憶存儲時的重要安全問題：

敏感信息

Claude 通常會拒絕在記憶文件中寫下敏感信息。但是，您可能想實現更嚴格的驗證，以剝離潛在的敏感信息。

文件存儲大小

考慮跟蹤記憶文件大小，並防止文件增長過大。考慮添加記憶讀取命令可以返回的最大字符數，並讓 Claude 通過內容分頁。

記憶過期

考慮定期清除在較長時間內未被訪問的記憶文件。

路徑遍歷保護

惡意路徑輸入可能會嘗試訪問 /memories 目錄外的文件。您的實現必須驗證所有路徑以防止目錄遍歷攻擊。

考慮這些保護措施：

驗證所有路徑都以 /memories 開頭
將路徑解析為其規範形式，並驗證它們保持在記憶目錄內
拒絕包含 ../、..\ 或其他遍歷模式的路徑
監視 URL 編碼的遍歷序列（%2e%2e%2f）
使用您的語言的內置路徑安全實用程序（例如，Python 的 pathlib.Path.resolve() 和 relative_to()）

錯誤處理

上下文編輯集成

記憶工具與上下文編輯配對以管理長期運行的對話。有關詳情，請參閱上下文編輯。

與壓縮一起使用

多會話軟件開發模式

工作原理

初始化會話： 第一個會話在任何實質性工作開始之前設置記憶工件。這包括進度日誌（跟蹤已完成的內容和接下來的內容）、功能清單（定義工作範圍）以及對項目需要的任何啟動或初始化腳本的引用。
後續會話： 每個新會話通過讀取這些記憶工件來打開。這在幾秒鐘內恢復項目的完整狀態，無需重新探索代碼庫或重新追蹤早期決策。
會話結束更新： 在會話結束之前，它使用已完成的內容和剩餘內容更新進度日誌。這確保下一個會話有準確的起點。

關鍵原則

一次處理一個功能。只有在端到端驗證確認其有效後才標記功能完成，而不是在代碼編寫後。這使進度日誌值得信賴，並防止範圍蔓延在會話中複合。

有關此模式實踐中的詳細案例研究，包括初始化腳本、進度文件結構和基於 git 的恢復，請參閱長期運行代理的有效工具。

後續步驟

查看所有工具

Anthropic 提供的工具及其屬性的目錄。

上下文編輯

與記憶一起管理對話長度。

Was this page helpful?