API Memory Storage: Spesifikasi, parameter, dan persyaratan cakupan - Tablestore

Layanan Memory Storage menyediakan 13 API melalui protokol HTTP JSON untuk manajemen penyimpanan memori, pembacaan dan penulisan memori jangka panjang serta memori jangka pendek, dan kueri audit—memungkinkan integrasi kustom tanpa SDK.

Daftar API

API berikut dikelompokkan berdasarkan fungsinya.

Manajemen penyimpanan memori

API	Deskripsi
`CreateMemoryStore`	Membuat penyimpanan memori.
`GetMemoryStore`	Mengambil detail penyimpanan memori.
`UpdateMemoryStore`	Memperbarui deskripsi penyimpanan memori.
`DeleteMemoryStore`	Menghapus penyimpanan memori.
`ListMemoryStores`	Menampilkan daftar penyimpanan memori.

Memori jangka panjang

API	Deskripsi
`AddMemories`	Menambahkan pesan percakapan atau teks dan menghasilkan memori jangka panjang.
`SearchMemories`	Mencari memori jangka panjang.
`ListMemories`	Menampilkan daftar memori jangka panjang.
`GetMemory`	Mengambil memori jangka panjang.
`UpdateMemory`	Memperbarui memori jangka panjang.
`DeleteMemory`	Menghapus memori jangka panjang.

Memori jangka pendek dan audit

API	Deskripsi
`ListMemoryStoreMessages`	Menanyakan memori jangka pendek (pesan sesi mentah).
`ListMemoryStoreRequests`	Menanyakan catatan audit permintaan penyimpanan memori.

Objek umum

API penyimpanan memori menggunakan kembali struktur data berikut dalam permintaan dan respons.

Scope

Scope merepresentasikan hierarki kepemilikan data memori dan terdiri dari empat bidang.

Parameter	Tipe	Deskripsi
`appId`	string	ID aplikasi.
`tenantId`	string	ID penyewa atau pengguna.
`agentId`	string	ID Agent.
`runId`	string	ID sesi, run, atau tugas.

Persyaratan bidang Scope dan dukungan karakter wildcard * bervariasi tergantung pada API.

Skenario	Bidang yang wajib	Aturan wildcard `*`
Penulisan (`AddMemories`)	`appId`	Jika bidang opsional kosong, nilai default-nya adalah `__default__`. Karakter wildcard `*` tidak diizinkan.
Pencarian memori jangka panjang (`SearchMemories`)	`appId`, `tenantId`	Karakter wildcard `*` dapat digunakan untuk `agentId` dan `runId`.
Kueri memori jangka pendek (`ListMemoryStoreMessages`)	Keempat bidang Scope wajib diisi.	Karakter wildcard `*` tidak diizinkan.
Mengambil, memperbarui, atau menghapus satu memori jangka panjang (`GetMemory`, `UpdateMemory`, `DeleteMemory`)	Keempat bidang Scope wajib diisi.	Karakter wildcard `*` tidak diizinkan.
Kueri daftar (`ListMemories`, `ListMemoryStoreRequests`)	`appId`	Karakter wildcard `*` dapat digunakan secara hierarkis.

Contoh:

{
  "appId": "app-001",
  "tenantId": "user-001",
  "agentId": "assistant",
  "runId": "session-001"
}

Message

Untuk API AddMemories, bidang messages menggunakan struktur berikut.

Parameter	Tipe	Wajib	Deskripsi
`role`	string	Ya	Peran pesan, seperti `user`, `assistant`, atau `system`.
`content`	string	Ya	Isi pesan.
`messageId`	string	Tidak	ID pesan. Panjang maksimum: 256 karakter.
`timestamp`	string	Tidak	Timestamp dalam format RFC3339.
`metadata`	object	Tidak	Metadata tingkat pesan. Baik kunci maupun nilai berupa string.

Metadata

Metadata terdiri dari pasangan kunci-nilai string yang berfungsi sebagai tag bisnis. API pencarian menggunakan metadata ini untuk penyaringan kecocokan eksak.

Batas	Nilai
Jumlah maksimum kunci per permintaan	16
Panjang maksimum kunci	64 karakter
Panjang maksimum nilai	1024 karakter

Contoh:

{
  "source": "chat",
  "topic": "preference"
}

CreateMemoryStore

Membuat penyimpanan memori.

Parameter permintaan

Parameter	Tipe	Wajib	Deskripsi
`memoryStoreName`	string	Ya	Nama penyimpanan memori. Panjangnya tidak boleh lebih dari 32 karakter dan hanya boleh berisi huruf, angka, serta garis bawah (_).
`description`	string	Tidak	Deskripsi opsional penyimpanan memori, dengan panjang maksimum 1024 karakter.

Contoh permintaan

{
  "memoryStoreName": "agent_memory",
  "description": "Long-term memory store for the agent"
}

GetMemoryStore

Mengembalikan detail penyimpanan memori.

Parameter permintaan

Parameter	Tipe	Wajib	Deskripsi
`memoryStoreName`	string	true	Nama penyimpanan memori.

Contoh permintaan

