> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs-dev.band.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-dev.band.ai/_mcp/server. # List memories GET https://api.dev.band.ai/api/v1/agent/memories Lists memories accessible to the agent. Two independent dimensions: - `memory_scope` — WHOSE memories. `me` (default) returns only the memories this agent stored, whatever their scope. `org` returns the organization's shared memories, and is rejected with 422 when the agent belongs to no organization. - `scope` — WHICH category. Omitted at `memory_scope=me` it does not narrow at all. Omitted at `memory_scope=org` it means `organization`: an org-wide read returns the organization's shared knowledge, never subject-scoped memories about unrelated people. A subject is reachable only by passing `scope=subject` with its `subject_id`. Another agent's `agent`-scoped memories are never returned, at any `memory_scope`. Use `content_query` for full-text search across memory content. **Pagination:** Use `cursor` + `limit` (recommended) OR `page` + `page_size` (deprecated, sunset 2026-10-01). Do NOT mix families. Reference: https://docs-dev.band.ai/api/agent-api/agent-api-memories/list-agent-memories ## Authentication - `X-API-Key` header (required) — Enter your API key for programmatic access ## Request ### Query parameters - `cursor` (string, optional) — Opaque cursor for keyset pagination - `limit` (integer, optional) — Max results per request (1-100, default 20) - `page` (integer, optional, deprecated) — Page number (offset pagination) - DEPRECATED - `subject_id` (string, optional) — Filter by subject UUID (required for subject-scoped queries) - `scope` (string, optional) — Filter by scope: agent, subject, organization, or all - `memory_scope` (enum, optional) — Whose memories to return: 'me' (default, this agent only) or 'org' (all agents in the organization) - Allowed values: `me`, `org` - `system` (string, optional) — Filter by memory system - `type` (string, optional) — Filter by memory type - `segment` (string, optional) — Filter by segment - `content_query` (string, optional) — Full-text search query - `page_size` (integer, optional, deprecated) — Number of results per page (max 50) - DEPRECATED - `status` (string, optional) — Filter by status: active, superseded, archived, or all ## Response ### 200 Memories - `data` (list of AgentMemory, optional) - `meta` (ApiV1AgentMemoriesGetResponsesContentApplicationJsonSchemaMeta, optional) — Pagination metadata (cursor fields on the keyset path, offset fields on the deprecated path) - `metadata` (ApiV1AgentMemoriesGetResponsesContentApplicationJsonSchemaMetadata, optional) — Pagination metadata (cursor fields on the keyset path, offset fields on the deprecated path) ## Errors ### 401 Unauthorized Error Unauthorized - `error` (ErrorError, required) ### 422 Unprocessable Entity Error Invalid pagination params (invalid/unsupported cursor, or mixed cursor + offset families) - `error` (ErrorError, required) ## Types ### AgentMemory A memory entry stored by an agent - `content` (string, required) — The memory content - `id` (string, required) — Memory ID - `inserted_at` (string, required) — When the memory was created - `scope` (enum, required) — Visibility scope of the memory - Allowed values: `agent`, `subject`, `organization` - `segment` (enum, required) — Logical segment of the memory - Allowed values: `user`, `agent`, `tool`, `guideline` - `system` (enum, required) — Memory system tier - Allowed values: `sensory`, `working`, `long_term` - `type` (enum, required) — Memory type within the system - Allowed values: `iconic`, `echoic`, `haptic`, `episodic`, `semantic`, `procedural` - `metadata` (AgentMemoryMetadata, optional, nullable) — Additional metadata - `organization_id` (string, optional, nullable) — Organization this memory is shared within. Null for an `agent`-scoped memory, whose audience is one agent rather than an organization, and for any memory stored by an agent that belongs to none. - `source_agent_id` (string, optional, nullable) — UUID of the agent that stored this memory. Null once that agent is deleted — the column is `on_delete: :nilify_all`, so the memory outlives its author. - `status` (enum, optional) — Memory lifecycle status - Allowed values: `active`, `superseded`, `archived` - `subject_id` (string, optional, nullable) — UUID of the subject this memory is about (user or agent) - `thought` (string, optional, nullable) — Agent's reasoning for storing this memory ### ApiV1AgentMemoriesGetResponsesContentApplicationJsonSchemaMeta Pagination metadata (cursor fields on the keyset path, offset fields on the deprecated path) - `has_more` (boolean, optional) — Whether more results exist beyond this page (cursor pagination) - `limit` (integer, optional) — Max results requested (cursor pagination) - `next_cursor` (string, optional, nullable) — Opaque cursor for the next page; null when there are no more results (cursor pagination) - `page` (integer, optional) — Current page number (offset pagination) - `page_size` (integer, optional) — Number of results per page (offset pagination) - `total_count` (integer, optional) — Total number of matching memories (offset pagination) - `total_pages` (integer, optional) — Total number of pages (offset pagination) ### ApiV1AgentMemoriesGetResponsesContentApplicationJsonSchemaMetadata Pagination metadata (cursor fields on the keyset path, offset fields on the deprecated path) - `has_more` (boolean, optional) — Whether more results exist beyond this page (cursor pagination) - `limit` (integer, optional) — Max results requested (cursor pagination) - `next_cursor` (string, optional, nullable) — Opaque cursor for the next page; null when there are no more results (cursor pagination) - `page` (integer, optional) — Current page number (offset pagination) - `page_size` (integer, optional) — Number of results per page (offset pagination) - `total_count` (integer, optional) — Total number of matching memories (offset pagination) - `total_pages` (integer, optional) — Total number of pages (offset pagination) ### ErrorError - `code` (string, required) — Machine-readable error code - `message` (string, required) — Human-readable error message - `request_id` (string, required) — Unique request identifier for tracing and debugging - `details` (ErrorErrorDetails, optional) — Additional error details (optional) ### AgentMemoryMetadata Additional metadata ### ErrorErrorDetails Additional error details (optional) ## Examples **Response** ```json { "data": [ { "content": "string", "id": "string", "inserted_at": "2024-01-15T09:30:00Z", "scope": "agent", "segment": "user", "system": "sensory", "type": "iconic", "metadata": {}, "organization_id": "string", "source_agent_id": "string", "status": "active", "subject_id": "string", "thought": "string" } ], "meta": { "has_more": true, "limit": 1, "next_cursor": "string", "page": 1, "page_size": 1, "total_count": 1, "total_pages": 1 }, "metadata": { "has_more": true, "limit": 1, "next_cursor": "string", "page": 1, "page_size": 1, "total_count": 1, "total_pages": 1 } } ``` **SDK Code** ```python import requests url = "https://api.dev.band.ai/api/v1/agent/memories" querystring = {"content_query":"prefers SUV","cursor":"eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJpIjoiNTUwZTg0MDAifQ","limit":"20","memory_scope":"me","page":"1","page_size":"20","scope":"subject","segment":"user","status":"active","subject_id":"daca00d0-eb6b-4db1-8201-c46015c93d04","system":"long_term","type":"semantic"} headers = {"X-API-Key": ""} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.dev.band.ai/api/v1/agent/memories?content_query=prefers+SUV&cursor=eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJpIjoiNTUwZTg0MDAifQ&limit=20&memory_scope=me&page=1&page_size=20&scope=subject&segment=user&status=active&subject_id=daca00d0-eb6b-4db1-8201-c46015c93d04&system=long_term&type=semantic'; const options = {method: 'GET', headers: {'X-API-Key': ''}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.dev.band.ai/api/v1/agent/memories?content_query=prefers+SUV&cursor=eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJpIjoiNTUwZTg0MDAifQ&limit=20&memory_scope=me&page=1&page_size=20&scope=subject&segment=user&status=active&subject_id=daca00d0-eb6b-4db1-8201-c46015c93d04&system=long_term&type=semantic" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("X-API-Key", "") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.dev.band.ai/api/v1/agent/memories?content_query=prefers+SUV&cursor=eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJpIjoiNTUwZTg0MDAifQ&limit=20&memory_scope=me&page=1&page_size=20&scope=subject&segment=user&status=active&subject_id=daca00d0-eb6b-4db1-8201-c46015c93d04&system=long_term&type=semantic") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["X-API-Key"] = '' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.dev.band.ai/api/v1/agent/memories?content_query=prefers+SUV&cursor=eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJpIjoiNTUwZTg0MDAifQ&limit=20&memory_scope=me&page=1&page_size=20&scope=subject&segment=user&status=active&subject_id=daca00d0-eb6b-4db1-8201-c46015c93d04&system=long_term&type=semantic") .header("X-API-Key", "") .asString(); ``` ```php request('GET', 'https://api.dev.band.ai/api/v1/agent/memories?content_query=prefers+SUV&cursor=eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJpIjoiNTUwZTg0MDAifQ&limit=20&memory_scope=me&page=1&page_size=20&scope=subject&segment=user&status=active&subject_id=daca00d0-eb6b-4db1-8201-c46015c93d04&system=long_term&type=semantic', [ 'headers' => [ 'X-API-Key' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.dev.band.ai/api/v1/agent/memories?content_query=prefers+SUV&cursor=eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJpIjoiNTUwZTg0MDAifQ&limit=20&memory_scope=me&page=1&page_size=20&scope=subject&segment=user&status=active&subject_id=daca00d0-eb6b-4db1-8201-c46015c93d04&system=long_term&type=semantic"); var request = new RestRequest(Method.GET); request.AddHeader("X-API-Key", ""); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["X-API-Key": ""] let request = NSMutableURLRequest(url: NSURL(string: "https://api.dev.band.ai/api/v1/agent/memories?content_query=prefers+SUV&cursor=eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJpIjoiNTUwZTg0MDAifQ&limit=20&memory_scope=me&page=1&page_size=20&scope=subject&segment=user&status=active&subject_id=daca00d0-eb6b-4db1-8201-c46015c93d04&system=long_term&type=semantic")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```