> ## 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. # Search memories [OSS + Cloud] > Retrieve the memories relevant to a query. Exactly one of `user_id` / `agent_id` is required, and it decides what comes back: a user owner returns episodes (plus profiles with `include_profile`), an agent owner returns agent cases and skills. All result collections are always present in the response, empty when they do not apply. The vector-backed methods read an index that lags extraction by seconds — to read back something just extracted, use /api/v2/memory/get. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v2/memory/search 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/search: post: tags: - Memory summary: Search memories [OSS + Cloud] description: >- Retrieve the memories relevant to a query. Exactly one of `user_id` / `agent_id` is required, and it decides what comes back: a user owner returns episodes (plus profiles with `include_profile`), an agent owner returns agent cases and skills. All result collections are always present in the response, empty when they do not apply. The vector-backed methods read an index that lags extraction by seconds — to read back something just extracted, use /api/v2/memory/get. operationId: searchMemory requestBody: content: application/json: schema: $ref: '#/components/schemas/SearchInput' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SuccessEnvelope_SearchData_' '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: SearchInput: properties: app_id: type: string title: App Id default: default description: >- Scope to search in, 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: >- Search one user's memories — matched against the messages' `sender_id`. Exactly one of `user_id` / `agent_id` is required. agent_id: anyOf: - type: string minLength: 1 - type: 'null' title: Agent Id description: >- Search one agent's memories (cases and skills). Exactly one of `user_id` / `agent_id` is required. query: type: string minLength: 1 title: Query description: The natural-language query to retrieve against. method: type: string enum: - keyword - vector - hybrid - agentic title: Method default: hybrid description: >- Retrieval strategy. "keyword" is lexical, "vector" is embedding similarity, "hybrid" (default) combines both, and "agentic" lets the engine run a multi-round LLM-guided retrieval — more thorough, slower. top_k: type: integer title: Top K default: -1 description: >- Maximum number of hits. Either -1 (the default, letting the engine decide) or a value from 1 to 100; anything else is rejected with 422. radius: anyOf: - type: number maximum: 1 minimum: 0 - type: 'null' title: Radius description: Vector-similarity radius, 0.0–1.0. Unset leaves it to the engine. min_score: anyOf: - type: number maximum: 1 minimum: 0 - type: 'null' title: Min Score description: >- Post-fusion score floor, 0.0–1.0. Applies to the episode hybrid (hierarchy) path only; other paths ignore it. The hybrid path fuses its two routes into a probability, so unlike a raw keyword or vector score this floor is an absolute bar and 0.0–1.0 is the real range. include_profile: type: boolean title: Include Profile default: false description: >- Also return the user's profile alongside the hits, saving a second call. Ignored for an agent owner, whose results carry no profiles. with_readable_episode: type: boolean title: With Readable Episode default: false description: >- Attach a human-readable rendering of each episode to the returned items, for display only — it is not indexed, filterable or scored, and callers fall back to `episode` when it is null. Ignored for an agent owner. enable_llm_rerank: type: boolean title: Enable Llm Rerank default: false description: >- Opt-in LLM rerank, and only for hybrid agent_case / agent_skill retrieval. The episode hybrid path has its own fact eviction and ignores this, as do keyword, vector and agentic. filters: anyOf: - $ref: '#/components/schemas/FilterNode' - type: 'null' description: >- Optional filter tree — recursive `AND` / `OR` arrays mixed with the scalar conditions being matched. additionalProperties: false type: object required: - query title: SearchInput example: query: outdoor hobbies method: hybrid top_k: 10 include_profile: true SuccessEnvelope_SearchData_: properties: request_id: type: string title: Request Id description: Request trace id (peer to data) data: $ref: '#/components/schemas/SearchData' description: Endpoint-defined business result type: object required: - request_id - data title: SuccessEnvelope[SearchData] 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. SearchData: properties: episodes: items: $ref: '#/components/schemas/SearchEpisodeItem' type: array title: Episodes description: >- Matching episodes, for a user owner. Always present, empty when not applicable. profiles: items: $ref: '#/components/schemas/SearchProfileItem' type: array title: Profiles description: The user's profile, when `include_profile` asked for it. agent_cases: items: $ref: '#/components/schemas/SearchAgentCaseItem' type: array title: Agent Cases description: Matching agent cases, for an agent owner. agent_skills: items: $ref: '#/components/schemas/SearchAgentSkillItem' type: array title: Agent Skills description: Matching agent skills, for an agent owner. unprocessed_messages: items: $ref: '#/components/schemas/UnprocessedMessageDTO' type: array title: Unprocessed Messages description: >- Raw buffered messages not yet extracted. Returned only when the request filtered on a single `session_id`, so a caller can see what is still in flight. type: object title: SearchData 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 SearchEpisodeItem: 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/SearchAtomicFactItem' type: array title: Atomic Facts description: >- The facts extracted from this episode, each with its own relevance score. tags: items: type: string type: array title: Tags description: Tags attached through /api/v2/memory/tag/*. score: type: number title: Score description: >- Relevance of this episode to the query. What the number means depends on `method`: the hybrid path fuses its two routes into a probability in 0.0–1.0 (which is what `min_score` filters on), while keyword and vector pass the underlying engine's own score through — BM25 has no upper bound and vector similarity depends on the metric. So compare scores within one method, not across methods. type: object required: - id - app_id - project_id - timestamp - summary - subject - episode - type - score title: SearchEpisodeItem SearchProfileItem: 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. score: anyOf: - type: number - type: 'null' title: Score description: >- Relevance to the query. Null when the profile was returned by `include_profile` rather than matched. type: object required: - id - app_id - project_id - user_id title: SearchProfileItem SearchAgentCaseItem: 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). score: type: number title: Score description: Relevance of this case to the query. type: object required: - id - app_id - project_id - agent_id - session_id - task_intent - approach - quality_score - timestamp - score title: SearchAgentCaseItem SearchAgentSkillItem: 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. score: type: number title: Score description: Relevance of this skill to the query. type: object required: - id - app_id - project_id - agent_id - name - description - content - confidence - maturity_score - score title: SearchAgentSkillItem UnprocessedMessageDTO: properties: id: type: string title: Id description: Buffered-message id. app_id: type: string title: App Id description: The business-semantic scope the message was written under. project_id: type: string title: Project Id description: Second half of that scope. session_id: type: string title: Session Id description: The session the message is buffered under. sender_id: type: string title: Sender Id description: Who sent it. sender_name: anyOf: - type: string - type: 'null' title: Sender Name description: The sender's display name, when one was given. role: type: string enum: - user - assistant - tool title: Role description: '"user", "assistant" or "tool", as submitted.' content: anyOf: - type: string - items: $ref: '#/components/schemas/ContentItem' type: array title: Content description: The message body as submitted. timestamp: type: string format: date-time title: Timestamp description: When the message was produced (ISO 8601). tool_calls: anyOf: - items: $ref: '#/components/schemas/ToolCall' type: array - type: 'null' title: Tool Calls description: Tool calls on an assistant message, as submitted. tool_call_id: anyOf: - type: string - type: 'null' title: Tool Call Id description: The tool call this result answers, on a "tool" message. type: object required: - id - app_id - project_id - session_id - sender_id - role - content - timestamp title: UnprocessedMessageDTO description: >- Buffered raw message not yet extracted (no owner — inference happens after boundary detection). Returned by /search only when ``filters.session_id`` is a top-level eq scalar (spec §4 / appendix E). SearchAtomicFactItem: properties: id: type: string title: Id description: Atomic-fact id. content: type: string title: Content description: The fact itself, as a single statement. score: type: number title: Score description: Relevance of this fact to the query. type: object required: - id - content - score title: SearchAtomicFactItem ContentItem: properties: type: type: string enum: - text - audio - image - doc - pdf - html - email title: Type description: >- What this item is: "text", "image", "audio", "doc", "pdf", "html" or "email". It selects how the content is parsed, so it must match the payload. text: anyOf: - type: string - type: 'null' title: Text description: Inline text, used when `type` is "text". source: anyOf: - type: string - type: 'null' title: Source description: >- Where the item came from — an origin label carried through to the memory. base64: anyOf: - type: string - type: 'null' title: Base64 description: >- The item's bytes inline, base64-encoded. NOTE: a non-text item that carries only `base64` is skipped by the parse step — the parser reads bytes from object storage — so use `uri` for anything that must actually be understood. uri: anyOf: - type: string - type: 'null' title: Uri description: >- Pointer to already-uploaded bytes: the object key returned by POST /api/v2/object/sign. This is the only form of a non-text item that gets parsed. ext: anyOf: - type: string - type: 'null' title: Ext description: >- File extension of the referenced content, e.g. "pdf" — used when the uri carries none. name: anyOf: - type: string - type: 'null' title: Name description: Original file name, kept for display and passed to the parser. source_info: anyOf: - additionalProperties: true type: object - type: 'null' title: Source Info description: >- Free-form provenance metadata stored alongside the item; a `size` here is passed to the parser. extras: anyOf: - additionalProperties: true type: object - type: 'null' title: Extras description: Free-form extra fields, passed through untouched. type: object required: - type title: ContentItem description: >- A single content element (appendix A). Current phase: only ``type="text"``. ToolCall: properties: id: type: string title: Id description: >- Tool-call id; the matching "tool" message echoes it as `tool_call_id`. type: type: string title: Type default: function description: Tool-call kind. Always "function" today. function: $ref: '#/components/schemas/ToolCallFunction' description: The function invoked, with its arguments. type: object required: - id - function title: ToolCall ToolCallFunction: properties: name: type: string title: Name description: Name of the function the assistant called. arguments: type: string title: Arguments description: >- The call's arguments as a JSON-encoded string (OpenAI shape), not an object. type: object required: - name - arguments title: ToolCallFunction 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.