{
  "memoryStoreName": "agent_memory"
}

UpdateMemoryStore

Memperbarui deskripsi penyimpanan memori.

Parameter permintaan

Parameter	Tipe	Wajib	Deskripsi
`memoryStoreName`	string	Ya	Nama penyimpanan memori.
`description`	string	Ya	Deskripsi baru, dengan panjang maksimum 1024 karakter.

DeleteMemoryStore

Menghapus penyimpanan memori.

Peringatan

Ini adalah operasi yang tidak dapat dikembalikan dan akan menghapus permanen penyimpanan memori beserta seluruh datanya. Gunakan dengan hati-hati di lingkungan produksi.

Parameter permintaan

Parameter	Jenis	Wajib	Deskripsi
`memoryStoreName`	string	Ya	Nama penyimpanan memori yang akan dihapus.

ListMemoryStores

Menampilkan daftar penyimpanan memori.

Parameter permintaan

Parameter	Jenis	Wajib	Deskripsi
`limit`	int	Tidak	Jumlah penyimpanan memori yang dikembalikan.
`nextToken`	string	Tidak	Token untuk mengambil halaman hasil berikutnya.

AddMemories

Menulis pesan dialog atau teks. Layanan menyimpan pesan asli sebagai memori jangka pendek dan mengekstraksi memori jangka panjang dari input tersebut.

Parameter permintaan

Parameter	Tipe	Wajib	Deskripsi
`memoryStoreName`	string	Ya	Nama penyimpanan memori tujuan.
`scope`	object	Ya	Scope. Untuk operasi tulis, `appId` wajib diisi, dan wildcard `*` tidak diizinkan.
`messages`	array	Wajib jika `text` tidak disediakan	Array pesan dialog. Maksimal 20 pesan, dengan total panjang konten hingga 32.000 karakter.
`text`	string	Wajib jika `messages` tidak disediakan	Isi teks. Panjang maksimum: 32.000 karakter.
`metadata`	object	Tidak	Metadata untuk operasi tulis. Maksimal 16 pasangan kunci-nilai. Panjang kunci dibatasi hingga 64 karakter, dan nilai hingga 1.024 karakter.
`sync`	boolean	Tidak	Menentukan apakah harus menunggu ekstraksi memori selesai secara sinkron. Nilai default-nya adalah `false`.

Untuk daftar lengkap batasan, lihat Batasan dan Catatan.

Contoh permintaan: tambahkan pesan

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "messages": [
    {
      "role": "user",
      "content": "I like coffee"
    },
    {
      "role": "assistant",
      "content": "Okay, I'll remember that."
    }
  ],
  "metadata": {
    "source": "chat"
  },
  "sync": true
}

Contoh permintaan: tambahkan teks

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001"
  },
  "text": "The user likes coffee and prefers concise answers."
}

Parameter respons

Parameter	Deskripsi
`requestId`	ID permintaan.
`status`	Status permintaan. Operasi tulis asinkron biasanya mengembalikan `running`.
`acceptedMessages`	Jumlah pesan yang diterima.
`scope`	Scope yang digunakan untuk operasi tulis.
`memoryStoreName`	Nama penyimpanan memori.
`memcellsCreated`	Hanya dikembalikan untuk operasi tulis sinkron. Jumlah memcell yang dibuat.
`unitsCreated`	Hanya dikembalikan untuk operasi tulis sinkron. Jumlah unit memori jangka panjang yang dibuat.

SearchMemories

Mengambil memori jangka panjang.

Parameter permintaan

Parameter	Type	Wajib	Deskripsi
`memoryStoreName`	string	Ya	Nama penyimpanan memori tujuan.
`query`	string	Ya	Teks kueri.
`scope`	object	Ya	Scope. Saat melakukan pengambilan, Anda harus memberikan `appId` dan `tenantId`. Untuk `agentId` dan `runId`, Anda dapat menggunakan wildcard `*`.
`topK`	int	Tidak	Jumlah item yang dikembalikan, dengan nilai default `10` dan rentang nilai `1 hingga 50`.
`enableRerank`	boolean	Tidak	Menentukan apakah Rerank diaktifkan. Nilai default-nya adalah `true`.
`metadata`	object	Tidak	Filter metadata untuk kueri kecocokan eksak. Baik kunci maupun nilai berupa string.

Untuk deskripsi lengkap batas atas topK, lihat Batasan dan Catatan.

Contoh permintaan

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "*",
    "runId": "*"
  },
  "query": "What drinks does the user like?",
  "topK": 5,
  "enableRerank": true,
  "metadata": {
    "source": "chat"
  }
}

Bidang respons

Bidang	Deskripsi
`results`	Daftar hasil pencarian.
`results[].unit`	Unit memori jangka panjang. Lihat tabel di bawah untuk deskripsi bidang-bidangnya.
`results[].score`	Skor relevansi.
`scope`	Scope yang digunakan untuk kueri.
`memoryStoreName`	Nama penyimpanan memori.

Bidang internal results[].unit adalah sebagai berikut.

