Menggunakan memori agen

Setiap sesi Managed Agents dimulai dengan konteks baru secara default. Ketika sebuah sesi berakhir, semua state yang telah dibangun agen akan hilang. Memory store (penyimpanan memori) memungkinkan agen membawa informasi lintas sesi: preferensi pengguna, konvensi proyek, kesalahan sebelumnya, dan konteks domain.

Note: Jangan menggabungkan agent-memory-2026-07-22 dengan managed-agents-2026-04-01 pada permintaan memory store: mengirim keduanya akan mengembalikan error 400. Jika kode Anda menetapkan header beta secara eksplisit, ganti managed-agents-2026-04-01 dengan agent-memory-2026-07-22 pada panggilan memory store alih-alih menambahkan nilai kedua. Endpoint sesi, termasuk melampirkan memory store ke sesi, tetap menggunakan managed-agents-2026-04-01. GET /v1/memory_stores/{memory_store_id}/memories berperilaku sama di bawah header mana pun: hasil dikembalikan dalam urutan yang stabil dan ditentukan server, serta path_prefix dan depth berlaku dengan cara yang sama.

Ikhtisar

Sebuah memory store adalah kumpulan dokumen teks dengan cakupan workspace yang dioptimalkan untuk Haijun. Ketika Anda melampirkan store ke sebuah sesi, store tersebut di-mount sebagai direktori di dalam sandbox sesi. Agen membaca dan menulisnya dengan alat file yang sama yang digunakannya untuk bagian filesystem lainnya, dan sebuah catatan yang menjelaskan setiap mount secara otomatis ditambahkan ke "system prompt" (prompt sistem), yang memberi tahu agen di mana harus mencari. Toolset agen diperlukan untuk interaksi ini; pastikan untuk mengaktifkannya saat pembuatan agen. Pada sandbox self-hosted, direktori tersebut bukan mount langsung. Sebagai gantinya, environment worker milik SDK mengunduh setiap store yang dilampirkan ke dalam sandbox Anda sebelum alat agen berjalan dan menjaga salinan tersebut tetap sinkron dengan store.

Setiap memori dalam sebuah store dialamatkan dengan sebuah path dan dapat dibaca serta diedit langsung melalui API atau Haijun Console, sehingga memungkinkan penyetelan, impor, dan ekspor.

Setiap perubahan pada memori menciptakan versi memori yang tidak dapat diubah (immutable), memberi Anda jejak audit dan pemulihan point-in-time untuk semua yang ditulis agen.

Membuat memory store

Berikan store sebuah name dan description. Deskripsi tersebut diteruskan ke agen, memberi tahu apa isi store tersebut.

bash

  curl -s https://haijun.my.id/v1/memory_stores \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "juglow-beta: agent-memory-2026-07-22" \
    -H "content-type: application/json" \
    -d '{"name": "User Preferences", "description": "Per-user preferences and project context."}'

bash

    ant apply memory_store.yaml

yaml

      # yaml-language-server: $schema=https://platform.juglow.my.id/schemas/ant/beta/memory_store.json
      name: User Preferences
      description: Per-user preferences and project context.

python

  store = client.beta.memory_stores.create(
      name="User Preferences",
      description="Per-user preferences and project context.",
  )
  print(store.id)  # memstore_01Hx...

typescript

  const store = await client.beta.memoryStores.create({
    name: "User Preferences",
    description: "Per-user preferences and project context."
  });
  console.log(store.id); // memstore_01Hx...

csharp

  var store = await client.Beta.MemoryStores.Create(new()
  {
      Name = "User Preferences",
      Description = "Per-user preferences and project context.",
  });
  Console.WriteLine(store.ID);  // memstore_01Hx...

  store, err := client.Beta.MemoryStores.New(ctx, juglow.BetaMemoryStoreNewParams{
  	Name:        "User Preferences",
  	Description: juglow.String("Per-user preferences and project context."),
  })
  if err != nil {
  	panic(err)
  }
  fmt.Println(store.ID) // memstore_01Hx...

java

  var store = client.beta().memoryStores().create(
      MemoryStoreCreateParams.builder()
          .name("User Preferences")
          .description("Per-user preferences and project context.")
          .build()
  );
  IO.println(store.id());  // memstore_01Hx...

php

  use Juglow\Client;

  $client = new Client();

  $store = $client->beta->memoryStores->create(
      name: 'User Preferences',
      description: 'Per-user preferences and project context.',
  );
  echo "{$store->id}\n"; // memstore_01Hx...

ruby

  require "juglow"

  client = Juglow::Client.new

  store = client.beta.memory_stores.create(
    name: "User Preferences",
    description: "Per-user preferences and project context."
  )
  puts store.id # memstore_01Hx...

id memory store (memstore_...) adalah yang Anda teruskan saat melampirkan store ke sebuah sesi.

Mengisinya dengan konten awal (opsional)

Muat store terlebih dahulu dengan materi referensi sebelum agen apa pun berjalan:

bash

  curl -s "https://haijun.my.id/v1/memory_stores/$store_id/memories" \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "juglow-beta: agent-memory-2026-07-22" \
    -H "content-type: application/json" \
    -d '{"path": "/formatting_standards.md", "content": "All reports use GAAP formatting. Dates are ISO-8601..."}' > /dev/null

bash

  ant beta:memory-stores:memories create \
    --memory-store-id "$store_id" \
    --path "/formatting_standards.md" \
    --content "All reports use GAAP formatting. Dates are ISO-8601..." \
    > /dev/null

