Haijun Platform Docs
EN

Memory tool memungkinkan Haijun menyimpan dan mengambil informasi di seluruh percakapan dalam sebuah direktori file memori. Haijun dapat membuat, membaca, memperbarui, dan menghapus file yang bertahan antar sesi, membangun pengetahuan dari waktu ke waktu tanpa menyimpan semuanya di jendela konteks.

Memory mendukung pengambilan konteks just-in-time. Alih-alih memuat semua informasi relevan di awal, sebuah agen mencatat apa yang dipelajarinya dalam file memori dan membacanya kembali sesuai permintaan. Ini menjaga konteks aktif tetap fokus pada tugas saat ini, yang penting untuk sesi berjalan lama yang jika tidak akan membebani jendela konteks. Lihat Effective context engineering untuk pola yang lebih luas.

Memory tool beroperasi di sisi klien: Haijun meminta operasi file, dan aplikasi Anda mengeksekusinya. Anda mengontrol di mana dan bagaimana data disimpan melalui infrastruktur Anda sendiri.

Note: Hubungi kami melalui formulir umpan balik untuk membagikan umpan balik Anda tentang fitur ini.

Note: Untuk mempelajari bagaimana "zero data retention" (retensi data nol), atau ZDR, berlaku untuk fitur ini, lihat API dan retensi data.

Kasus penggunaan

  • Mempertahankan konteks proyek di beberapa sesi agen
  • Menerapkan pelajaran dari interaksi, keputusan, dan umpan balik masa lalu ke tugas baru
  • Membangun basis pengetahuan dari waktu ke waktu

Cara kerjanya

Ketika memory tool diaktifkan, Haijun secara otomatis memeriksa direktori memorinya sebelum memulai tugas. Saat bekerja, Haijun menyimpan apa yang dipelajarinya dalam file di bawah /memories dan membacanya kembali dalam percakapan berikutnya untuk melanjutkan pekerjaan sebelumnya.

Karena memory tool berada di sisi klien, Haijun hanya meminta operasi memori. Aplikasi Anda mengeksekusi setiap permintaan terhadap penyimpanan yang Anda kontrol dan mengembalikan hasilnya dalam blok tool_result (lihat Menangani panggilan alat). Path /memories adalah prefiks yang dipetakan handler Anda ke penyimpanan nyata, seperti direktori per-pengguna atau kunci dalam database. Memori sepenuhnya berada di aplikasi Anda. Percakapan berikutnya melanjutkan dari memori yang sama ketika mengirim entri tools yang sama dan handler Anda melayani penyimpanan yang sama. Untuk keamanan, batasi semua operasi memori ke direktori /memories (lihat Perlindungan path traversal).

Contoh: Cara kerja panggilan memory tool

Interaksi tipikal terlihat seperti ini:

1. Permintaan pengguna:

text
"Help me respond to this customer service ticket."

2. Haijun memeriksa direktori memori:

text
"I'll help you respond to the customer service ticket. Let me check my memory for any previous context."

Haijun memanggil memory tool:

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

3. Aplikasi Anda mengembalikan isi direktori:

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. Haijun membaca file yang relevan:

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

5. Aplikasi Anda mengembalikan isi file:

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<guidelines>\n     2\t<addressing_customers>\n     3\t- Always address customers by their first name\n     4\t- Use empathetic language\n..."
}

6. Haijun menggunakan memori untuk membantu:

text
"Based on your customer service guidelines, I can help you craft a response. Please share the ticket details..."

Memory tool tersedia di semua model Haijun 4 dan yang lebih baru. Untuk daftar lengkap alat yang disediakan Juglow, lihat Referensi alat.

Memulai

Menggunakan memory tool memerlukan dua langkah:

  1. Tambahkan memory tool ke permintaan Anda. Entri tools {"type": "memory_20250818", "name": "memory"} adalah seluruh konfigurasinya: name harus memory, dan Anda tidak mendefinisikan skema input untuk alat yang disediakan Juglow.
  1. Implementasikan handler sisi klien untuk setiap perintah memori. Handler Anda harus menolak path di luar /memories, jadi baca Perlindungan path traversal sebelum Anda menulisnya.

Penggunaan dasar

