Skip to main content

Knowledge Commands

See Knowledge module docs for permissions and data model.

soat search-knowledge​

Search knowledge

  • Method: POST
  • Path: /api/v1/knowledge/search

Usage​

soat search-knowledge

Options​

--project-id​

Limit search to a specific project

  • Source: body
  • Required: no
  • Type: string
  • Example: proj_V1StGXR8Z5jdHi6B
--query​

Search query text. Runs a vector query and a full-text query over each store and fuses the rankings; the full-text channel matches exact tokens and phrases, the vector channel everything else.

  • Source: body
  • Required: no
  • Type: string
  • Example: customer communication preferences
--min-similarity​

Minimum raw cosine similarity_score a vector candidate must reach to take part in ranking, applied before fusion. Only applies when query is provided. Lexical candidates are deliberately exempt: a result that literally contains the searched token is the evidence, and dropping it for a low cosine is the failure hybrid search exists to prevent. Not a floor on score, whose fused value encodes rank position rather than similarity.

  • Source: body
  • Required: no
  • Type: number
  • Example: 0.5
--rrf-k​

The k in the reciprocal rank fusion term 1 / (k + rank), which sets how steeply a result's contribution decays with its position in each ranked list. A smaller value weights the very top of each list more heavily. Defaults to the deployment's KNOWLEDGE_RRF_K, itself 60 by default. Only applies when query is provided.

  • Source: body
  • Required: no
  • Type: integer
  • Example: 60
--recency-half-life-days​

Half-life, in days, of a recency decay applied to memory store results after fusion: a result's score is multiplied by 2 ^ (-age_in_days / recency_half_life_days), where age is measured from its updated_at. Document results are never decayed. 0 — the default, and the default of the deployment's KNOWLEDGE_RECENCY_HALF_LIFE_DAYS — disables the blend entirely; it is a switch, not a lower bound, and sending 0 turns off a deployment-wide decay for this one request. Accepts fractions (0.5 is twelve hours). How many ranks a given half-life costs depends on rrf_k. Only applies when query is provided. No value is known to be safe in general: every half-life measured against the reference corpus that lifted recency-sensitive queries also cost relevance-sensitive ones, which is why this ships disabled. Measure against your own corpus before setting it — see the Retrieval Quality guide.

  • Source: body
  • Required: no
  • Type: number
  • Example: 30
--limit​

Maximum number of results to return (default 10). A value above 100 is clamped to 100 — the ceiling bounds the vector scan this one request performs, so a larger limit returns everything there is up to that many rows rather than being refused.

  • Source: body
  • Required: no
  • Type: integer
  • Example: 10
--include-documents​

Set false to leave the document store out of this search. A query names no store, so it reaches both; the store-specific filters narrow within a store rather than choosing between them. This is the switch, and a filter naming the other store never overrides it. false for both stores is 400.

  • Source: body
  • Required: no
  • Type: boolean
  • Default: true
  • Example: false
--include-memories​

Set false to leave the memory store out of this search. The mirror of include_documents, for a caller that wants documents alone.

  • Source: body
  • Required: no
  • Type: boolean
  • Default: true
  • Example: false
--memory-store-ids​

Search memories within these specific memory stores

  • Source: body
  • Required: no
  • Type: array<string>
  • Example: ["mstore_V1StGXR8Z5jdHi6B"]
--document-paths​

Filter results to documents whose file path starts with one of these prefixes

  • Source: body
  • Required: no
  • Type: array<string>
  • Example: ["/sales/","/hr/"]
--document-ids​

Filter results to specific document IDs

  • Source: body
  • Required: no
  • Type: array<string>
  • Example: ["doc_V1StGXR8Z5jdHi6B"]
--tags​

Filter results to documents and memories whose tags contain every one of these key-value pairs (exact, case-sensitive match). Scopes both stores, so passing it alone searches both — as query does. For memories it matches at memory granularity: a memory is returned when its parent memory store's tags match or its own do.

  • Source: body
  • Required: no
  • Type: unknown
--metadata​

Filter document results by their metadata bag. A document-store filter: a memory carries no such bag, so passing it alone searches documents, as document_paths does.

  • Source: body
  • Required: no
  • Type: unknown