python

  client.beta.memory_stores.memories.create(
      store.id,
      path="/formatting_standards.md",
      content="All reports use GAAP formatting. Dates are ISO-8601...",
  )

typescript

  await client.beta.memoryStores.memories.create(store.id, {
    path: "/formatting_standards.md",
    content: "All reports use GAAP formatting. Dates are ISO-8601..."
  });

csharp

  await client.Beta.MemoryStores.Memories.Create(store.ID, new()
  {
      Path = "/formatting_standards.md",
      Content = "All reports use GAAP formatting. Dates are ISO-8601...",
  });

  _, err = client.Beta.MemoryStores.Memories.New(ctx, store.ID, juglow.BetaMemoryStoreMemoryNewParams{
  	Path:    "/formatting_standards.md",
  	Content: juglow.String("All reports use GAAP formatting. Dates are ISO-8601..."),
  })
  if err != nil {
  	panic(err)
  }

java

  client.beta().memoryStores().memories().create(
      store.id(),
      MemoryCreateParams.builder()
          .path("/formatting_standards.md")
          .content("All reports use GAAP formatting. Dates are ISO-8601...")
          .build()
  );

php

  $client->beta->memoryStores->memories->create(
      $store->id,
      path: '/formatting_standards.md',
      content: 'All reports use GAAP formatting. Dates are ISO-8601...',
  );

ruby

  client.beta.memory_stores.memories.create(
    store.id,
    path: "/formatting_standards.md",
    content: "All reports use GAAP formatting. Dates are ISO-8601..."
  )

Tip: Memori individual di dalam store dibatasi hingga 100 kB (\~25 ribu token). Sebuah store menampung maksimum 10.000 memori. Susun memori sebagai banyak file kecil yang terfokus, bukan beberapa file besar.

Melampirkan memory store ke sesi

Memory store dilampirkan dalam array resources[] milik sesi ketika sesi dibuat. Tidak seperti resource file, memory store hanya dapat dilampirkan pada saat pembuatan sesi; menambahkan atau menghapusnya dari sesi yang sedang berjalan tidak didukung. Anda melampirkan memory store dengan cara yang sama untuk sesi di cloud dan environment self-hosted; environment self-hosted hanya menerima resource memory_store.

Secara opsional, sertakan instructions untuk memberikan panduan khusus sesi tentang bagaimana agen harus menggunakan store ini. Ini ditampilkan kepada agen bersama name dan description store, dan dibatasi hingga 4.096 karakter.

Anda juga dapat mengonfigurasi access. Nilai defaultnya adalah read_write (ditampilkan secara eksplisit dalam contoh berikut), tetapi read_only juga didukung.

bash

  curl -s https://haijun.my.id/v1/sessions \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "juglow-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    --data @- <<EOF
  {
    "agent": "$agent_id",
    "environment_id": "$environment_id",
    "resources": [
      {
        "type": "memory_store",
        "memory_store_id": "$store_id",
        "access": "read_write",
        "instructions": "User preferences and project context. Check before starting any task."
      }
    ]
  }
  EOF

bash

  ant beta:sessions create <<YAML
  agent: $agent_id
  environment_id: $environment_id
  resources:
    - type: memory_store
      memory_store_id: $store_id
      access: read_write
      instructions: User preferences and project context. Check before starting any task.
  YAML

python

  session = client.beta.sessions.create(
      agent=agent.id,
      environment_id=environment.id,
      resources=[
          {
              "type": "memory_store",
              "memory_store_id": store.id,
              "access": "read_write",
              "instructions": "User preferences and project context. Check before starting any task.",
          }
      ],
  )

typescript

  const session = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id,
    resources: [
      {
        type: "memory_store",
        memory_store_id: store.id,
        access: "read_write",
        instructions: "User preferences and project context. Check before starting any task."
      }
    ]
  });

csharp

  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
      Resources =
      [
          new BetaManagedAgentsMemoryStoreResourceParam
          {
              Type = "memory_store",
              MemoryStoreID = store.ID,
              Access = "read_write",
              Instructions = "User preferences and project context. Check before starting any task.",
          },
      ],
  });

  session, err := client.Beta.Sessions.New(ctx, juglow.BetaSessionNewParams{
  	Agent: juglow.BetaSessionNewParamsAgentUnion{
  		OfString: juglow.String(agent.ID),
  	},
  	EnvironmentID: environment.ID,
  	Resources: []juglow.BetaSessionNewParamsResourceUnion{{
  		OfMemoryStore: &juglow.BetaManagedAgentsMemoryStoreResourceParam{
  			Type:          juglow.BetaManagedAgentsMemoryStoreResourceParamTypeMemoryStore,
  			MemoryStoreID: store.ID,
  			Access:        juglow.BetaManagedAgentsMemoryStoreResourceParamAccessReadWrite,
  			Instructions:  juglow.String("User preferences and project context. Check before starting any task."),
  		},
  	}},
  })
  if err != nil {
  	panic(err)
  }

java

  var session = client.beta().sessions().create(
      SessionCreateParams.builder()
          .agent(agent.id())
          .environmentId(environment.id())
          .addResource(
              BetaManagedAgentsMemoryStoreResourceParam.builder()
                  .type(BetaManagedAgentsMemoryStoreResourceParam.Type.MEMORY_STORE)
                  .memoryStoreId(store.id())
                  .access(BetaManagedAgentsMemoryStoreResourceParam.Access.READ_WRITE)
                  .instructions("User preferences and project context. Check before starting any task.")
                  .build()
          )
          .build()
  );