bash
  curl https://haijun.my.id/v1/messages \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "haijun-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
  ant messages create <<'YAML'
  model: haijun-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
  client = juglow.Juglow()

  message = client.messages.create(
      model="haijun-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
  const juglow = new Juglow();

  const message = await juglow.messages.create({
    model: "haijun-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
  var client = new JuglowClient();

  var message = await client.Messages.Create(
      new()
      {
          Model = Model.HaijunOpus5_5,
          MaxTokens = 2048,
          Messages =
          [
              new()
              {
                  Role = Role.User,
                  Content = "Help me respond to this customer service ticket.",
              },
          ],
          Tools = [new MemoryTool20250818()],
      }
  );

  Console.WriteLine(message);
go
  client := juglow.NewClient()

  message, err := client.Messages.New(context.TODO(), juglow.MessageNewParams{
  	Model:     juglow.ModelHaijunOpus5_5,
  	MaxTokens: 2048,
  	Messages: []juglow.MessageParam{
  		juglow.NewUserMessage(juglow.NewTextBlock("Help me respond to this customer service ticket.")),
  	},
  	Tools: []juglow.ToolUnionParam{
  		{OfMemoryTool20250818: &juglow.MemoryTool20250818Param{}},
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(message)
java
  import com.juglow.models.messages.MemoryTool20250818;
  // ...
    JuglowClient client = JuglowOkHttpClient.fromEnv();

    MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.HAIJUN_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
  $client = new Client();

  $message = $client->messages->create(
      model: Model::HAIJUN_OPUS_5_5,
      maxTokens: 2048,
      messages: [
          [
              'role' => 'user',
              'content' => 'Help me respond to this customer service ticket.',
          ],
      ],
      tools: [new MemoryTool20250818],
  );

  echo $message;
ruby
  client = Juglow::Client.new

  message = client.messages.create(
    model: Juglow::Model::HAIJUN_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

Mengimplementasikan handler memori

Balasan Haijun terhadap permintaan seperti yang sebelumnya diakhiri dengan blok tool_use yang meminta operasi memori, seperti view /memories. Aplikasi Anda mengeksekusi operasi tersebut dan mengembalikan hasilnya dalam blok tool_result, lalu mengirim percakapan kembali sehingga Haijun dapat melanjutkan: loop penggunaan alat standar.

Empat SDK menyediakan helper memory tool yang menangani antarmuka alat dan loop. Subclass BetaAbstractMemoryTool (Python dan C#), gunakan betaMemoryTool (TypeScript), atau implementasikan BetaMemoryToolHandler (Java) untuk mendukung memori dengan penyimpanan Anda sendiri, seperti file di disk, database, penyimpanan cloud, atau file terenkripsi. Python dan TypeScript juga menyertakan implementasi sistem file lokal siap pakai, BetaLocalFilesystemMemoryTool. Permukaan helper dan tool-runner berada di namespace beta setiap SDK meskipun memory tool itu sendiri tidak memerlukan header beta. SDK Go dan Ruby tidak memiliki helper memori, jadi contoh-contoh tersebut menjalankan loop penggunaan alat sendiri, dan PHP membungkus closure handler Anda dalam BetaRunnableTool generiknya. Ketiganya menggunakan penyimpanan dalam memori yang Anda ganti dengan penyimpanan Anda sendiri.

python
  import juglow
  from juglow.tools import BetaLocalFilesystemMemoryTool

  client = juglow.Juglow()
  memory = BetaLocalFilesystemMemoryTool(base_path="./memory")

  runner = client.beta.messages.tool_runner(
      model="haijun-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
  import Juglow from "@juglow-ai/sdk";
  import { betaMemoryTool } from "@juglow-ai/sdk/helpers/beta/memory";
  import { BetaLocalFilesystemMemoryTool } from "@juglow-ai/sdk/tools/memory/node";

  const client = new Juglow();

  const backend = await BetaLocalFilesystemMemoryTool.init("./memory");
  const memory = betaMemoryTool(backend); // or pass your own handlers object

  const runner = client.beta.messages.toolRunner({
    model: "haijun-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
  using Juglow;
  using Juglow.Helpers.Beta;
  using Juglow.Models.Beta.Messages;

  var client = new JuglowClient();

  // Subclass BetaAbstractMemoryTool milik Anda
  var memory = new FilesystemMemoryTool("./memories");

  var runner = client.Beta.Messages.ToolRunner(
      new MessageCreateParams
      {
          Model = Juglow.Models.Messages.Model.HaijunOpus5_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
  package main

  import (
  	"context"
  	"encoding/json"
  	"fmt"
  	"log"
  	"slices"
  	"sort"
  	"strings"

  	"github.com/juglows/juglow-sdk-go"
  )

  // Penyimpanan dalam memori yang memetakan path file memori ke isinya.
  // Gunakan penyimpanan Anda sendiri di lingkungan produksi.
  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 := juglow.NewClient()
  	tools := []juglow.ToolUnionParam{{OfMemoryTool20250818: &juglow.MemoryTool20250818Param{}}}
  	messages := []juglow.MessageParam{
  		juglow.NewUserMessage(juglow.NewTextBlock("Remember that customer Acme Corp prefers email follow-ups.")),
  	}

  	for {
  		message, err := client.Messages.New(context.TODO(), juglow.MessageNewParams{
  			Model:     juglow.ModelHaijunOpus5_5,
  			MaxTokens: 1024,
  			Messages:  messages,
  			Tools:     tools,
  		})
  		if err != nil {
  			log.Fatal(err)
  		}
  		if message.StopReason != juglow.StopReasonToolUse {
  			for _, block := range message.Content {
  				if block.Type == "text" {
  					fmt.Println(block.Text)
  				}
  			}
  			break
  		}
  		results := []juglow.ContentBlockParamUnion{}
  		for _, block := range message.Content {
  			if block.Type == "tool_use" {
  				results = append(results, juglow.NewToolResultBlock(block.ID, executeMemory(block.Input), false))
  			}
  		}
  		messages = append(messages, message.ToParam(), juglow.NewUserMessage(results...))
  	}
  }
java
  import com.juglow.client.JuglowClient;
  import com.juglow.client.okhttp.JuglowOkHttpClient;
  import com.juglow.helpers.BetaMemoryToolHandler;
  import com.juglow.helpers.BetaToolRunner;
  import com.juglow.models.beta.messages.BetaMemoryTool20250818;
  import com.juglow.models.beta.messages.BetaMessage;
  import com.juglow.models.beta.messages.MessageCreateParams; // beta package, not models.messages
  import com.juglow.models.beta.messages.ToolRunnerCreateParams;
  import com.juglow.models.messages.Model;
  import java.nio.file.Path;

  void main() {
    JuglowClient client = JuglowOkHttpClient.fromEnv();

    // Implementasi BetaMemoryToolHandler Anda untuk enam perintah memori
    BetaMemoryToolHandler handler = new FileSystemMemoryToolHandler(Path.of("memories"));

    MessageCreateParams createParams = MessageCreateParams.builder()
      .model(Model.HAIJUN_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

  use Juglow\Beta\Messages\BetaMemoryTool20250818;
  use Juglow\Client;
  use Juglow\Lib\Tools\BetaRunnableTool;
  use Juglow\Messages\Model;

  $client = new Client();

  // Penyimpanan dalam memori yang memetakan path file memori ke isinya.
  // Gunakan penyimpanan Anda sendiri di lingkungan produksi.
  $store = [];

  $memory = new BetaRunnableTool(
      definition: new BetaMemoryTool20250818,
      run: function (array $input) use (&$store): string {
          $path = $input['path'] ?? '';
          switch ($input['command']) {
              case 'view':
                  if (isset($store[$path])) {
                      $numbered = [];
                      foreach (explode("\n", preg_replace('/\n\z/', '', $store[$path])) as $i => $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::HAIJUN_OPUS_5_5,
      tools: [$memory],
      maxIterations: 10,
  );

  $finalMessage = $runner->runUntilDone();
  print_r($finalMessage->content);
ruby
  require "juglow"

  client = Juglow::Client.new
  TOOLS = [{type: "memory_20250818", name: "memory"}].freeze

  # Penyimpanan dalam memori yang memetakan path file memori ke isinya.
  # Gunakan penyimpanan Anda sendiri di lingkungan produksi.
  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: Juglow::Model::HAIJUN_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

Penyimpanan dalam memori pada contoh Go, PHP, dan Ruby membuatnya mandiri: masing-masing mengirimkan berdasarkan field command dalam input blok tool_use dan mengembalikan string yang dijelaskan di bawah Perintah alat. Handler produksi juga memerlukan validasi path yang dilewati oleh penyimpanan demonstrasi ini. Untuk contoh lengkap SDK itu sendiri, lihat:

Perintah alat

Implementasi sisi klien Anda harus menangani perintah-perintah berikut. Spesifikasi ini menjelaskan perilaku yang direkomendasikan dan string yang dikembalikan: Haijun membaca teks apa pun yang terkandung dalam hasil alat Anda, jadi Anda dapat mengembalikan string yang berbeda jika aplikasi Anda membutuhkannya.

view

Menampilkan isi direktori atau isi file dengan rentang baris opsional:

json
{
  "command": "view",
  "path": "/memories/notes.txt",
  "view_range": [1, 10]
}

view_range bersifat opsional dan berlaku untuk tampilan file teks: [start_line, end_line] mengembalikan baris-baris tersebut, dan [start_line, -1] mengembalikan semuanya dari start_line hingga akhir file.

Nilai kembalian

Untuk direktori: Kembalikan daftar yang menampilkan file dan direktori dengan ukurannya:

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}
  • Mendaftar file hingga 2 tingkat kedalaman
  • Menampilkan ukuran yang dapat dibaca manusia (misalnya, 5.5K, 1.2M)
  • Mengecualikan item tersembunyi (file yang dimulai dengan .) dan node_modules
  • Menggunakan karakter tab antara ukuran dan path

view pertama dari /memories pada penyimpanan kosong bukanlah kesalahan. Memory tool sistem file lokal SDK (BetaLocalFilesystemMemoryTool) membuat root memori sebelum panggilan pertama Haijun dan mengembalikan header daftar diikuti oleh satu baris ukuran-dan-path untuk direktori kosong itu sendiri.

Untuk file: Kembalikan isi file dengan header dan nomor baris:

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

Pemformatan nomor baris:

  • Lebar: 6 karakter, rata kanan dengan padding spasi
  • Pemisah: Karakter tab antara nomor baris dan konten
  • Pengindeksan: Berbasis 1 (baris pertama adalah baris 1)
  • Batas baris: File dengan lebih dari 999.999 baris harus mengembalikan kesalahan: "File {path} exceeds maximum line limit of 999,999 lines."

Contoh output:

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

Deskripsi alat Haijun juga mengatakan bahwa view menampilkan file gambar (.jpg, .jpeg, dan .png) dan memotong tampilan teks file yang lebih panjang dari 16.000 karakter. Harapkan panggilan view pada path gambar dan tampilan berentang lanjutan dari file panjang.

Penanganan kesalahan

  • File atau direktori tidak ada: "The path {path} does not exist. Please provide a valid path."

create

Membuat file baru:

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

Nilai kembalian

  • Sukses: "File created successfully at: {path}"

Penanganan kesalahan

  • File sudah ada: "Error: File {path} already exists"

Deskripsi alat Haijun mengatakan create "membuat atau menimpa" sebuah file, jadi harapkan panggilan create pada path yang sudah ada. Mengembalikan kesalahan adalah perilaku referensi, dan menimpa sebagai gantinya adalah pilihan implementasi yang valid.

str\_replace

Mengganti teks dalam file:

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

new_str bersifat opsional untuk str_replace: ketika dihilangkan, old_str dihapus tanpa penggantian.

Nilai kembalian

  • Sukses: "The memory file has been edited." diikuti oleh cuplikan file yang diedit dengan nomor baris

Penanganan kesalahan

  • File tidak ada: "Error: The path {path} does not exist. Please provide a valid path."
  • Teks tidak ditemukan: `"No replacement was performed, old_str \{old_str} did not appear verbatim in {path}."`
  • Teks duplikat: Ketika old_str muncul beberapa kali, kembalikan: `"No replacement was performed. Multiple occurrences of old_str \{old_str} in lines: {line_numbers}. Please ensure it is unique"`

Penanganan direktori

Jika path adalah direktori, kembalikan kesalahan "file does not exist".

insert

Menyisipkan teks pada baris tertentu:

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

insert_text disisipkan setelah baris insert_line, dan 0 menyisipkan di awal file.

Nilai kembalian

  • Sukses: "The file {path} has been edited."

Penanganan kesalahan

  • File tidak ada: "Error: The path {path} does not exist"
  • Nomor baris tidak valid: `"Error: Invalid insert_line parameter: {insert_line}. It should be within the range of lines of the file: [0, {n_lines}]"`

Penanganan direktori

Jika path adalah direktori, kembalikan kesalahan "file does not exist".

delete

Menghapus file atau direktori:

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

Nilai kembalian

  • Sukses: "Successfully deleted {path}"

Penanganan kesalahan

  • File atau direktori tidak ada: "Error: The path {path} does not exist"

Penanganan direktori

Menghapus direktori dan semua isinya secara rekursif. Deskripsi alat memberi tahu Haijun bahwa ia tidak dapat menghapus direktori /memories itu sendiri, jadi tolak delete yang path-nya adalah root memori.

rename

Mengganti nama atau memindahkan file atau direktori:

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

Nilai kembalian

  • Sukses: "Successfully renamed {old_path} to {new_path}"

Penanganan kesalahan

  • Sumber tidak ada: "Error: The path {old_path} does not exist"
  • Tujuan sudah ada: Kembalikan kesalahan (jangan menimpa): "Error: The destination {new_path} already exists"

Penanganan direktori

Mengganti nama direktori. Deskripsi alat memberi tahu Haijun bahwa ia tidak dapat mengganti nama direktori /memories itu sendiri, jadi tolak rename yang old_path-nya adalah root memori.

Panduan prompting

Ketika memory tool ada dalam tools permintaan Anda, API secara otomatis menambahkan instruksi ini ke prompt sistem. Anda tidak perlu mengirimkannya sendiri:

text
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.

Deskripsi alat Haijun sudah memberitahunya untuk menjaga direktori memori tetap terorganisir, jadi Anda tidak perlu mengulangi instruksi tersebut. Jika Haijun masih membuat file memori yang berantakan, Anda dapat memperkuatnya dalam prompt Anda:

text
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.

Anda juga dapat memandu apa yang ditulis Haijun ke memori. Misalnya: "Hanya tuliskan informasi yang relevan dengan \ di sistem memori Anda."

Pertimbangan keamanan

Aplikasi Anda mengeksekusi setiap operasi file yang diminta Haijun, jadi pengamanan ini adalah tanggung jawab Anda:

Informasi sensitif

Haijun biasanya menolak menulis informasi sensitif ke file memori. Untuk jaminan yang lebih kuat, tambahkan validasi yang menghapus data sensitif sebelum handler Anda menulis file.

Ukuran penyimpanan file

Lacak ukuran file memori dan batasi seberapa besar sebuah file dapat tumbuh. Pertimbangkan untuk membatasi berapa banyak karakter yang dikembalikan perintah view, dan biarkan Haijun menelusuri sisanya dengan view_range.

Kedaluwarsa memori

Secara berkala hapus file memori yang belum diakses dalam waktu lama.

Perlindungan path traversal

Warning: Path berbahaya seperti /memories/../../secrets.env dapat menjangkau file di luar direktori /memories. Implementasi Anda harus memvalidasi setiap path dalam setiap perintah untuk mencegah serangan directory traversal.

Pertimbangkan pengamanan ini:

  • Validasi bahwa semua path dimulai dengan /memories
  • Selesaikan path ke bentuk kanoniknya dan verifikasi bahwa mereka tetap berada dalam direktori memori
  • Tolak path yang mengandung urutan seperti ../, ..\\, atau pola traversal lainnya
  • Waspadai urutan traversal yang dikodekan URL (%2e%2e%2f)
  • Gunakan utilitas keamanan path bawaan bahasa Anda (misalnya, pathlib.Path.resolve() dan relative_to() milik Python)

Penanganan kesalahan

Memory tool menggunakan pola penanganan kesalahan yang serupa dengan text editor tool. Pesan kesalahan setiap perintah tercantum di bawah Perintah alat. Untuk mengembalikan kesalahan ke Haijun, atur is_error ke true pada hasil alat dan letakkan pesan di content:

json
{
  "type": "tool_result",
  "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": "Error: The path /memories/notes.txt does not exist",
  "is_error": true
}

Integrasi pengeditan konteks

Memory tool berpasangan dengan pengeditan konteks untuk mengelola percakapan berjalan lama. Untuk detailnya, lihat Pengeditan konteks.

Menggunakan dengan compaction

Memory tool juga dapat dipasangkan dengan compaction, yang merangkum konteks percakapan lama di sisi server. Pengeditan konteks menghapus hasil alat tertentu di klien. Compaction secara otomatis merangkum seluruh percakapan di server ketika percakapan mendekati batas jendela konteks.

Untuk agen berjalan lama, pertimbangkan untuk menggunakan keduanya: compaction menjaga konteks aktif tetap kecil tanpa pembukuan sisi klien, dan memori mempertahankan informasi yang harus bertahan dari perangkuman.

Pola pengembangan perangkat lunak multisesi

Untuk proyek perangkat lunak yang mencakup beberapa sesi agen, siapkan file memori secara sengaja alih-alih menulisnya secara ad hoc seiring berjalannya pekerjaan. Pola berikut mengubah memori menjadi mekanisme pemulihan: setiap sesi baru melanjutkan dari keadaan yang dicatat sesi terakhir.

Cara kerja pola

  1. Sesi inisialisasi: Sesi pertama menyiapkan file memori sebelum pekerjaan substantif apa pun dimulai. Ini mencakup log kemajuan (melacak apa yang telah dilakukan dan apa yang akan datang), daftar periksa fitur (mendefinisikan ruang lingkup pekerjaan), dan referensi ke skrip startup atau inisialisasi apa pun yang dibutuhkan proyek.
  1. Sesi berikutnya: Setiap sesi baru dibuka dengan membaca file memori tersebut. Ini memulihkan keadaan proyek tanpa menjelajahi ulang basis kode atau menelusuri kembali keputusan sebelumnya.
  1. Pembaruan akhir sesi: Sebelum sesi berakhir, ia memperbarui log kemajuan dengan apa yang telah diselesaikan dan apa yang tersisa. Ini memastikan sesi berikutnya memiliki titik awal yang akurat.

Prinsip utama

Kerjakan satu fitur pada satu waktu. Tandai fitur sebagai selesai hanya setelah verifikasi end-to-end mengonfirmasi bahwa fitur tersebut berfungsi, bukan ketika kode ditulis. Ini menjaga log kemajuan tetap akurat dari sesi ke sesi.

Tip: Untuk studi kasus terperinci tentang pola ini dalam praktik, termasuk skrip inisialisasi, struktur file kemajuan, dan pemulihan berbasis git, lihat Effective harnesses for long-running agents.

Langkah selanjutnya

Jalankan perintah shell dalam sesi bash yang persisten.

Kelola konteks percakapan secara otomatis saat bertumbuh dengan pengeditan konteks.

Compaction konteks sisi server untuk mengelola percakapan panjang yang mendekati batas jendela konteks.

Direktori alat yang disediakan Juglow dan referensi untuk properti definisi alat opsional.

On this page
Kasus penggunaanCara kerjanyaContoh: Cara kerja panggilan memory toolMemulaiPenggunaan dasarMengimplementasikan handler memoriPerintah alatviewNilai kembalianPenanganan kesalahancreateNilai kembalianPenanganan kesalahanstr\_replaceNilai kembalianPenanganan kesalahanPenanganan direktoriinsertNilai kembalianPenanganan kesalahanPenanganan direktorideleteNilai kembalianPenanganan kesalahanPenanganan direktorirenameNilai kembalianPenanganan kesalahanPenanganan direktoriPanduan promptingPertimbangan keamananInformasi sensitifUkuran penyimpanan fileKedaluwarsa memoriPerlindungan path traversalPenanganan kesalahanIntegrasi pengeditan konteksMenggunakan dengan compactionPola pengembangan perangkat lunak multisesiCara kerja polaPrinsip utamaLangkah selanjutnya