---
title: Инструмент памяти
url: https://platform.claude.com/docs/ru/agents-and-tools/tool-use/memory-tool
description: Позвольте Claude сохранять и извлекать информацию между разговорами, реализовав файловые операции инструмента памяти в вашем приложении.
---
Инструмент памяти (memory tool) позволяет Claude сохранять и извлекать информацию между разговорами в каталоге файлов памяти. Claude может создавать, читать, обновлять и удалять файлы, которые сохраняются между сессиями, накапливая знания со временем без необходимости держать всё в «context window» (контекстном окне).
Память поддерживает извлечение контекста по требованию (just-in-time). Вместо того чтобы загружать всю релевантную информацию заранее, агент записывает то, что узнаёт, в файлы памяти и считывает их обратно по мере необходимости. Это позволяет сосредоточить активный контекст на текущей задаче, что важно для длительных сессий, которые в противном случае переполнили бы контекстное окно. Более общий паттерн описан в статье [Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents).
Инструмент памяти работает на стороне клиента: Claude запрашивает файловые операции, а ваше приложение их выполняет. Вы контролируете, где и как хранятся данные, с помощью собственной инфраструктуры.
Воспользуйтесь [формой обратной связи](https://forms.gle/YXC2EKGMhjN1c4L88), чтобы поделиться своим мнением об этой функции.
Чтобы узнать, как «zero data retention» (нулевое хранение данных), или ZDR, применяется к этой функции, см. раздел [API и хранение данных](https://platform.claude.com/docs/ru/manage-claude/api-and-data-retention).
## Сценарии использования
* Поддержание контекста проекта на протяжении нескольких сессий агента
* Применение уроков из прошлых взаимодействий, решений и обратной связи к новым задачам
* Постепенное накопление базы знаний
## Как это работает
Когда инструмент памяти включён, Claude автоматически проверяет свой каталог памяти перед началом задачи. В процессе работы Claude сохраняет то, что узнаёт, в файлах в каталоге `/memories` и считывает их в последующих разговорах, чтобы продолжить начатую ранее работу.
Поскольку инструмент памяти работает на стороне клиента, Claude лишь запрашивает операции с памятью. Ваше приложение выполняет каждый запрос в хранилище, которое вы контролируете, и возвращает результат в блоке `tool_result` (см. [Обработка вызовов инструментов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/handle-tool-calls)). Путь `/memories` — это префикс, который ваш обработчик отображает на реальное хранилище, например каталог для каждого пользователя или ключи в базе данных. Память полностью находится в вашем приложении. Последующий разговор продолжается с той же памятью, если он отправляет ту же запись `tools`, а ваш обработчик обслуживает то же хранилище. В целях безопасности ограничьте все операции с памятью каталогом `/memories` (см. [Защита от обхода путей](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/memory-tool#path-traversal-protection)).
### Пример: как работают вызовы инструмента памяти
Типичное взаимодействие выглядит так:
**1. Запрос пользователя:**
```text wrap
"Help me respond to this customer service ticket."
```
**2. Claude проверяет каталог памяти:**
```text wrap
"I'll help you respond to the customer service ticket. Let me check my memory for any previous context."
```
Claude вызывает инструмент памяти:
```json
{
"type": "tool_use",
"id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
"name": "memory",
"input": {
"command": "view",
"path": "/memories"
}
}
```
**3. Ваше приложение возвращает содержимое каталога:**
```json
{
"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 читает релевантные файлы:**
```json
{
"type": "tool_use",
"id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
"name": "memory",
"input": {
"command": "view",
"path": "/memories/customer_service_guidelines.xml"
}
}
```
**5. Ваше приложение возвращает содержимое файла:**
```json
{
"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\n 2\t\n 3\t- Always address customers by their first name\n 4\t- Use empathetic language\n..."
}
```
**6. Claude использует память, чтобы помочь:**
```text wrap
"Based on your customer service guidelines, I can help you craft a response. Please share the ticket details..."
```
Инструмент памяти доступен во всех моделях Claude 4 и более поздних. Полный список инструментов, предоставляемых Anthropic, см. в [Справочнике по инструментам](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-reference).
## Начало работы
Использование инструмента памяти состоит из двух шагов:
1. Добавьте инструмент памяти в ваш запрос. Запись `tools` `{"type": "memory_20250818", "name": "memory"}` — это вся конфигурация: `name` должно быть `memory`, и вы не определяете входную схему для инструмента, предоставляемого Anthropic.
2. Реализуйте клиентский обработчик для каждой команды памяти. Ваш обработчик должен отклонять пути за пределами `/memories`, поэтому прочитайте раздел [Защита от обхода путей](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/memory-tool#path-traversal-protection), прежде чем его писать.
## Базовое использование
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 2048,
"messages": [
{
"role": "user",
"content": "Help me respond to this customer service ticket."
}
],
"tools": [{
"type": "memory_20250818",
"name": "memory"
}]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 2048
tools:
- type: memory_20250818
name: memory
messages:
- role: user
content: Help me respond to this customer service ticket.
YAML
```
```python Python
client = anthropic.Anthropic()
message = client.messages.create(
model="claude-opus-5-5",
max_tokens=2048,
messages=[
{
"role": "user",
"content": "Help me respond to this customer service ticket.",
}
],
tools=[{"type": "memory_20250818", "name": "memory"}],
)
print(message)
```
```typescript TypeScript
const anthropic = new Anthropic();
const message = await anthropic.messages.create({
model: "claude-opus-5-5",
max_tokens: 2048,
messages: [
{
role: "user",
content: "Help me respond to this customer service ticket."
}
],
tools: [{ type: "memory_20250818", name: "memory" }]
});
console.log(message);
```
```csharp C#
var client = new AnthropicClient();
var message = await client.Messages.Create(
new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 2048,
Messages =
[
new()
{
Role = Role.User,
Content = "Help me respond to this customer service ticket.",
},
],
Tools = [new MemoryTool20250818()],
}
);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
message, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 2048,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Help me respond to this customer service ticket.")),
},
Tools: []anthropic.ToolUnionParam{
{OfMemoryTool20250818: &anthropic.MemoryTool20250818Param{}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(message)
```
```java Java
import com.anthropic.models.messages.MemoryTool20250818;
// ...
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(2048L)
.addTool(MemoryTool20250818.builder().build())
.addUserMessage("Help me respond to this customer service ticket.")
.build();
Message message = client.messages().create(params);
IO.println(message);
```
```php PHP
$client = new Client();
$message = $client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 2048,
messages: [
[
'role' => 'user',
'content' => 'Help me respond to this customer service ticket.',
],
],
tools: [new MemoryTool20250818],
);
echo $message;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 2048,
messages: [
{
role: "user",
content: "Help me respond to this customer service ticket."
}
],
tools: [
{
type: "memory_20250818",
name: "memory"
}
]
)
puts message
```
## Реализация обработчика памяти
Ответ Claude на запрос, подобный предыдущему, заканчивается блоком `tool_use`, который запрашивает операцию с памятью, например `view /memories`. Ваше приложение выполняет операцию и возвращает результат в блоке `tool_result`, а затем отправляет разговор обратно, чтобы Claude мог продолжить: это стандартный [цикл использования инструментов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/handle-tool-calls).
Четыре SDK предоставляют вспомогательные средства для инструмента памяти, которые берут на себя интерфейс инструмента и цикл. Создайте подкласс `BetaAbstractMemoryTool` (Python и C#), используйте `betaMemoryTool` (TypeScript) или реализуйте `BetaMemoryToolHandler` (Java), чтобы хранить память в собственном хранилище, например в файлах на диске, базе данных, облачном хранилище или зашифрованных файлах. Python и TypeScript также включают готовую реализацию на основе локальной файловой системы — `BetaLocalFilesystemMemoryTool`. Вспомогательные средства и «tool runner» (исполнитель инструментов) находятся в бета-пространстве имён вашего SDK, хотя сам инструмент памяти не требует бета-заголовка. В SDK для Go и Ruby нет вспомогательного средства для памяти, поэтому эти примеры сами выполняют цикл использования инструментов, а PHP оборачивает замыкание вашего обработчика в свой универсальный `BetaRunnableTool`. Все три используют хранилище в оперативной памяти, которое вы заменяете собственным хранилищем.
```python Python
import anthropic
from anthropic.tools import BetaLocalFilesystemMemoryTool
client = anthropic.Anthropic()
memory = BetaLocalFilesystemMemoryTool(base_path="./memory")
runner = client.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Remember that customer Acme Corp prefers email follow-ups.",
}
],
tools=[memory],
)
final_message = runner.until_done()
print(final_message.content)
```
```typescript TypeScript
import Anthropic from "@anthropic-ai/sdk";
import { betaMemoryTool } from "@anthropic-ai/sdk/helpers/beta/memory";
import { BetaLocalFilesystemMemoryTool } from "@anthropic-ai/sdk/tools/memory/node";
const client = new Anthropic();
const backend = await BetaLocalFilesystemMemoryTool.init("./memory");
const memory = betaMemoryTool(backend); // or pass your own handlers object
const runner = client.beta.messages.toolRunner({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [
{
role: "user",
content: "Remember that customer Acme Corp prefers email follow-ups."
}
],
tools: [memory],
max_iterations: 10
});
const finalMessage = await runner;
console.log(finalMessage.content);
```
```csharp C#
using Anthropic;
using Anthropic.Helpers.Beta;
using Anthropic.Models.Beta.Messages;
var client = new AnthropicClient();
// Ваш подкласс BetaAbstractMemoryTool
var memory = new FilesystemMemoryTool("./memories");
var runner = client.Beta.Messages.ToolRunner(
new MessageCreateParams
{
Model = Anthropic.Models.Messages.Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages =
[
new()
{
Role = Role.User,
Content = "Remember that customer Acme Corp prefers email follow-ups.",
},
],
},
[memory],
maxIterations: 10
);
var finalMessage = await runner.RunUntilDoneAsync();
Console.WriteLine(finalMessage);
```
```go Go
package main
import (
"context"
"encoding/json"
"fmt"
"log"
"slices"
"sort"
"strings"
"github.com/anthropics/anthropic-sdk-go"
)
// Хранилище в памяти, сопоставляющее пути к файлам памяти с их содержимым.
// В рабочей среде используйте собственное хранилище.
var store = map[string]string{}
type memoryCommand struct {
Command string `json:"command"`
Path string `json:"path"`
FileText string `json:"file_text"`
OldStr string `json:"old_str"`
NewStr string `json:"new_str"`
InsertLine int `json:"insert_line"`
InsertText string `json:"insert_text"`
OldPath string `json:"old_path"`
NewPath string `json:"new_path"`
}
func executeMemory(raw json.RawMessage) string {
var cmd memoryCommand
if err := json.Unmarshal(raw, &cmd); err != nil {
return "Error: invalid memory command"
}
switch cmd.Command {
case "view":
if content, ok := store[cmd.Path]; ok {
lines := strings.Split(strings.TrimSuffix(content, "\n"), "\n")
for i, line := range lines {
lines[i] = fmt.Sprintf("%6d\t%s", i+1, line)
}
return fmt.Sprintf("Here's the content of %s with line numbers:\n%s", cmd.Path, strings.Join(lines, "\n"))
}
if cmd.Path == "/memories" {
listing := []string{"1.0K\t/memories"}
for path := range store {
listing = append(listing, "1.0K\t"+path)
}
sort.Strings(listing[1:])
return fmt.Sprintf("Here're the files and directories up to 2 levels deep in %s, excluding hidden items and node_modules:\n%s", cmd.Path, strings.Join(listing, "\n"))
}
return fmt.Sprintf("The path %s does not exist. Please provide a valid path.", cmd.Path)
case "create":
store[cmd.Path] = cmd.FileText
return "File created successfully at: " + cmd.Path
case "str_replace":
content, ok := store[cmd.Path]
if !ok || !strings.Contains(content, cmd.OldStr) {
return fmt.Sprintf("No replacement was performed, old_str `%s` did not appear verbatim in %s.", cmd.OldStr, cmd.Path)
}
store[cmd.Path] = strings.Replace(content, cmd.OldStr, cmd.NewStr, 1)
return "The memory file has been edited."
case "insert":
content, ok := store[cmd.Path]
if !ok {
return fmt.Sprintf("Error: The path %s does not exist", cmd.Path)
}
lines := strings.Split(content, "\n")
if cmd.InsertLine < 0 || cmd.InsertLine > len(lines) {
return fmt.Sprintf("Error: Invalid `insert_line` parameter: %d. It should be within the range of lines of the file: [0, %d]", cmd.InsertLine, len(lines))
}
lines = slices.Insert(lines, cmd.InsertLine, strings.TrimSuffix(cmd.InsertText, "\n"))
store[cmd.Path] = strings.Join(lines, "\n")
return fmt.Sprintf("The file %s has been edited.", cmd.Path)
case "delete":
if _, ok := store[cmd.Path]; !ok {
return fmt.Sprintf("Error: The path %s does not exist", cmd.Path)
}
delete(store, cmd.Path)
return "Successfully deleted " + cmd.Path
case "rename":
if _, ok := store[cmd.OldPath]; !ok {
return fmt.Sprintf("Error: The path %s does not exist", cmd.OldPath)
}
if _, ok := store[cmd.NewPath]; ok {
return fmt.Sprintf("Error: The destination %s already exists", cmd.NewPath)
}
store[cmd.NewPath] = store[cmd.OldPath]
delete(store, cmd.OldPath)
return fmt.Sprintf("Successfully renamed %s to %s", cmd.OldPath, cmd.NewPath)
default:
return "Error: unknown command " + cmd.Command
}
}
func main() {
client := anthropic.NewClient()
tools := []anthropic.ToolUnionParam{{OfMemoryTool20250818: &anthropic.MemoryTool20250818Param{}}}
messages := []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Remember that customer Acme Corp prefers email follow-ups.")),
}
for {
message, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: messages,
Tools: tools,
})
if err != nil {
log.Fatal(err)
}
if message.StopReason != anthropic.StopReasonToolUse {
for _, block := range message.Content {
if block.Type == "text" {
fmt.Println(block.Text)
}
}
break
}
results := []anthropic.ContentBlockParamUnion{}
for _, block := range message.Content {
if block.Type == "tool_use" {
results = append(results, anthropic.NewToolResultBlock(block.ID, executeMemory(block.Input), false))
}
}
messages = append(messages, message.ToParam(), anthropic.NewUserMessage(results...))
}
}
```
```java Java
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.helpers.BetaMemoryToolHandler;
import com.anthropic.helpers.BetaToolRunner;
import com.anthropic.models.beta.messages.BetaMemoryTool20250818;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.MessageCreateParams; // beta package, not models.messages
import com.anthropic.models.beta.messages.ToolRunnerCreateParams;
import com.anthropic.models.messages.Model;
import java.nio.file.Path;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Ваша реализация BetaMemoryToolHandler для шести команд памяти
BetaMemoryToolHandler handler = new FileSystemMemoryToolHandler(Path.of("memories"));
MessageCreateParams createParams = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addTool(BetaMemoryTool20250818.builder().build())
.addUserMessage("Remember that customer Acme Corp prefers email follow-ups.")
.build();
ToolRunnerCreateParams runnerParams = ToolRunnerCreateParams.builder()
.betaMemoryToolHandler(handler)
.initialMessageParams(createParams)
.maxIterations(10)
.build();
BetaToolRunner runner = client.beta().messages().toolRunner(runnerParams);
for (BetaMessage message : runner) {
IO.println(message);
}
}
```
```php PHP
$line) {
$numbered[] = sprintf("%6d\t%s", $i + 1, $line);
}
return "Here's the content of {$path} with line numbers:\n" . implode("\n", $numbered);
}
if ($path === '/memories') {
$listing = ["1.0K\t/memories"];
foreach (array_keys($store) as $stored) {
$listing[] = "1.0K\t{$stored}";
}
return "Here're the files and directories up to 2 levels deep in {$path}, excluding hidden items and node_modules:\n" . implode("\n", $listing);
}
return "The path {$path} does not exist. Please provide a valid path.";
case 'create':
$store[$path] = $input['file_text'];
return "File created successfully at: {$path}";
case 'str_replace':
$position = strpos($store[$path] ?? '', $input['old_str']);
if ($position === false) {
return "No replacement was performed, old_str `{$input['old_str']}` did not appear verbatim in {$path}.";
}
$store[$path] = substr_replace($store[$path], $input['new_str'] ?? '', $position, strlen($input['old_str']));
return 'The memory file has been edited.';
case 'insert':
if (!isset($store[$path])) {
return "Error: The path {$path} does not exist";
}
$lines = explode("\n", $store[$path]);
if ($input['insert_line'] < 0 || $input['insert_line'] > count($lines)) {
return "Error: Invalid `insert_line` parameter: {$input['insert_line']}. It should be within the range of lines of the file: [0, " . count($lines) . "]";
}
array_splice($lines, $input['insert_line'], 0, [preg_replace('/\n\z/', '', $input['insert_text'])]);
$store[$path] = implode("\n", $lines);
return "The file {$path} has been edited.";
case 'delete':
if (!isset($store[$path])) {
return "Error: The path {$path} does not exist";
}
unset($store[$path]);
return "Successfully deleted {$path}";
case 'rename':
if (!isset($store[$input['old_path']])) {
return "Error: The path {$input['old_path']} does not exist";
}
if (isset($store[$input['new_path']])) {
return "Error: The destination {$input['new_path']} already exists";
}
$store[$input['new_path']] = $store[$input['old_path']];
unset($store[$input['old_path']]);
return "Successfully renamed {$input['old_path']} to {$input['new_path']}";
default:
return "Error: unknown command {$input['command']}";
}
},
);
$runner = $client->beta->messages->toolRunner(
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'Remember that customer Acme Corp prefers email follow-ups.']],
model: Model::CLAUDE_OPUS_5_5,
tools: [$memory],
maxIterations: 10,
);
$finalMessage = $runner->runUntilDone();
print_r($finalMessage->content);
```
```ruby Ruby
require "anthropic"
client = Anthropic::Client.new
TOOLS = [{type: "memory_20250818", name: "memory"}].freeze
# Хранилище в оперативной памяти, сопоставляющее пути к файлам памяти с их содержимым.
# В рабочей среде используйте собственное хранилище.
STORE = {}
def execute_memory(input)
path = input[:path]
case input[:command]
when "view"
if STORE.key?(path)
lines = STORE[path].chomp.split("\n", -1)
lines = [""] if lines.empty?
numbered = lines.each_with_index.map { |line, i| format("%6d\t%s", i + 1, line) }
"Here's the content of #{path} with line numbers:\n#{numbered.join("\n")}"
elsif path == "/memories"
listing = ["1.0K\t/memories"] + STORE.keys.map { |stored| "1.0K\t#{stored}" }
"Here're the files and directories up to 2 levels deep in #{path}, excluding hidden items and node_modules:\n#{listing.join("\n")}"
else
"The path #{path} does not exist. Please provide a valid path."
end
when "create"
STORE[path] = input[:file_text]
"File created successfully at: #{path}"
when "str_replace"
unless STORE.key?(path) && STORE[path].include?(input[:old_str])
return "No replacement was performed, old_str `#{input[:old_str]}` did not appear verbatim in #{path}."
end
STORE[path] = STORE[path].sub(input[:old_str]) { input[:new_str].to_s }
"The memory file has been edited."
when "insert"
return "Error: The path #{path} does not exist" unless STORE.key?(path)
lines = STORE[path].split("\n", -1)
lines = [""] if lines.empty?
if input[:insert_line] < 0 || input[:insert_line] > lines.length
return "Error: Invalid `insert_line` parameter: #{input[:insert_line]}. It should be within the range of lines of the file: [0, #{lines.length}]"
end
lines.insert(input[:insert_line], input[:insert_text].chomp)
STORE[path] = lines.join("\n")
"The file #{path} has been edited."
when "delete"
return "Error: The path #{path} does not exist" unless STORE.key?(path)
STORE.delete(path)
"Successfully deleted #{path}"
when "rename"
return "Error: The path #{input[:old_path]} does not exist" unless STORE.key?(input[:old_path])
return "Error: The destination #{input[:new_path]} already exists" if STORE.key?(input[:new_path])
STORE[input[:new_path]] = STORE.delete(input[:old_path])
"Successfully renamed #{input[:old_path]} to #{input[:new_path]}"
else
"Error: unknown command #{input[:command]}"
end
end
messages = [{role: "user", content: "Remember that customer Acme Corp prefers email follow-ups."}]
loop do
message = client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
messages: messages,
tools: TOOLS
)
unless message.stop_reason == :tool_use
puts message.content
break
end
tool_results = message.content.filter_map do |block|
next unless block.type == :tool_use
{type: "tool_result", tool_use_id: block.id, content: execute_memory(block.input)}
end
messages << {role: "assistant", content: message.content} << {role: "user", content: tool_results}
end
```
Хранилища в оперативной памяти в примерах для Go, PHP и Ruby делают их самодостаточными: каждое из них выполняет диспетчеризацию по полю `command` в `input` блока `tool_use` и возвращает строки, описанные в разделе [Команды инструмента](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/memory-tool#tool-commands). Обработчику для продакшена также нужна [проверка путей](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/memory-tool#path-traversal-protection), которую эти демонстрационные хранилища пропускают. Полные примеры из самих SDK см. здесь:
* Python: [examples/memory/basic.py](https://github.com/anthropics/anthropic-sdk-python/blob/main/examples/memory/basic.py)
* TypeScript: [examples/tools-helpers-memory.ts](https://github.com/anthropics/anthropic-sdk-typescript/blob/main/examples/tools-helpers-memory.ts)
* C#: [MemoryToolExample](https://github.com/anthropics/anthropic-sdk-csharp/tree/main/examples/MemoryToolExample)
* Java: [BetaMemoryToolExample.java](https://github.com/anthropics/anthropic-sdk-java/blob/main/anthropic-java-example/src/main/java/com/anthropic/example/BetaMemoryToolExample.java)
## Команды инструмента
Ваша клиентская реализация должна обрабатывать следующие команды. Эти спецификации описывают рекомендуемое поведение и возвращаемые строки: Claude читает любой текст, содержащийся в результате вашего инструмента, поэтому вы можете возвращать другие строки, если это нужно вашему приложению.
### view
Показывает содержимое каталога или содержимое файла с необязательными диапазонами строк:
```json
{
"command": "view",
"path": "/memories/notes.txt",
"view_range": [1, 10]
}
```
`view_range` необязателен и применяется к просмотру текстовых файлов: `[start_line, end_line]` возвращает эти строки, а `[start_line, -1]` возвращает всё от `start_line` до конца файла.
#### Возвращаемые значения
**Для каталогов:** Верните список, показывающий файлы и каталоги с их размерами:
```text
Here're the files and directories up to 2 levels deep in {path}, excluding hidden items and node_modules:
{size}\t{path}
{size}\t{path}/{filename1}
{size}\t{path}/{filename2}
```
* Перечисляет файлы до 2 уровней вложенности
* Показывает размеры в удобочитаемом виде (например, `5.5K`, `1.2M`)
* Исключает скрытые элементы (файлы, начинающиеся с `.`) и `node_modules`
* Использует символ табуляции между размером и путём
Первый `view` каталога `/memories` в пустом хранилище не является ошибкой. Если в вашем SDK есть инструмент памяти для локальной файловой системы (`BetaLocalFilesystemMemoryTool`), он создаёт корневой каталог памяти до первого вызова Claude и возвращает заголовок списка, за которым следует одна строка с размером и путём для самого пустого каталога.
**Для файлов:** Верните содержимое файла с заголовком и номерами строк:
```text wrap
Here's the content of {path} with line numbers:
{line_numbers}{tab}{content}
```
Форматирование номеров строк:
* **Ширина:** 6 символов, выравнивание по правому краю с заполнением пробелами
* **Разделитель:** Символ табуляции между номером строки и содержимым
* **Индексация:** С единицы (первая строка — строка 1)
* **Лимит строк:** Для файлов с более чем 999 999 строками следует возвращать ошибку: `"File {path} exceeds maximum line limit of 999,999 lines."`
**Пример вывода:**
```text
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
```
В описании инструмента для Claude также сказано, что `view` отображает файлы изображений (`.jpg`, `.jpeg` и `.png`) и усекает текстовое представление файлов длиннее 16 000 символов. Ожидайте вызовов `view` для путей к изображениям и последующих просмотров длинных файлов по диапазонам.
#### Обработка ошибок
* **Файл или каталог не существует:** `"The path {path} does not exist. Please provide a valid path."`
### create
Создаёт новый файл:
```json
{
"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"`
В описании инструмента для Claude сказано, что `create` «создаёт или перезаписывает» файл, поэтому ожидайте вызовов `create` для уже существующих путей. Возврат ошибки — это эталонное поведение, а перезапись вместо этого — допустимый вариант реализации.
### str\_replace
Заменяет текст в файле:
```json
{
"command": "str_replace",
"path": "/memories/preferences.txt",
"old_str": "Favorite color: blue",
"new_str": "Favorite color: green"
}
```
`new_str` необязателен для `str_replace`: если он опущен, `old_str` удаляется без замены.
#### Возвращаемые значения
* **Успех:** `"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
Вставляет текст в определённую строку:
```json
{
"command": "insert",
"path": "/memories/todo.txt",
"insert_line": 2,
"insert_text": "- Review memory tool documentation\n"
}
```
`insert_text` вставляется после строки `insert_line`, а `0` вставляет в начало файла.
#### Возвращаемые значения
* **Успех:** `"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
Удаляет файл или каталог:
```json
{
"command": "delete",
"path": "/memories/old_file.txt"
}
```
#### Возвращаемые значения
* **Успех:** `"Successfully deleted {path}"`
#### Обработка ошибок
* **Файл или каталог не существует:** `"Error: The path {path} does not exist"`
#### Обработка каталогов
Рекурсивно удаляет каталог и всё его содержимое. Описание инструмента сообщает Claude, что он не может удалить сам каталог `/memories`, поэтому отклоняйте `delete`, путь которого является корнем памяти.
### rename
Переименовывает или перемещает файл или каталог:
```json
{
"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"`
#### Обработка каталогов
Переименовывает каталог. Описание инструмента сообщает Claude, что он не может переименовать сам каталог `/memories`, поэтому отклоняйте `rename`, у которого `old_path` является корнем памяти.
## Рекомендации по подсказкам
Когда инструмент памяти присутствует в `tools` вашего запроса, API автоматически добавляет эту инструкцию в «system prompt» (системную подсказку). Вам не нужно отправлять её самостоятельно:
```text wrap
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 всё же создаёт беспорядочные файлы памяти, вы можете усилить это в своей подсказке:
```text wrap
Note: when editing your memory folder, always try to keep its content up-to-date, coherent and organized. You can rename or delete files that are no longer relevant. Do not create new files unless necessary.
```
Вы также можете направлять то, что Claude записывает в память. Например: «Only write down information relevant to \ in your memory system.»
## Соображения безопасности
Ваше приложение выполняет каждую файловую операцию, которую запрашивает Claude, поэтому эти меры защиты — ваша ответственность:
### Конфиденциальная информация
Claude обычно отказывается записывать конфиденциальную информацию в файлы памяти. Для более надёжных гарантий добавьте проверку, которая удаляет конфиденциальные данные до того, как ваш обработчик запишет файл.
### Размер файлового хранилища
Отслеживайте размеры файлов памяти и ограничивайте, насколько большим может стать файл. Рассмотрите возможность ограничить количество символов, возвращаемых командой `view`, и позвольте Claude постранично просматривать остальное с помощью `view_range`.
### Истечение срока хранения памяти
Периодически удаляйте файлы памяти, к которым давно не обращались.
### Защита от обхода путей
Вредоносный путь, такой как `/memories/../../secrets.env`, может получить доступ к файлам за пределами каталога `/memories`. Ваша реализация должна проверять каждый путь в каждой команде, чтобы предотвратить атаки обхода каталогов.
Рассмотрите следующие меры защиты:
* Проверяйте, что все пути начинаются с `/memories`
* Приводите пути к канонической форме и проверяйте, что они остаются в пределах каталога памяти
* Отклоняйте пути, содержащие последовательности вроде `../`, `..\\` или другие паттерны обхода
* Следите за URL-кодированными последовательностями обхода (`%2e%2e%2f`)
* Используйте встроенные в ваш язык утилиты безопасности путей (например, `pathlib.Path.resolve()` и `relative_to()` в Python)
## Обработка ошибок
Инструмент памяти использует паттерны обработки ошибок, аналогичные [инструменту текстового редактора](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/text-editor-tool#handle-errors). Сообщения об ошибках каждой команды перечислены в разделе [Команды инструмента](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/memory-tool#tool-commands). Чтобы вернуть ошибку Claude, установите `is_error` в `true` в результате инструмента и поместите сообщение в `content`:
```json
{
"type": "tool_result",
"tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
"content": "Error: The path /memories/notes.txt does not exist",
"is_error": true
}
```
## Интеграция с редактированием контекста
Инструмент памяти сочетается с редактированием контекста для управления длительными разговорами. Подробности см. в разделе [Редактирование контекста](https://platform.claude.com/docs/ru/build-with-claude/context-editing).
## Использование с уплотнением
Инструмент памяти также можно сочетать с [уплотнением](https://platform.claude.com/docs/ru/build-with-claude/compaction) (compaction), которое суммирует более старый контекст разговора на стороне сервера. Редактирование контекста очищает конкретные результаты инструментов на клиенте. Уплотнение автоматически суммирует весь разговор на сервере, когда разговор приближается к лимиту контекстного окна.
Для длительно работающих агентов рассмотрите использование обоих подходов: уплотнение сохраняет активный контекст небольшим без учёта на стороне клиента, а память сохраняет информацию, которая должна пережить суммаризацию.
## Паттерн многосессионной разработки программного обеспечения
Для программных проектов, охватывающих несколько сессий агента, настраивайте файлы памяти целенаправленно, а не записывайте их спонтанно по ходу работы. Следующий паттерн превращает память в механизм восстановления: каждая новая сессия возобновляется с состояния, записанного предыдущей.
### Как работает паттерн
1. **Сессия-инициализатор:** Первая сессия настраивает файлы памяти до начала какой-либо существенной работы. Сюда входят журнал прогресса (отслеживающий, что сделано и что дальше), чек-лист функций (определяющий объём работы) и ссылка на любой скрипт запуска или инициализации, необходимый проекту.
2. **Последующие сессии:** Каждая новая сессия начинается с чтения этих файлов памяти. Это восстанавливает состояние проекта без повторного изучения кодовой базы или повторного прохождения ранее принятых решений.
3. **Обновление в конце сессии:** Перед завершением сессия обновляет журнал прогресса, указывая, что было выполнено и что осталось. Это гарантирует, что у следующей сессии будет точная отправная точка.
### Ключевой принцип
Работайте над одной функцией за раз. Отмечайте функцию как завершённую только после того, как сквозная проверка подтвердит её работоспособность, а не когда код написан. Это сохраняет точность журнала прогресса от сессии к сессии.
Подробный разбор этого паттерна на практике, включая скрипт-инициализатор, структуру файла прогресса и восстановление на основе git, см. в статье [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents).
## Следующие шаги
Выполняйте команды оболочки в постоянной сессии bash.
Автоматически управляйте контекстом разговора по мере его роста с помощью редактирования контекста.
Уплотнение контекста на стороне сервера для управления длинными разговорами, приближающимися к лимитам контекстного окна.
Каталог инструментов, предоставляемых Anthropic, и справочник по необязательным свойствам определения инструментов.