# Recall Memories Matching a Query

> Recall Memories Matching a Query is a paid API for AI agents from memory.withzero.xyz, paid per call via MPP, metered — billed by usage, status unknown (last checked 2026-09-14, last successful call 2026-07-18).

Performs a semantic similarity search over durable agent memories and returns the most relevant stored facts or context entries for a given natural-language query.

## Facts

- Endpoint: POST https://memory.withzero.xyz/api/v1/contexts
- Price: metered — billed by usage
- Payment: MPP
- Status: unknown
- Last checked: 2026-09-14
- Last successful call: 2026-07-18
- Success rate: 50% of calls made through Zero
- Activations on Zero: 5
- Provider: memory.withzero.xyz
- Website: https://memory.withzero.xyz
- Canonical page: https://www.zero.xyz/c/memory-withzero-xyz-recall-memories-matching-a-query-242a8bfe
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_wsfxxFo9utcWWfPe9mLiv

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability memory-withzero-xyz-recall-memories-matching-a-query-242a8bfe -d '<json body>'
```

Example prompt: Search my durable agent memory for anything relevant to 'project deadlines and client deliverables' and return the top 5 most similar memories.

## When to prefer this

Use this endpoint when an AI agent needs to retrieve previously stored facts, context, or notes that are semantically relevant to the current task or user query. It is free to call, making it ideal for frequent lookups during reasoning loops. Prefer this over a full memory dump when you want ranked, relevant results rather than all stored data. If a returned memory has is_summary=true, follow up with the /expand endpoint to retrieve the underlying consolidated memories.

## Known failure modes

- query string missing or empty — returns 400 validation error
- query exceeds 4096 character limit — returns 400 validation error
- namespace specified does not exist or has no memories — returns empty memories array
- limit out of range (less than 1 or greater than 100) — returns 400 validation error
- caller has no stored memories — returns empty memories array
- authentication failure — returns 401 unauthorized

## How this service works

Recall memories matching a query (free).

## Output

An array of memory objects ranked by cosine distance (smaller = more relevant), each containing the memory ID, namespace, key, content text, distance score, a pinned flag (always surfaced ahead of distance-ranked results), and an is_summary flag (if true, the memory is a dreaming-consolidated summary that can be expanded via the /expand endpoint).

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "query"
 ],
 "properties": {
  "ns": {
   "type": "string",
   "maxLength": 128,
   "minLength": 1,
   "description": "Restrict recall to this namespace. Omit to search all of the caller's memories."
  },
  "limit": {
   "type": "integer",
   "maximum": 100,
   "minimum": 1,
   "description": "Max memories to return (default 10)."
  },
  "query": {
   "type": "string",
   "maxLength": 4096,
   "minLength": 1,
   "description": "Natural-language query to recall against."
  }
 },
 "additionalProperties": false
}
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "memories"
 ],
 "properties": {
  "memories": {
   "type": "array",
   "items": {
    "type": "object",
    "required": [
     "id",
     "ns",
     "key",
     "content",
     "distance",
     "pinned",
     "is_summary"
    ],
    "properties": {
     "id": {
      "type": "string"
     },
     "ns": {
      "type": "string"
     },
     "key": {
      "type": "string"
     },
     "pinned": {
      "type": "boolean",
      "description": "A \"standing order\" — always surfaced ahead of distance-ranked rows, exempt from dreaming."
     },
     "content": {
      "type": "string"
     },
     "distance": {
      "type": "number",
      "description": "Cosine distance (0 = identical, smaller = more relevant)."
     },
     "is_summary": {
      "type": "boolean",
      "description": "True if this row is a dreaming summary node. Pass its `id` to POST /api/v1/contexts/expand to read back the original memories it consolidated."
     }
    },
    "additionalProperties": false
   }
  }
 },
 "additionalProperties": false
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/memory-withzero-xyz-recall-memories-matching-a-query-242a8bfe/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from memory.withzero.xyz](https://www.zero.xyz/host/memory.withzero.xyz/llms.txt)