php

  $session = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
      resources: [
          [
              'type' => 'memory_store',
              'memory_store_id' => $store->id,
              'access' => 'read_write',
              'instructions' => 'User preferences and project context. Check before starting any task.',
          ],
      ],
  );

ruby

  session = client.beta.sessions.create(
    agent: agent.id,
    environment_id: environment.id,
    resources: [
      {
        type: "memory_store",
        memory_store_id: store.id,
        access: "read_write",
        instructions: "User preferences and project context. Check before starting any task."
      }
    ]
  )

Warning: Memory store dilampirkan dengan akses read_write secara default. Jika agen memproses input yang tidak tepercaya (prompt yang diberikan pengguna, konten web yang diambil, atau output alat pihak ketiga), prompt injection yang berhasil dapat menulis konten berbahaya ke dalam store. Sesi-sesi berikutnya kemudian membaca konten tersebut sebagai memori tepercaya. Gunakan read_only untuk materi referensi, lookup bersama, dan store apa pun yang tidak perlu dimodifikasi oleh agen.

Maksimum 8 memory store didukung per sesi. Lampirkan beberapa store ketika bagian-bagian memori yang berbeda memiliki pemilik atau aturan akses yang berbeda. Alasan umum:

Materi referensi bersama: satu store read-only yang dilampirkan ke banyak sesi (standar, konvensi, pengetahuan domain), dipisahkan dari store read-write milik masing-masing sesi.

Pemetaan ke struktur produk Anda: satu store per pengguna akhir, per tim, atau per proyek, sambil berbagi satu konfigurasi agen.

Siklus hidup yang berbeda: store yang bertahan lebih lama dari sesi tunggal mana pun, atau store yang ingin Anda arsipkan sesuai jadwalnya sendiri.

Bagaimana agen mengakses memori

Setiap store yang dilampirkan di-mount di dalam sandbox sesi sebagai direktori di bawah /mnt/memory/. Nama direktori adalah nama tampilan store yang disanitasi menjadi slug yang aman untuk filesystem (huruf kecil; rangkaian karakter non-alfanumerik menjadi satu tanda hubung), sehingga store bernama "Demo Memory" di-mount di /mnt/memory/demo-memory/. Path persisnya dikembalikan dalam field mount_path pada resource memory-store milik sesi; baca dari sana alih-alih menyusunnya sendiri. Agen membaca dan menulis store dengan toolset agen standar. Penulisan di bawah mount path dipersistenkan kembali ke store dan tetap sinkron di seluruh sesi yang berbagi store tersebut; penulisan ke path lain mana pun di bawah /mnt/memory/ akan gagal, karena sandbox me-mount direktori induk tersebut sebagai read-only. Deskripsi singkat setiap mount (nama tampilan, mount path, mode akses, description store, dan instructions apa pun) secara otomatis ditambahkan ke prompt sistem.

access ditegakkan di tingkat filesystem: mount read_only menolak penulisan, sedangkan penulisan ke mount read_write menghasilkan versi memori yang diatribusikan ke sesi tersebut.

Note: Pada sandbox self-hosted, direktori setiap store adalah salinan lokal yang dikelola oleh worker SDK, bukan mount langsung. Worker merekonsiliasi setiap salinan dengan store-nya setelah pemanggilan alat, paling banyak sekali per interval sinkronisasi (15 detik secara default), dan sekali lagi ketika sesi berakhir. Alat write dan edit milik agen hanya mengubah salinan lokal; worker mengunggah perubahan tersebut pada sinkronisasi berikutnya, sehingga sesi lain yang berjalan di sandbox self-hosted baru melihat perubahan setelah kedua worker telah melakukan sinkronisasi. Path di bawah /mnt/memory/ di luar direktori store bukanlah ruang scratch di sana: alat file milik worker menolak menulis ke path tersebut, dan apa pun yang ditulis perintah shell di sana tidak pernah disinkronkan ke store. Untuk store read_only, alat write dan edit milik worker menolak perubahan di bawah direktori tersebut dan worker tidak pernah mengunggah apa pun darinya. Untuk mempelajari bagaimana worker menyelesaikan konflik penulisan, dan apa yang masih dapat diubah oleh alat bash dalam salinan lokal store read-only, lihat Store read-only dan konflik.

Pembacaan dan penulisan agen muncul dalam event stream sebagai event agent.tool_use dan agent.tool_result biasa untuk alat mana pun yang menyentuh mount tersebut.

Melihat dan mengedit memori

Memory store dapat dikelola langsung melalui API. Gunakan ini untuk membangun alur kerja peninjauan, memperbaiki memori yang buruk, atau mengisi store sebelum sesi apa pun berjalan.

Mendaftar memori

Daftar memori dalam sebuah store. Hasil dikembalikan dalam urutan yang stabil dan ditentukan server.

path_prefix membatasi daftar ke satu direktori. Nilainya harus diakhiri dengan / dan mencocokkan segmen path utuh, sehingga path_prefix=/notes/ mengembalikan /notes/todo.md tetapi tidak /notes-archive/todo.md.

depth mengontrol seberapa dalam daftar menelusuri di bawah path_prefix: hilangkan (atau teruskan 0) untuk mendaftar seluruh subtree, atau teruskan 1 untuk mendaftar hanya anak langsungnya. Nilai lain mengembalikan error 400.

bash

  curl -s "https://haijun.my.id/v1/memory_stores/$store_id/memories?path_prefix=/" \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "juglow-beta: agent-memory-2026-07-22"

bash

  ant beta:memory-stores:memories list \
    --memory-store-id "$store_id" \
    --path-prefix "/"

