> 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 for current user GET https://api.dev.band.ai/api/v1/me/memories Lists memories accessible to the authenticated user: - Memories about the user (subject_id = user's UUID) - Organization-scoped memories in the user's organization - The `agent`-scoped private memories of the agents this user owns, which carry no organization and so come back with `organization_id: null` - Optionally filter by chat room to see room-level memories Unlike agents, users can see memories from ALL agents in their organization that are about them or in rooms they participate in. Another owner's agents' private memories are never returned. **Pagination:** Use `cursor` + `limit` (recommended) OR `page` + `page_size` (deprecated, sunset 2026-10-01). Do NOT mix families. **Display fields:** each row carries `subject_name`, `subject_type`, `source_agent_name`, `chat_room_title`, `chat_room_status` and `chat_room_type` next to the raw ids, so a table can be labelled without a follow-up request per row. They are resolved once for the whole page. Every one of them is nullable: a referent that was deleted, or that the caller may not see, reads as null while its id is still returned. Reference: https://docs-dev.band.ai/api/human-api/human-api-memories/list-user-memories ## Authentication - `X-API-Key` header (required) — Enter your API key for programmatic access - `Authorization` header (bearer token, required) — Enter your JWT token (without the 'Bearer ' prefix) ## 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 - `chat_room_id` (string, optional) — Filter by chat room ID - `scope` (string, optional) — Filter scope: about_me, organization, room, all - `system` (string, optional) — Filter by memory system - `type` (string, optional) — Filter by memory type - `segment` (string, optional) — Filter by segment - `source_agent_id` (string, optional) — Filter by the agent that stored the memory - `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 User Memories - `data` (list of UserMemory, optional) - `meta` (ApiV1MeMemoriesGetResponsesContentApplicationJsonSchemaMeta, optional) — Pagination metadata (cursor fields on the keyset path, offset fields on the deprecated path) - `metadata` (ApiV1MeMemoriesGetResponsesContentApplicationJsonSchemaMetadata, optional) — Pagination metadata (cursor fields on the keyset path, offset fields on the deprecated path) ## Errors ### 401 Unauthorized Error Unauthorized - `error` (ErrorError, required) ### 403 Forbidden Error Forbidden - `error` (ErrorError, required) ### 422 Unprocessable Entity Error Invalid pagination params (invalid/unsupported cursor, or mixed cursor + offset families) - `error` (ErrorError, required) ## Types ### UserMemory A memory entry visible to the user - `chat_room_status` (string, required, nullable) — Status of the chat room; null under the same conditions as `chat_room_title`. - `chat_room_title` (string, required, nullable) — Title of the chat room the memory was created in. Null when the memory has no room, the room was deleted, or the caller does not participate in it — `chat_room_id` is still returned, as the id alone carries no room content. - `chat_room_type` (string, required, nullable) — Type of the chat room; null under the same conditions as `chat_room_title`. - `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` - `source_agent_name` (string, required, nullable) — Display name of the agent that stored this memory; null when unresolvable. - `subject_name` (string, required, nullable) — Display name of the subject this memory is about. Null when there is no subject, when the referent no longer exists, or when it is not visible to the caller (a name is data and is scoped like the row itself). - `subject_type` (enum, required, nullable) — Which id space `subject_id` resolved in — `subject_id` itself carries no discriminator. Null whenever `subject_name` is null. - Allowed values: `user`, `agent` - `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` - `updated_at` (string, required) — When the memory was last modified — a supersede, archive or restore moves it, so it is the field to show as "Updated". Results are ordered by `inserted_at` regardless: the keyset cursor is built on `(inserted_at, id)`, so ordering by this field is not offered rather than offered and silently broken. - `chat_room_id` (string, optional, nullable) — Chat room where memory was created (if applicable) - `metadata` (UserMemoryMetadata, 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 - `thought` (string, optional, nullable) — Agent's reasoning for storing this memory ### ApiV1MeMemoriesGetResponsesContentApplicationJsonSchemaMeta 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) ### ApiV1MeMemoriesGetResponsesContentApplicationJsonSchemaMetadata 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) ### UserMemoryMetadata Additional metadata ### ErrorErrorDetails Additional error details (optional) ## Examples **Response** ```json { "data": [ { "chat_room_status": "string", "chat_room_title": "string", "chat_room_type": "string", "content": "string", "id": "string", "inserted_at": "2024-01-15T09:30:00Z", "scope": "agent", "segment": "user", "source_agent_name": "string", "subject_name": "string", "subject_type": "user", "system": "sensory", "type": "iconic", "updated_at": "2024-01-15T09:30:00Z", "chat_room_id": "string", "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/me/memories" querystring = {"chat_room_id":"daca00d0-eb6b-4db1-8201-c46015c93d04","content_query":"prefers SUV","cursor":"eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJpIjoiNTUwZTg0MDAifQ","limit":"20","page":"1","page_size":"20","scope":"about_me","segment":"user","source_agent_id":"40b10483-595a-4275-9720-d05edda97279","status":"active","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/me/memories?chat_room_id=daca00d0-eb6b-4db1-8201-c46015c93d04&content_query=prefers+SUV&cursor=eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJpIjoiNTUwZTg0MDAifQ&limit=20&page=1&page_size=20&scope=about_me&segment=user&source_agent_id=40b10483-595a-4275-9720-d05edda97279&status=active&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/me/memories?chat_room_id=daca00d0-eb6b-4db1-8201-c46015c93d04&content_query=prefers+SUV&cursor=eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJpIjoiNTUwZTg0MDAifQ&limit=20&page=1&page_size=20&scope=about_me&segment=user&source_agent_id=40b10483-595a-4275-9720-d05edda97279&status=active&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/me/memories?chat_room_id=daca00d0-eb6b-4db1-8201-c46015c93d04&content_query=prefers+SUV&cursor=eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJpIjoiNTUwZTg0MDAifQ&limit=20&page=1&page_size=20&scope=about_me&segment=user&source_agent_id=40b10483-595a-4275-9720-d05edda97279&status=active&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/me/memories?chat_room_id=daca00d0-eb6b-4db1-8201-c46015c93d04&content_query=prefers+SUV&cursor=eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJpIjoiNTUwZTg0MDAifQ&limit=20&page=1&page_size=20&scope=about_me&segment=user&source_agent_id=40b10483-595a-4275-9720-d05edda97279&status=active&system=long_term&type=semantic") .header("X-API-Key", "") .asString(); ``` ```php request('GET', 'https://api.dev.band.ai/api/v1/me/memories?chat_room_id=daca00d0-eb6b-4db1-8201-c46015c93d04&content_query=prefers+SUV&cursor=eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJpIjoiNTUwZTg0MDAifQ&limit=20&page=1&page_size=20&scope=about_me&segment=user&source_agent_id=40b10483-595a-4275-9720-d05edda97279&status=active&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/me/memories?chat_room_id=daca00d0-eb6b-4db1-8201-c46015c93d04&content_query=prefers+SUV&cursor=eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJpIjoiNTUwZTg0MDAifQ&limit=20&page=1&page_size=20&scope=about_me&segment=user&source_agent_id=40b10483-595a-4275-9720-d05edda97279&status=active&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/me/memories?chat_room_id=daca00d0-eb6b-4db1-8201-c46015c93d04&content_query=prefers+SUV&cursor=eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJpIjoiNTUwZTg0MDAifQ&limit=20&page=1&page_size=20&scope=about_me&segment=user&source_agent_id=40b10483-595a-4275-9720-d05edda97279&status=active&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() ```