---
title: "Post Search"
method: POST
path: "/api/v1/memory/search"
tags: ["memory"]
---

# Post Search

`POST /api/v1/memory/search`

Hybrid retrieval across the configured memory backends.

## Request body

- SearchRequest — Request body for ``POST /api/v2/memory/search``. Callers identify the memory owner via ``user_id`` XOR ``agent_id`` — exactly one must be set. Internally the manager + compile_filters keep using ``owner_id`` / ``owner_type`` (the storage tables' columns); those are exposed as derived properties so the rename only affects the wire contract, not the internal recall plumbing.
  - `user_id` string, nullable
  - `agent_id` string, nullable
  - `app_id` string
  - `project_id` string
  - `query` string, required
  - `method` 'keyword' | 'vector' | 'hybrid' | 'agentic' — Public method enum. RRF / LR / vector_anchored are hidden under HYBRID.
  - `top_k` integer
  - `radius` number, nullable
  - `min_score` number, nullable
  - `include_profile` boolean
  - `enable_llm_rerank` boolean — Opt-in LLM rerank pass for HYBRID. Applies to agent_case and agent_skill fusion only; the episode hybrid path has built-in fact eviction and ignores this flag. Ignored by keyword / vector / agentic.
  - `filters` FilterNode — One Filters DSL node. Recursive ``AND`` / ``OR`` arrays mix with arbitrary scalar fields at the same level. Pydantic only checks the combinators; field-level safety is enforced when compiling the node to a LanceDB ``where`` string in :mod:`everos.memory.search.filters`.
    - `AND` FilterNode[], nullable
    - `OR` FilterNode[], nullable

## Response `200`

Successful Response

- SearchResponse — Top-level response envelope.
  - `request_id` string, required
  - `data` SearchData, required — Body of ``response.data``. All five arrays are always present so client code can iterate without branching on ``owner_type``. Routes not applicable to the request's owner type stay as ``[]``. ``unprocessed_messages`` is filled only when ``filters.session_id`` is present as a top-level eq scalar — in-flight buffer rows are scope-tagged but unattributed (no ``user_id``), so session is the only meaningful query dimension.
    - `episodes` SearchEpisodeItem[]
      - `id` string, required
      - `user_id` string, nullable, required
      - `app_id` string
      - `project_id` string
      - `session_id` string, nullable
      - `timestamp` string, date-time, required
      - `sender_ids` string[]
      - `summary` string, required
      - `subject` string, required
      - `episode` string, required
      - `type` 'Conversation', required
      - `score` number, required
      - `atomic_facts` SearchAtomicFactItem[]
        - `id` string, required
        - `content` string, required
        - `score` number, required
    - `profiles` SearchProfileItem[]
      - `id` string, required
      - `user_id` string, nullable, required
      - `app_id` string
      - `project_id` string
      - `profile_data` object, required
      - `score` number, nullable
    - `agent_cases` SearchAgentCaseItem[]
      - `id` string, required
      - `agent_id` string, required
      - `app_id` string
      - `project_id` string
      - `session_id` string, required
      - `task_intent` string, required
      - `approach` string, required
      - `quality_score` number, required
      - `key_insight` string, nullable
      - `timestamp` string, date-time, required
      - `score` number, required
    - `agent_skills` SearchAgentSkillItem[]
      - `id` string, required
      - `agent_id` string, required
      - `app_id` string
      - `project_id` string
      - `name` string, required
      - `description` string, required
      - `content` string, required
      - `confidence` number, required
      - `maturity_score` number, required
      - `source_case_ids` string[]
      - `score` number, required
    - `unprocessed_messages` UnprocessedMessageDTO[]
      - `id` string, required
      - `app_id` string
      - `project_id` string
      - `session_id` string, required
      - `sender_id` string, required
      - `sender_name` string, nullable
      - `role` 'user' | 'assistant' | 'tool', required
      - `content` union, required
        - string
        - object[]
      - `timestamp` string, date-time, required
      - `tool_calls` object[], nullable
      - `tool_call_id` string, nullable

## Other responses

- `422` — Validation Error

## Changes

- **2026-06-24** `65f2f4743b36` — 2 breaking, 1 info
  - the response property `data/episodes/items/session_id` became optional for the status `200`
  - response property `data/episodes/items/session_id` list-of-types was widened by adding types `null` to media type `application/json` of response `200`
  - added the new optional request property `min_score`
- **2026-06-05** `7be97420eb25` — 1 warning, 2 info
  - removed the request property `min_score`
  - the response property `data/episodes/items/session_id` became required for the status `200`
  - response property `data/episodes/items/session_id` list-of-types was narrowed by removing types `null` from media type `application/json` of response `200`

[Change history](https://skmtc.dev/evermind-ai/apis/everos/changes/api/v1/memory/search/post.md)

---

[API](https://skmtc.dev/evermind-ai/apis/everos.md) · [All operations](https://skmtc.dev/evermind-ai/apis/everos/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/evermind-ai/everos/revisions/9a2e78d664d6/schema)