python

  page = client.beta.memory_stores.memories.list(
      store.id,
      path_prefix="/",
  )
  for item in page.data:
      print(item.type, item.path)

typescript

  const page = await client.beta.memoryStores.memories.list(store.id, {
    path_prefix: "/"
  });
  for (const item of page.data) {
    console.log(item.type, item.path);
  }

csharp

  var page = await client.Beta.MemoryStores.Memories.List(store.ID, new()
  {
      PathPrefix = "/",
  });
  await foreach (var item in page.Paginate())
  {
      var line = item.Match(m => $"memory  {m.Path}", p => $"memory_prefix  {p.Path}");
      Console.WriteLine(line);
  }

  page, err := client.Beta.MemoryStores.Memories.List(ctx, store.ID, juglow.BetaMemoryStoreMemoryListParams{
  	PathPrefix: juglow.String("/"),
  })
  if err != nil {
  	panic(err)
  }
  for _, item := range page.Data {
  	fmt.Println(item.Type, item.Path)
  }

java

  var page = client.beta().memoryStores().memories().list(
      store.id(),
      MemoryListParams.builder()
          .pathPrefix("/")
          .build()
  );
  for (var item : page.data()) {
      item.memory().ifPresent(m -> IO.println("memory  " + m.path()));
      item.memoryPrefix().ifPresent(p -> IO.println("memory_prefix  " + p.path()));
  }

php

  $page = $client->beta->memoryStores->memories->list(
      $store->id,
      pathPrefix: '/',
  );
  foreach ($page->data as $item) {
      echo "{$item->type}  {$item->path}\n";
  }

ruby

  page = client.beta.memory_stores.memories.list(
    store.id,
    path_prefix: "/"
  )
  page.data.each do |entry|
    puts "#{entry.type}  #{entry.path}"
  end

Lihat referensi List memories untuk parameter lengkap dan skema respons.

Membaca memori

Mengambil memori individual mengembalikan konten lengkapnya.

bash

  curl -s "https://haijun.my.id/v1/memory_stores/$store_id/memories/$mem_id" \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "juglow-beta: agent-memory-2026-07-22"

bash

  ant beta:memory-stores:memories retrieve \
    --memory-store-id "$store_id" \
    --memory-id "$mem_id"

python

  retrieved = client.beta.memory_stores.memories.retrieve(
      mem.id,
      memory_store_id=store.id,
  )
  print(retrieved.content)

typescript

  const retrieved = await client.beta.memoryStores.memories.retrieve(mem.id, {
    memory_store_id: store.id
  });
  console.log(retrieved.content);

csharp

  var retrieved = await client.Beta.MemoryStores.Memories.Retrieve(mem.ID, new()
  {
      MemoryStoreID = store.ID,
  });
  Console.WriteLine(retrieved.Content);

  retrieved, err := client.Beta.MemoryStores.Memories.Get(ctx, mem.ID, juglow.BetaMemoryStoreMemoryGetParams{
  	MemoryStoreID: store.ID,
  })
  if err != nil {
  	panic(err)
  }
  fmt.Println(retrieved.Content)

java

  var retrieved = client.beta().memoryStores().memories().retrieve(
      mem.id(),
      MemoryRetrieveParams.builder().memoryStoreId(store.id()).build()
  );
  IO.println(retrieved.content().orElseThrow());

php

  $retrieved = $client->beta->memoryStores->memories->retrieve($mem->id, memoryStoreID: $store->id);
  echo "{$retrieved->content}\n";

ruby

  retrieved = client.beta.memory_stores.memories.retrieve(
    mem.id,
    memory_store_id: store.id
  )
  puts retrieved.content

Lihat referensi Retrieve a memory untuk parameter lengkap dan skema respons.

Membuat memori

memories.create membuat memori pada path tertentu. Create tidak menimpa; untuk mengubah memori yang sudah ada, gunakan memories.update.

bash

  curl -s "https://haijun.my.id/v1/memory_stores/$store_id/memories" \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "juglow-beta: agent-memory-2026-07-22" \
    -H "content-type: application/json" \
    -d '{"path": "/preferences/formatting.md", "content": "Always use tabs, not spaces."}'

bash

  ant beta:memory-stores:memories create \
    --memory-store-id "$store_id" \
    --path "/preferences/formatting.md" \
    --content "Always use tabs, not spaces."

python

  mem = client.beta.memory_stores.memories.create(
      store.id,
      path="/preferences/formatting.md",
      content="Always use tabs, not spaces.",
  )

typescript

  const mem = await client.beta.memoryStores.memories.create(store.id, {
    path: "/preferences/formatting.md",
    content: "Always use tabs, not spaces."
  });

csharp

  var mem = await client.Beta.MemoryStores.Memories.Create(store.ID, new()
  {
      Path = "/preferences/formatting.md",
      Content = "Always use tabs, not spaces.",
  });

  mem, err := client.Beta.MemoryStores.Memories.New(ctx, store.ID, juglow.BetaMemoryStoreMemoryNewParams{
  	Path:    "/preferences/formatting.md",
  	Content: juglow.String("Always use tabs, not spaces."),
  })
  if err != nil {
  	panic(err)
  }

java

  var mem = client.beta().memoryStores().memories().create(
      store.id(),
      MemoryCreateParams.builder()
          .path("/preferences/formatting.md")
          .content("Always use tabs, not spaces.")
          .build()
  );

php

  $mem = $client->beta->memoryStores->memories->create(
      $store->id,
      path: '/preferences/formatting.md',
      content: 'Always use tabs, not spaces.',
  );

