> ## 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

**query** `string` *required*

Natural language search query. Max 32,768 characters.

**limit** `integer`

Maximum number of results, 1–100. Default: `5`.

**min\_similarity** `number`

Minimum similarity threshold, 0–1. Default: `0.0`.

**namespace** `string`

Filter results to a specific namespace.

**session\_id** `string`

Filter results to a specific session.

**agent\_id** `string`

Filter results to a specific agent.

**include\_relations** `boolean`

Include related memories in results. Default: `false`.

**filters** `object`

Additional filters to narrow results.

**Filter fields**

**filters.tags** `string[]`

Match memories with any of these tags. Max 10.

**filters.after** `string`

ISO 8601 date. Only return memories created after this date.

## Scoring

> [!NOTE]
>
> **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.

## Response (200)

**memories** `array`

Array of matching memories.

**Memory object fields**

**memories\[].id** `string`

UUID of the memory.

**memories\[].content** `string`

The memory text.

**memories\[].similarity** `number`

Weighted similarity score.

**memories\[].metadata** `object`

Metadata attached to the memory.

**memories\[].importance** `number`

Importance value (0–1).

**memories\[].namespace** `string`

Namespace of the memory.

**memories\[].memory\_type** `string`

Memory type: `correction`, `preference`, `decision`, `project`, `observation`, or `general`.

**memories\[].session\_id** `string | null`

Session identifier, if set.

**memories\[].agent\_id** `string | null`

Agent identifier, if set.

**memories\[].created\_at** `string`

ISO 8601 creation timestamp.

**memories\[].access\_count** `number`

Number of times this memory has been recalled.

**memories\[].pinned** `boolean`

Whether the memory is pinned (exempt from decay).

**memories\[].\_signals** `object`

Signal breakdown for debugging/transparency. Includes `vector`, `keyword`, `recency`, `base_importance`, `effective_importance`, `context_importance`, `relation_count`, and `type_decay`.

**query\_tokens** `number`

Tokens used for the query embedding.

## Example

```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"],
)
```

```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
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.