Bidang	Deskripsi
`id`	ID unit memori jangka panjang.
`conversation_key`	Kunci percakapan terkait.
`scope`	Scope memori adalah objek dengan empat bidang: `appId`, `tenantId`, `agentId`, dan `runId`.
`memcell_id`	ID sel memori.
`unit_type`	Tipe unit memori.
`text`	Teks memori.
`search_text`	Teks yang digunakan untuk pengambilan.
`source_turn_ids`	Daftar ID pesan sumber.
`type_label`	Label tipe.
`date_bucket`	Bucket tanggal.
`metadata_json`	Metadata, dalam bentuk string JSON.
`deleted`	Menunjukkan apakah unit tersebut telah dihapus.
`created_at`	Waktu pembuatan.
`salience`	Skor salience.
`version`	Nomor versi.

ListMemories

Menampilkan daftar memori jangka panjang.

Parameter permintaan

Parameter	Tipe	Wajib	Deskripsi
`memoryStoreName`	string	Ya	Nama penyimpanan memori.
`scope`	object	Ya	Scope. `appId` dan `tenantId` wajib diisi. Anda dapat menggunakan karakter wildcard `*` untuk `agentId` dan `runId`.
`limit`	int	Tidak	Jumlah maksimum memori jangka panjang yang dikembalikan.
`nextToken`	string	Tidak	Token untuk mengambil halaman hasil berikutnya.

Contoh permintaan

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "*",
    "agentId": "*",
    "runId": "*"
  },
  "limit": 20
}

GetMemory

Mengambil satu memori jangka panjang.

Parameter permintaan

Parameter	Tipe	Wajib	Deskripsi
`memoryStoreName`	string	Ya	Nama penyimpanan memori.
`memoryId`	string	Ya	ID memori.
`scope`	object	Ya	Untuk Scope lengkap, keempat bidang wajib diisi, dan karakter wildcard `*` tidak diizinkan.

UpdateMemory

Memperbarui satu memori jangka panjang. Anda harus menyertakan setidaknya salah satu dari text atau metadata.

Parameter permintaan

Parameter	Tipe	Wajib	Deskripsi
`memoryStoreName`	string	Ya	Nama penyimpanan memori.
`memoryId`	string	Ya	ID memori.
`scope`	object	Ya	Untuk Scope lengkap, keempat bidang wajib diisi, dan karakter wildcard `*` tidak diizinkan.
`text`	string	Tidak	Teks memori baru.
`metadata`	object	Tidak	Metadata baru.

DeleteMemory

Menghapus satu item memori jangka panjang.

Peringatan

Menghapus item memori jangka panjang adalah operasi yang tidak dapat dikembalikan. Lakukan dengan hati-hati di lingkungan produksi.

Parameter permintaan

Parameter	Tipe	Wajib	Deskripsi
`memoryStoreName`	string	Ya	Nama penyimpanan memori.
`memoryId`	string	Ya	ID memori.
`scope`	object	Ya	Scope lengkap memerlukan keempat bidang dan tidak mengizinkan karakter wildcard `*`.

ListMemoryStoreMessages

Menampilkan daftar pesan sesi mentah dari memori jangka pendek.

Parameter permintaan

Parameter	Tipe	Wajib	Deskripsi
`memoryStoreName`	string	Ya	Nama penyimpanan memori.
`scope`	object	Ya	Untuk Scope lengkap, keempat bidang wajib diisi, dan wildcard seperti `*` tidak diizinkan.
`limit`	int	Tidak	Jumlah maksimum pesan yang dikembalikan.
`nextToken`	string	Tidak	Token untuk halaman hasil berikutnya.
`minTimestamp`	string	Tidak	Timestamp minimum, dalam format RFC3339.
`maxTimestamp`	string	Tidak	Timestamp maksimum, dalam format RFC3339.

Contoh permintaan

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "limit": 100
}

ListMemoryStoreRequests

Menanyakan catatan audit permintaan untuk penyimpanan memori.

Parameter permintaan

Parameter	Type	Wajib	Deskripsi
`memoryStoreName`	string	Ya	Nama penyimpanan memori.
`scope`	object	Ya	Scope. Anda dapat menggunakan wildcard `*` secara hierarkis.
`operation`	string	Tidak	Nama operasi, seperti `AddMemories` atau `SearchMemories`.
`limit`	int	Tidak	Jumlah maksimum catatan yang dikembalikan.
`nextToken`	string	Tidak	Token untuk halaman hasil berikutnya.
`minTimestamp`	string	Tidak	Timestamp minimum, dalam format RFC 3339.
`maxTimestamp`	string	Tidak	Timestamp maksimum, dalam format RFC 3339.

Contoh permintaan

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "*",
    "agentId": "*",
    "runId": "*"
  },
  "operation": "AddMemories",
  "limit": 50
}

Parameter respons

Parameter	Deskripsi
`requestId`	ID permintaan.
`operation`	Nama operasi.
`scope`	Scope permintaan.
`requestSummary`	Ringkasan permintaan.
`responseStatus`	Status respons.
`latencyMs`	Latensi dalam milidetik.
`targetId`	ID target operasi, seperti ID memori.
`createdAt`	Waktu saat catatan dibuat.