ruby

  mem = client.beta.memory_stores.memories.create(
    store.id,
    path: "/preferences/formatting.md",
    content: "Always use tabs, not spaces."
  )

Lihat referensi Create a memory untuk parameter lengkap dan skema respons.

Memperbarui memori

memories.update memodifikasi memori yang sudah ada berdasarkan ID. Anda dapat mengubah content, path (penggantian nama), atau keduanya. Contoh berikut mengganti nama memori ke path arsip:

bash

  curl -s -X POST "https://haijun.my.id/v1/memory_stores/$store_id/memories/$mem_id" \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "juglow-beta: agent-memory-2026-07-22" \
    -H "content-type: application/json" \
    -d '{"path": "/archive/2026_q1_formatting.md"}' > /dev/null

bash

  ant beta:memory-stores:memories update \
    --memory-store-id "$store_id" \
    --memory-id "$mem_id" \
    --path "/archive/2026_q1_formatting.md" \
    > /dev/null

python

  client.beta.memory_stores.memories.update(
      mem.id,
      memory_store_id=store.id,
      path="/archive/2026_q1_formatting.md",
  )

typescript

  await client.beta.memoryStores.memories.update(mem.id, {
    memory_store_id: store.id,
    path: "/archive/2026_q1_formatting.md"
  });

csharp

  await client.Beta.MemoryStores.Memories.Update(mem.ID, new()
  {
      MemoryStoreID = store.ID,
      Path = "/archive/2026_q1_formatting.md",
  });

  _, err = client.Beta.MemoryStores.Memories.Update(ctx, mem.ID, juglow.BetaMemoryStoreMemoryUpdateParams{
  	MemoryStoreID: store.ID,
  	Path:          juglow.String("/archive/2026_q1_formatting.md"),
  })
  if err != nil {
  	panic(err)
  }

java

  client.beta().memoryStores().memories().update(
      mem.id(),
      MemoryUpdateParams.builder()
          .memoryStoreId(store.id())
          .path("/archive/2026_q1_formatting.md")
          .build()
  );

php

  $client->beta->memoryStores->memories->update(
      $mem->id,
      memoryStoreID: $store->id,
      path: '/archive/2026_q1_formatting.md',
  );

ruby

  client.beta.memory_stores.memories.update(
    mem.id,
    memory_store_id: store.id,
    path: "/archive/2026_q1_formatting.md"
  )

Lihat referensi Update a memory untuk parameter lengkap dan skema respons.

Pengeditan konten yang aman (optimistic concurrency)

Untuk menghindari menimpa penulisan yang terjadi bersamaan, teruskan prakondisi content_sha256. Pembaruan hanya diterapkan jika hash konten yang tersimpan masih cocok dengan yang Anda baca; jika tidak cocok, baca ulang memori dan coba lagi terhadap state terbaru.

bash

  curl -s -X POST "https://haijun.my.id/v1/memory_stores/$store_id/memories/$mem_id" \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "juglow-beta: agent-memory-2026-07-22" \
    -H "content-type: application/json" \
    --data @- > /dev/null <<EOF
  {
    "content": "CORRECTED: Always use 2-space indentation.",
    "precondition": {"type": "content_sha256", "content_sha256": "$mem_sha"}
  }
  EOF

bash

  ant beta:memory-stores:memories update \
    --memory-store-id "$store_id" \
    --memory-id "$mem_id" \
    --content "CORRECTED: Always use 2-space indentation." \
    --precondition "{type: content_sha256, content_sha256: $mem_sha}" \
    > /dev/null

python

  client.beta.memory_stores.memories.update(
      memory_id=mem.id,
      memory_store_id=store.id,
      content="CORRECTED: Always use 2-space indentation.",
      precondition={"type": "content_sha256", "content_sha256": mem.content_sha256},
  )

typescript

  await client.beta.memoryStores.memories.update(mem.id, {
    memory_store_id: store.id,
    content: "CORRECTED: Always use 2-space indentation.",
    precondition: { type: "content_sha256", content_sha256: mem.content_sha256 }
  });

csharp

  await client.Beta.MemoryStores.Memories.Update(mem.ID, new()
  {
      MemoryStoreID = store.ID,
      Content = "CORRECTED: Always use 2-space indentation.",
      Precondition = new BetaManagedAgentsPrecondition
      {
          Type = "content_sha256",
          ContentSha256 = mem.ContentSha256,
      },
  });

  _, err = client.Beta.MemoryStores.Memories.Update(ctx, mem.ID, juglow.BetaMemoryStoreMemoryUpdateParams{
  	MemoryStoreID: store.ID,
  	Content:       juglow.String("CORRECTED: Always use 2-space indentation."),
  	Precondition: juglow.BetaManagedAgentsPreconditionParam{
  		Type:          juglow.BetaManagedAgentsPreconditionTypeContentSha256,
  		ContentSha256: juglow.String(mem.ContentSha256),
  	},
  })
  if err != nil {
  	panic(err)
  }

java

  client.beta().memoryStores().memories().update(
      mem.id(),
      MemoryUpdateParams.builder()
          .memoryStoreId(store.id())
          .content("CORRECTED: Always use 2-space indentation.")
          .precondition(
              BetaManagedAgentsPrecondition.builder()
                  .type(BetaManagedAgentsPrecondition.Type.CONTENT_SHA256)
                  .contentSha256(mem.contentSha256())
                  .build()
          )
          .build()
  );

