> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memoclaw.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recall Memories

> POST /v1/recall — Semantic search across your memories.

<Snippet file="snippets/x402-callout.mdx" />

**Price:** \$0.005 USDC

## Request Body

<ParamField body="query" type="string" required>
  Natural language search query. Max 32,768 characters.
</ParamField>

<ParamField body="limit" type="integer">
  Maximum number of results, 1–100. Default: `5`.
</ParamField>

<ParamField body="min_similarity" type="number">
  Minimum similarity threshold, 0–1. Default: `0.0`.
</ParamField>

<ParamField body="namespace" type="string">
  Filter results to a specific namespace.
</ParamField>

<ParamField body="session_id" type="string">
  Filter results to a specific session.
</ParamField>

<ParamField body="agent_id" type="string">
  Filter results to a specific agent.
</ParamField>

<ParamField body="include_relations" type="boolean">
  Include related memories in results. Default: `false`.
</ParamField>

<ParamField body="filters" type="object">
  Additional filters to narrow results.

  <Expandable title="Filter fields">
    <ParamField body="filters.tags" type="string[]">
      Match memories with any of these tags. Max 10.
    </ParamField>

    <ParamField body="filters.after" type="string">
      ISO 8601 date. Only return memories created after this date.
    </ParamField>
  </Expandable>
</ParamField>

## Scoring

<Info>
  **Hybrid recall scoring (4-signal approach):**

  ```
  hybrid = vector_sim × 0.55 + keyword_match × 0.25 + recency × 0.20
  score  = hybrid × context_importance × access_boost × type_decay
  ```

  Signals:

  * **vector\_sim**: Cosine similarity (0–1) — primary semantic signal
  * **keyword\_match**: Full-text/BM25 match, normalized (0–1) — exact term matches
  * **recency**: `exp(-age_days / 30)` — temporal freshness
  * **context\_importance**: Importance dynamically boosted by query relevance
  * **access\_boost**: `min(1 + access_count × 0.1, 2.0)` — frequently recalled memories rank higher
  * **type\_decay**: Exponential decay based on memory type half-life (correction: 180d, preference: 180d, decision: 90d, project: 30d, observation: 14d, general: 60d). Pinned memories are exempt from decay. Memories with more relations decay slower.

  When keyword match is strong (>0.3), its weight increases to 0.35 (vector drops to 0.45) for adaptive boosting.
</Info>

## Response (200)

<ResponseField name="memories" type="array">
  Array of matching memories.

  <Expandable title="Memory object fields">
    <ResponseField name="memories[].id" type="string">
      UUID of the memory.
    </ResponseField>

    <ResponseField name="memories[].content" type="string">
      The memory text.
    </ResponseField>

    <ResponseField name="memories[].similarity" type="number">
      Weighted similarity score.
    </ResponseField>

    <ResponseField name="memories[].metadata" type="object">
      Metadata attached to the memory.
    </ResponseField>

    <ResponseField name="memories[].importance" type="number">
      Importance value (0–1).
    </ResponseField>

    <ResponseField name="memories[].namespace" type="string">
      Namespace of the memory.
    </ResponseField>

    <ResponseField name="memories[].memory_type" type="string">
      Memory type: `correction`, `preference`, `decision`, `project`, `observation`, or `general`.
    </ResponseField>

    <ResponseField name="memories[].session_id" type="string | null">
      Session identifier, if set.
    </ResponseField>

    <ResponseField name="memories[].agent_id" type="string | null">
      Agent identifier, if set.
    </ResponseField>

    <ResponseField name="memories[].created_at" type="string">
      ISO 8601 creation timestamp.
    </ResponseField>

    <ResponseField name="memories[].access_count" type="number">
      Number of times this memory has been recalled.
    </ResponseField>

    <ResponseField name="memories[].pinned" type="boolean">
      Whether the memory is pinned (exempt from decay).
    </ResponseField>

    <ResponseField name="memories[]._signals" type="object">
      Signal breakdown for debugging/transparency. Includes `vector`, `keyword`, `recency`, `base_importance`, `effective_importance`, `context_importance`, `relation_count`, and `type_decay`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="query_tokens" type="number">
  Tokens used for the query embedding.
</ResponseField>

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.memoclaw.com/v1/recall \
    -H "Content-Type: application/json" \
    -d '{
      "query": "What are the user editor preferences?",
      "limit": 5,
      "filters": {
        "tags": ["preferences"]
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.memoclaw.com/v1/recall", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      query: "What are the user editor preferences?",
      limit: 5,
      filters: {
        tags: ["preferences"],
      },
    }),
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  from memoclaw import MemoClaw

  client = MemoClaw()
  result = client.recall(
      "What are the user editor preferences?",
      limit=5,
      tags=["preferences"],
  )
  ```
</CodeGroup>

```json Response theme={null}
{
  "memories": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "content": "User prefers dark mode and vim keybindings",
      "similarity": 0.89,
      "metadata": {
        "tags": ["preferences", "ui"]
      },
      "importance": 0.8,
      "memory_type": "preference",
      "namespace": "default",
      "session_id": null,
      "agent_id": null,
      "created_at": "2025-01-15T10:30:00Z",
      "access_count": 3,
      "pinned": false,
      "_signals": {
        "vector": 0.92,
        "keyword": 0.15,
        "recency": 0.78,
        "base_importance": 0.8,
        "effective_importance": 0.96,
        "context_importance": 0.98,
        "relation_count": 1,
        "type_decay": 0.95
      }
    }
  ],
  "query_tokens": 12
}
```