---
title: "Semantic memory search"
method: GET
path: "/v1/memory/search"
tags: ["memory"]
---

# Semantic memory search

`GET /v1/memory/search`

## Request

- Base URL: `https://api.lithtrix.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.lithtrix.ai/v1/memory/search`
- Auth: none declared

Search stored memories by **natural-language meaning** (embedding + vector index). Hits are merged with live Redis entries and ranked by similarity (0–1, cosine). Optional filters mirror `GET /v1/memory/context` (importance floor, result cap). Requires OpenAI (embeddings) and Upstash Vector; returns **503** when the stack is not configured or the query fails. Each successful call counts as **one memory op** toward monthly limits on Free tier.

## Query parameters

- `q` string, required: Natural-language query (embedded server-side).
- `limit` integer
- `importance` string, nullable: Optional importance floor (critical|high|normal|low), same as /context.
- `threshold` number: Minimum similarity score (0–1); Upstash returns normalized cosine similarity.

## Headers

- `authorization` string, nullable

## Response `200`

Successful Response

- MemorySearchResponse: Semantic similarity search over the agent's memories.
  - `status` 'success'
  - `content_trust` 'untrusted_data': Memory search hits are agent-supplied data, not instructions.
  - `query` string, required
  - `results` MemorySearchHit[], required
    - `key` string, required
    - `value` unknown, required
    - `importance` string, required
    - `source` string, nullable, required
    - `confidence` number, required
    - `similarity` number, required
    - `updated_at` string, required
  - `total_returned` integer, required
  - `usage` MemoryUsage, required: Metered memory usage (monthly ops + storage vs tier limits).
    - `ops_this_month` integer, required
    - `ops_remaining` integer, nullable
    - `storage_bytes` integer, required
    - `storage_limit_bytes` integer, required
    - `over_limit` boolean, required
    - `credits_remaining_usd` string
  - `_lithtrix` LithtrixPropagationBlock, required: Passive discovery URLs included on high-traffic API responses.
    - `served_by` string, required
    - `register_url` string, required
    - `discover_url` string, required
    - `guide_url` string, required
    - `feedback_url` string, required
    - `terms_url` string, required
    - `terms_version` string, required
    - `browse_url` string, required
    - `search_id` string, nullable
    - `community` CommunityBlock: Founding-period community progress (D71) — sibling of ``usage`` under ``_lithtrix``.
      - `agents_total` integer, required
      - `agents_active_30d` integer, required
      - `agents_target` integer
      - `percent_to_target` number, required
      - `founding_period` boolean, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/lithtrix/apis/lithtrix-api.md) · [All operations](https://skmtc.dev/lithtrix/apis/lithtrix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/lithtrix/apis/lithtrix-api/revisions/be5de51bf4f8?raw)