php

  $client->beta->memoryStores->memories->update(
      $mem->id,
      memoryStoreID: $store->id,
      content: 'CORRECTED: Always use 2-space indentation.',
      precondition: ['type' => 'content_sha256', 'content_sha256' => $mem->contentSha256],
  );

ruby

  client.beta.memory_stores.memories.update(
    mem.id,
    memory_store_id: store.id,
    content: "CORRECTED: Always use 2-space indentation.",
    precondition: {type: "content_sha256", content_sha256: mem.content_sha256}
  )

Menghapus memori

bash

  curl -s -X DELETE "https://haijun.my.id/v1/memory_stores/$store_id/memories/$mem_id" \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "juglow-beta: agent-memory-2026-07-22" > /dev/null

bash

  ant beta:memory-stores:memories delete \
    --memory-store-id "$store_id" \
    --memory-id "$mem_id" \
    > /dev/null

python

  client.beta.memory_stores.memories.delete(
      mem.id,
      memory_store_id=store.id,
  )

typescript

  await client.beta.memoryStores.memories.delete(mem.id, {
    memory_store_id: store.id
  });

csharp

  await client.Beta.MemoryStores.Memories.Delete(mem.ID, new()
  {
      MemoryStoreID = store.ID,
  });

  _, err = client.Beta.MemoryStores.Memories.Delete(ctx, mem.ID, juglow.BetaMemoryStoreMemoryDeleteParams{
  	MemoryStoreID: store.ID,
  })
  if err != nil {
  	panic(err)
  }

java

  client.beta().memoryStores().memories().delete(
      mem.id(),
      MemoryDeleteParams.builder().memoryStoreId(store.id()).build()
  );

php

  $client->beta->memoryStores->memories->delete($mem->id, memoryStoreID: $store->id);

ruby

  client.beta.memory_stores.memories.delete(
    mem.id,
    memory_store_id: store.id
  )

Lihat referensi Delete a memory untuk parameter lengkap dan skema respons.

Mengaudit perubahan memori

Setiap mutasi pada memori menciptakan versi memori yang tidak dapat diubah (memver_...). Gunakan endpoint versi untuk mengaudit siapa yang mengubah apa dan kapan, untuk memeriksa atau memulihkan snapshot sebelumnya, dan untuk membersihkan konten sensitif dari riwayat dengan redact.

Versi dimiliki oleh store (bukan memori individual) dan tidak dihapus ketika memori itu sendiri dihapus, sehingga jejak audit juga mencakup memori yang telah dihapus, sesuai dengan retensi yang dijelaskan di bawah. Versi disimpan selama 30 hari setelah ditulis; namun, versi-versi terbaru dari memori yang masih aktif selalu disimpan tanpa memandang usianya, sehingga memori yang jarang berubah mungkin mempertahankan riwayat lebih dari 30 hari. Panggilan memories.retrieve langsung selalu mengembalikan versi terbaru; endpoint versi memberi Anda riwayat yang masih disimpan.

Tidak ada endpoint pemulihan khusus; untuk melakukan rollback, ambil versi yang Anda inginkan dan tulis kembali content-nya dengan memories.update (atau memories.create jika memori induknya telah dihapus, asalkan versi yang Anda inginkan masih disimpan).

Versi memori lama mungkin dihapus setelah 30 hari. Untuk mempertahankan riwayat memori lebih lama, ekspor versi melalui API.

Mendaftar versi

Daftar riwayat versi untuk sebuah store, yang terbaru lebih dulu. Contoh berikut memfilter ke riwayat satu memori:

bash

  curl -s "https://haijun.my.id/v1/memory_stores/$store_id/memory_versions?memory_id=$mem_id" \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "juglow-beta: agent-memory-2026-07-22"

bash

  ant beta:memory-stores:memory-versions list \
    --memory-store-id "$store_id" \
    --memory-id "$mem_id" \
    --format json

python

  versions = client.beta.memory_stores.memory_versions.list(
      store.id,
      memory_id=mem.id,
  )
  for version in versions:
      print(f"{version.id}: {version.operation}")

  version_id = versions.data[1].id

typescript

  const versions = await client.beta.memoryStores.memoryVersions.list(store.id, {
    memory_id: mem.id
  });
  for await (const v of versions) {
    console.log(`${v.id}: ${v.operation}`);
  }

  const versionId = versions.data[1].id;

csharp

  var versions = await client.Beta.MemoryStores.MemoryVersions.List(store.ID, new()
  {
      MemoryID = mem.ID,
  });
  var versionIds = new List<string>();
  await foreach (var v in versions.Paginate())
  {
      Console.WriteLine($"{v.ID}: {v.Operation.Raw()}");
      versionIds.Add(v.ID);
  }

  var versionId = versionIds[1];

  versions := client.Beta.MemoryStores.MemoryVersions.ListAutoPaging(ctx, store.ID, juglow.BetaMemoryStoreMemoryVersionListParams{
  	MemoryID: juglow.String(mem.ID),
  })
  for versions.Next() {
  	v := versions.Current()
  	fmt.Printf("%s: %s\n", v.ID, v.Operation)
  }
  if err := versions.Err(); err != nil {
  	panic(err)
  }

  vpage, err := client.Beta.MemoryStores.MemoryVersions.List(ctx, store.ID, juglow.BetaMemoryStoreMemoryVersionListParams{
  	MemoryID: juglow.String(mem.ID),
  })
  if err != nil {
  	panic(err)
  }
  versionID := vpage.Data[1].ID

java

  var versions = client.beta().memoryStores().memoryVersions().list(
      store.id(),
      MemoryVersionListParams.builder().memoryId(mem.id()).build()
  );
  for (var v : versions.autoPager()) {
      IO.println(v.id() + ": " + v.operation());
  }

  var versionId = versions.data().get(1).id();

