> ## Documentation Index > Fetch the complete documentation index at: https://docs.evermind.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get memories [OSS + Cloud] > List stored memories of one type, paginated. - Exactly one of `user_id` / `agent_id` is required. - `memory_type` must match that owner: a user owns "episode" and "profile", an agent owns "agent_case" and "agent_skill". The other pairings are rejected with 422. This is a structured read, not a query: it does not embed the request, so a memory is readable as soon as it is extracted — whereas the vector index /api/v2/memory/search relies on lags behind extraction by seconds. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v2/memory/get openapi: 3.1.0 info: title: EverOS Cloud Memory API version: 2.0.0 license: name: Apache-2.0 identifier: Apache-2.0 contact: name: EverMind AI email: service@evermind.ai url: https://github.com/EverMind-AI/everos-cloud-sdk-python description: >- Official Python client for the EverOS Cloud Memory API. Add, search, retrieve, and manage long-term memory for your AI applications over a typed interface (pydantic v2, with full type hints). Install and usage guides: https://github.com/EverMind-AI/everos-cloud-sdk-python servers: - url: https://api.evermind.ai description: Production security: - BearerAuth: [] paths: /api/v2/memory/get: post: tags: - Memory summary: Get memories [OSS + Cloud] description: >- List stored memories of one type, paginated. - Exactly one of `user_id` / `agent_id` is required. - `memory_type` must match that owner: a user owns "episode" and "profile", an agent owns "agent_case" and "agent_skill". The other pairings are rejected with 422. This is a structured read, not a query: it does not embed the request, so a memory is readable as soon as it is extracted — whereas the vector index /api/v2/memory/search relies on lags behind extraction by seconds. operationId: getMemory requestBody: content: application/json: schema: $ref: '#/components/schemas/GetInput' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SuccessEnvelope_GetData_' '401': description: Missing or invalid bearer token. content: application/json: schema: $ref: '#/components/schemas/GatewayError' '403': description: >- Authenticated but not permitted — either rejected by the auth service, or the account's memory API version does not match the interface version implied by the path (a v1 account calling an /api/v2 route). content: application/json: schema: $ref: '#/components/schemas/GatewayError' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Rate limit or quota exceeded. content: application/json: schema: $ref: '#/components/schemas/GatewayError' '503': description: >- The gateway could not reach the authentication service. Transient — retry with backoff. content: application/json: schema: $ref: '#/components/schemas/GatewayError' components: schemas: GetInput: properties: app_id: type: string title: App Id default: default description: >- Scope to read from, defaulting to "default". Must match the pair used on write. project_id: type: string title: Project Id default: default description: Second half of the scope, defaulting to "default". user_id: anyOf: - type: string minLength: 1 - type: 'null' title: User Id description: >- Read one user's memories. Exactly one of `user_id` / `agent_id` is required, and a user owner may only ask for "episode" or "profile". agent_id: anyOf: - type: string minLength: 1 - type: 'null' title: Agent Id description: >- Read one agent's memories. Exactly one of `user_id` / `agent_id` is required, and an agent owner may only ask for "agent_case" or "agent_skill". memory_type: type: string enum: - episode - profile - agent_case - agent_skill title: Memory Type description: >- Which kind of memory to list: "episode" (narrative summaries of past sessions), "profile" (stable identity and preferences), "agent_case" (a distilled past trajectory) or "agent_skill" (a reusable skill). It must match the owner — the mismatched pairings are rejected with 422. page: type: integer minimum: 1 title: Page default: 1 description: 1-based page number. page_size: type: integer maximum: 100 minimum: 1 title: Page Size default: 20 description: Items per page, 1 to 100 (default 20). sort_by: type: string enum: - timestamp - updated_at title: Sort By default: timestamp description: >- Order by "timestamp" (when the memory happened, default) or "updated_at" (when it was last written). Profiles and agent skills have no temporal column and always sort by "updated_at". sort_order: type: string enum: - asc - desc title: Sort Order default: desc description: '"desc" (default, newest first) or "asc".' with_readable_episode: type: boolean title: With Readable Episode default: false description: >- Attach a human-readable rendering to each returned episode, for display only. Ignored for every non-episode `memory_type` rather than rejected. filters: anyOf: - $ref: '#/components/schemas/FilterNode' - type: 'null' description: >- Optional filter tree applied to the listing; same shape as on search. additionalProperties: false type: object required: - memory_type title: GetInput example: memory_type: episode page: 1 page_size: 20 sort_order: desc SuccessEnvelope_GetData_: properties: request_id: type: string title: Request Id description: Request trace id (peer to data) data: $ref: '#/components/schemas/GetData' description: Endpoint-defined business result type: object required: - request_id - data title: SuccessEnvelope[GetData] GatewayError: type: object additionalProperties: true description: >- Gateway error body. NOTE: shape is not yet uniform across auth/quota/ rate-limit paths — treat fields as best-effort. Commonly includes a `code`/`message` (flat) or an `error` object/string with a `message`. title: GatewayError HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail description: One entry per field that failed validation. type: object title: HTTPValidationError FilterNode: properties: AND: anyOf: - items: $ref: '#/components/schemas/FilterNode' type: array - type: 'null' title: And description: Nested conditions that must all hold. OR: anyOf: - items: $ref: '#/components/schemas/FilterNode' type: array - type: 'null' title: Or description: Nested conditions of which at least one must hold. additionalProperties: true type: object title: FilterNode description: |- One Filters DSL node — recursive ``AND`` / ``OR`` arrays plus arbitrary scalar field conditions at the same level. GetData: properties: episodes: items: $ref: '#/components/schemas/EpisodeItem' type: array title: Episodes description: Episodes, when `memory_type` was "episode". Empty otherwise. profiles: items: $ref: '#/components/schemas/ProfileItem' type: array title: Profiles description: Profiles, when `memory_type` was "profile". Empty otherwise. agent_cases: items: $ref: '#/components/schemas/AgentCaseItem' type: array title: Agent Cases description: Agent cases, when `memory_type` was "agent_case". Empty otherwise. agent_skills: items: $ref: '#/components/schemas/AgentSkillItem' type: array title: Agent Skills description: Agent skills, when `memory_type` was "agent_skill". Empty otherwise. total_count: type: integer title: Total Count default: 0 description: How many memories match the request in total, across all pages. count: type: integer title: Count default: 0 description: How many are in this page. type: object title: GetData ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location description: Path to the offending field, from the body root. msg: type: string title: Message description: What is wrong with it. type: type: string title: Error Type description: Machine-readable validation-error kind. type: object required: - loc - msg - type title: ValidationError EpisodeItem: properties: id: type: string title: Id description: Episode id. Use it to bind tags or to fetch this episode again. app_id: type: string title: App Id description: The business-semantic scope this memory was written under. project_id: type: string title: Project Id description: Second half of that scope. user_id: anyOf: - type: string - type: 'null' title: User Id description: >- The user this episode belongs to. Null on an episode merged from several owners. session_id: anyOf: - type: string - type: 'null' title: Session Id description: >- The session it was extracted from. Null when the episode merges more than one session. timestamp: type: string format: date-time title: Timestamp description: >- When the remembered exchange happened (ISO 8601), not when it was extracted. sender_ids: items: type: string type: array title: Sender Ids description: The senders that appear in the source exchange. summary: type: string title: Summary description: Short summary of the episode — what a result list should show. subject: type: string title: Subject description: What the episode is about, in a few words. episode: type: string title: Episode description: >- The episode's stored narrative body. This is the indexed, searchable text. readable_episode: anyOf: - type: string - type: 'null' title: Readable Episode description: >- Human-readable rendering of `episode`, for display only — never indexed, filtered or scored. Present as a key but null unless the request asked for it (and the tenant is enabled for it); fall back to `episode` when it is null. type: type: string title: Type description: >- How the episode was produced — "Conversation" or "AgentConversation". atomic_facts: items: $ref: '#/components/schemas/AtomicFactItem' type: array title: Atomic Facts description: >- The individual facts extracted from this episode, nested rather than returned separately. tags: items: type: string type: array title: Tags description: Tags attached through /api/v2/memory/tag/*. type: object required: - id - app_id - project_id - timestamp - summary - subject - episode - type title: EpisodeItem ProfileItem: properties: id: type: string title: Id description: Profile id. app_id: type: string title: App Id description: The business-semantic scope this profile was written under. project_id: type: string title: Project Id description: Second half of that scope. user_id: type: string title: User Id description: The user this profile describes. profile_data: additionalProperties: true type: object title: Profile Data description: >- The profile itself — the explicit_info and implicit_traits items maintained by extraction and by /api/v2/memory/edit. Each item's id is what an edit operation targets. created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At description: When the profile was first created. updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At description: When it last changed. type: object required: - id - app_id - project_id - user_id title: ProfileItem AgentCaseItem: properties: id: type: string title: Id description: Agent-case id. app_id: type: string title: App Id description: The business-semantic scope this case was written under. project_id: type: string title: Project Id description: Second half of that scope. agent_id: type: string title: Agent Id description: The agent that owns this case. session_id: type: string title: Session Id description: The session whose trajectory the case was distilled from. task_intent: type: string title: Task Intent description: What the agent was trying to do in that trajectory. approach: type: string title: Approach description: How it went about it — the reusable part of the case. quality_score: type: number title: Quality Score description: >- How good this case is judged to be. Nominally 0.0–1.0 with 0.5 as the no-opinion default, but the value is the extractor's own and nothing on the write path enforces the range — treat an out-of-range number as possible. One threshold is real: a case scoring below 0.2 is never distilled into a skill. key_insight: anyOf: - type: string - type: 'null' title: Key Insight description: >- The single takeaway distilled from the trajectory, when there is one. timestamp: type: string format: date-time title: Timestamp description: When the trajectory happened (ISO 8601). type: object required: - id - app_id - project_id - agent_id - session_id - task_intent - approach - quality_score - timestamp title: AgentCaseItem AgentSkillItem: properties: id: type: string title: Id description: Agent-skill id. app_id: type: string title: App Id description: The business-semantic scope this skill was written under. project_id: type: string title: Project Id description: Second half of that scope. agent_id: type: string title: Agent Id description: The agent that owns this skill. name: type: string title: Name description: The skill's name. description: type: string title: Description description: What the skill is for, in a sentence. content: type: string title: Content description: The skill itself — the reusable procedure, ready to put in a prompt. confidence: type: number title: Confidence description: >- How much the distillation trusts this skill. Nominally 0.0–1.0, defaulting to 0.0 before anything scores it; the range is not enforced on the write path. Nothing in retrieval filters on it today, and how it divides labour with `maturity_score` is still open — so do not build a threshold on it yet. maturity_score: type: number title: Maturity Score description: >- How well-established the skill is. Nominally 0.0–1.0 and unenforced, and — unlike the other two scores — its default is 0.6 rather than 0.0, chosen so an unscored skill starts mid-optimistic. The cost is that an unscored 0.6 is indistinguishable from a scored 0.6: there is no "not evaluated" sentinel, and maturity scoring is skipped by default. Filtering near 0.6 is therefore unreliable. source_case_ids: items: type: string type: array title: Source Case Ids description: >- The agent cases this skill was distilled from. Fetch them for the underlying evidence. created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At description: When the skill was first distilled. updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At description: When it was last reinforced or rewritten. type: object required: - id - app_id - project_id - agent_id - name - description - content - confidence - maturity_score title: AgentSkillItem AtomicFactItem: properties: id: type: string title: Id description: Atomic-fact id. content: type: string title: Content description: The fact itself, as a single statement. type: object required: - id - content title: AtomicFactItem description: |- Atomic fact nested in an episode. Spec appendix E references it but does not enumerate its fields — minimal shape until the contract is detailed. securitySchemes: BearerAuth: type: http scheme: bearer description: 'API key issued by EverOS, sent as `Authorization: Bearer `.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.