php

  $versions = $client->beta->memoryStores->memoryVersions->list(
      $store->id,
      memoryID: $mem->id,
  );
  foreach ($versions->pagingEachItem() as $v) {
      echo "{$v->id}: {$v->operation}\n";
  }

  $versionId = $versions->data[1]->id;

ruby

  versions = client.beta.memory_stores.memory_versions.list(
    store.id,
    memory_id: mem.id
  )
  versions.auto_paging_each do |version|
    puts "#{version.id}: #{version.operation}"
  end

  version_id = versions.data[1].id

Lihat referensi List memory versions untuk parameter lengkap dan skema respons.

Mengambil versi

Mengambil versi individual mengembalikan field yang sama dengan respons daftar ditambah isi content lengkap.

bash

  curl -s "https://haijun.my.id/v1/memory_stores/$store_id/memory_versions/$version_id" \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "juglow-beta: agent-memory-2026-07-22"

bash

  ant beta:memory-stores:memory-versions retrieve \
    --memory-store-id "$store_id" \
    --memory-version-id "$version_id"

python

  version = client.beta.memory_stores.memory_versions.retrieve(
      version_id,
      memory_store_id=store.id,
  )
  print(version.content)

typescript

  const version = await client.beta.memoryStores.memoryVersions.retrieve(versionId, {
    memory_store_id: store.id
  });
  console.log(version.content);

csharp

  var version = await client.Beta.MemoryStores.MemoryVersions.Retrieve(versionId, new()
  {
      MemoryStoreID = store.ID,
  });
  Console.WriteLine(version.Content);

  version, err := client.Beta.MemoryStores.MemoryVersions.Get(ctx, versionID, juglow.BetaMemoryStoreMemoryVersionGetParams{
  	MemoryStoreID: store.ID,
  })
  if err != nil {
  	panic(err)
  }
  fmt.Println(version.Content)

java

  var version = client.beta().memoryStores().memoryVersions().retrieve(
      versionId,
      MemoryVersionRetrieveParams.builder().memoryStoreId(store.id()).build()
  );
  IO.println(version.content().orElseThrow());

php

  $version = $client->beta->memoryStores->memoryVersions->retrieve(
      $versionId,
      memoryStoreID: $store->id,
  );
  echo "{$version->content}\n";

ruby

  version = client.beta.memory_stores.memory_versions.retrieve(
    version_id,
    memory_store_id: store.id
  )
  puts version.content

Lihat referensi Retrieve a memory version untuk parameter lengkap dan skema respons.

Meredaksi versi

Redact membersihkan konten dari versi historis sambil mempertahankan jejak audit (siapa melakukan apa, kapan). Gunakan untuk alur kerja kepatuhan seperti menghapus rahasia yang bocor, PII, atau permintaan penghapusan dari pengguna.

Versi yang merupakan head saat ini dari memori yang masih aktif tidak dapat diredaksi. Tulis versi baru terlebih dahulu (atau hapus memorinya), lalu redaksi versi lama.

bash

  curl -s -X POST "https://haijun.my.id/v1/memory_stores/$store_id/memory_versions/$version_id/redact" \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "juglow-beta: agent-memory-2026-07-22" \
    -H "content-type: application/json" \
    -d '{}'

bash

  ant beta:memory-stores:memory-versions redact \
    --memory-store-id "$store_id" \
    --memory-version-id "$version_id"

python

  client.beta.memory_stores.memory_versions.redact(
      version_id,
      memory_store_id=store.id,
  )

typescript

  await client.beta.memoryStores.memoryVersions.redact(versionId, {
    memory_store_id: store.id
  });

csharp

  await client.Beta.MemoryStores.MemoryVersions.Redact(versionId, new()
  {
      MemoryStoreID = store.ID,
  });

  _, err = client.Beta.MemoryStores.MemoryVersions.Redact(ctx, versionID, juglow.BetaMemoryStoreMemoryVersionRedactParams{
  	MemoryStoreID: store.ID,
  })
  if err != nil {
  	panic(err)
  }

java

  client.beta().memoryStores().memoryVersions().redact(
      versionId,
      MemoryVersionRedactParams.builder().memoryStoreId(store.id()).build()
  );

php

  $client->beta->memoryStores->memoryVersions->redact(
      $versionId,
      memoryStoreID: $store->id,
  );

ruby

  client.beta.memory_stores.memory_versions.redact(
    version_id,
    memory_store_id: store.id
  )

Lihat referensi Redact a memory version untuk parameter lengkap dan skema respons.

Mengelola memory store

Selain create, memory store mendukung retrieve, update, list, archive, dan delete.

Mendaftar store

Daftar store dalam workspace. Store yang diarsipkan dikecualikan secara default; teruskan include_archived: true untuk menyertakannya.

bash

  curl -s "https://haijun.my.id/v1/memory_stores?include_archived=true" \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "juglow-beta: agent-memory-2026-07-22"

bash

  ant beta:memory-stores list --include-archived

python

  for memory_store in client.beta.memory_stores.list(include_archived=True):
      print(memory_store.id, memory_store.name, memory_store.archived_at)

typescript

  for await (const s of client.beta.memoryStores.list({ include_archived: true })) {
    console.log(s.id, s.name, s.archived_at);
  }

csharp

  var stores = await client.Beta.MemoryStores.List(new() { IncludeArchived = true });
  await foreach (var s in stores.Paginate())
  {
      Console.WriteLine($"{s.ID} {s.Name} {s.ArchivedAt}");
  }

  stores := client.Beta.MemoryStores.ListAutoPaging(ctx, juglow.BetaMemoryStoreListParams{
  	IncludeArchived: juglow.Bool(true),
  })
  for stores.Next() {
  	s := stores.Current()
  	fmt.Println(s.ID, s.Name, s.ArchivedAt)
  }
  if err := stores.Err(); err != nil {
  	panic(err)
  }

java

  for (var s : client.beta().memoryStores().list(
      MemoryStoreListParams.builder().includeArchived(true).build()
  ).autoPager()) {
      IO.println(s.id() + " " + s.name() + " " + s.archivedAt());
  }

php

  foreach ($client->beta->memoryStores->list(includeArchived: true)->pagingEachItem() as $s) {
      // archivedAt hanya diatur pada penyimpanan yang diarsipkan.
      $archivedAt = isset($s->archivedAt) ? $s->archivedAt->format(DATE_ATOM) : '';
      echo "{$s->id} {$s->name} {$archivedAt}\n";
  }

ruby

  client.beta.memory_stores.list(include_archived: true).auto_paging_each do |memory_store|
    puts "#{memory_store.id} #{memory_store.name} #{memory_store.archived_at}"
  end

Lihat referensi List memory stores untuk parameter lengkap dan skema respons.

Mengarsipkan store

Pengarsipan membuat store menjadi read-only dan mencegahnya dilampirkan ke sesi baru. Pengarsipan bersifat satu arah; tidak ada pembatalan arsip.

bash

  curl -s -X POST "https://haijun.my.id/v1/memory_stores/$store_id/archive" \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "juglow-beta: agent-memory-2026-07-22" > /dev/null

bash

  ant beta:memory-stores archive --memory-store-id "$store_id"

python

  client.beta.memory_stores.archive(store.id)

typescript

  await client.beta.memoryStores.archive(store.id);

csharp

  await client.Beta.MemoryStores.Archive(store.ID);

  _, err = client.Beta.MemoryStores.Archive(ctx, store.ID, juglow.BetaMemoryStoreArchiveParams{})
  if err != nil {
  	panic(err)
  }

java

  client.beta().memoryStores().archive(store.id());

php

  $client->beta->memoryStores->archive($store->id);

ruby

  client.beta.memory_stores.archive(store.id)

Lihat referensi Archive a memory store untuk parameter lengkap dan skema respons.

Untuk menghapus store secara permanen beserta semua memori dan versinya, gunakan memory_stores.delete.

Praktik terbaik untuk pengelolaan memori

Ketika sebuah store mencapai batas 10.000 memori, penulisan ke memori baru akan gagal: baik panggilan memories.create langsung maupun penulisan file oleh agen ke path yang belum terpetakan. Memori yang sudah ada tetap dapat dibaca dan diedit. Praktik-praktik berikut membantu Anda tetap jauh di bawah batas dan pulih dengan baik jika Anda mencapainya.

Gunakan store yang terfokus. Alih-alih satu store besar serbaguna, gunakan store yang lebih kecil dan dibuat untuk tujuan tertentu: satu per pengguna, satu untuk pengetahuan domain bersama, dan satu untuk konteks khusus proyek. Setiap store memiliki batas 10.000 memorinya sendiri, sehingga menjaga cakupan store tetap terbatas mengurangi kemungkinan salah satunya penuh.

Ringkas atau pangkas sebelum store penuh. Hapus memori yang usang atau redundan dengan memories.delete. Anda juga dapat menjalankan sesi dreaming, yang mengonsolidasikan konten yang terfragmentasi ke dalam store output baru yang terpisah alih-alih memodifikasi store aslinya. Alihkan sesi Anda ke store output tersebut, lalu arsipkan atau hapus store aslinya.

Lampirkan store baru bila masuk akal. Jika sebuah store telah tumbuh melampaui cakupan kegunaannya, lampirkan store baru untuk konten baru dan lampirkan store asli dengan akses read_only. Agen dapat membaca dari keduanya sambil hanya menulis ke store yang baru.

Batasi akses tulis bila sesuai. Sesi yang hanya membaca materi referensi bersama tidak memerlukan read_write. Menjaga akses tulis terbatas pada sesi yang benar-benar menambahkan memori baru memudahkan pelacakan dari mana pertumbuhan berasal.

#Ikhtisar

#Membuat memory store

#Mengisinya dengan konten awal (opsional)

#Melampirkan memory store ke sesi

#Bagaimana agen mengakses memori

#Melihat dan mengedit memori

#Mendaftar memori

#Membaca memori

#Membuat memori

#Memperbarui memori

#Pengeditan konten yang aman (optimistic concurrency)

#Menghapus memori

#Mengaudit perubahan memori

#Mendaftar versi

#Mengambil versi

#Meredaksi versi

#Mengelola memory store

#Mendaftar store

#Mengarsipkan store

#Praktik terbaik untuk pengelolaan memori

Ikhtisar

Membuat memory store

Mengisinya dengan konten awal (opsional)

Melampirkan memory store ke sesi

Bagaimana agen mengakses memori

Melihat dan mengedit memori

Mendaftar memori

Membaca memori

Membuat memori

Memperbarui memori

Pengeditan konten yang aman (optimistic concurrency)

Menghapus memori

Mengaudit perubahan memori

Mendaftar versi

Mengambil versi

Meredaksi versi

Mengelola memory store

Mendaftar store

Mengarsipkan store

Praktik terbaik untuk pengelolaan memori