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

# Suggested Memories

> GET /v1/suggested — Get proactive memory suggestions for review.

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

**Price:** FREE

Suggested returns memories you *should* be reviewing based on access patterns and importance. Use this for proactive memory maintenance instead of only recalling on-demand.

## Categories

| Category   | Description                                                    |
| ---------- | -------------------------------------------------------------- |
| `stale`    | High importance but not recently accessed — might need refresh |
| `fresh`    | Recently stored but never accessed — verify they're useful     |
| `hot`      | Frequently accessed — your most valuable memories              |
| `decaying` | Approaching decay threshold — access soon or they'll fade      |

## Query Parameters

<ParamField query="limit" type="number">
  Max memories to return. Default: `10`, max: `50`.
</ParamField>

<ParamField query="category" type="string">
  Filter to a specific category: `stale`, `fresh`, `hot`, or `decaying`.
</ParamField>

<ParamField query="namespace" type="string">
  Filter by namespace.
</ParamField>

<ParamField query="session_id" type="string">
  Filter by session ID.
</ParamField>

<ParamField query="agent_id" type="string">
  Filter by agent ID.
</ParamField>

## Response

<ResponseField name="suggested" type="array">
  Array of suggested memories with category labels.
</ResponseField>

<ResponseField name="categories" type="object">
  Breakdown of counts per category.
</ResponseField>

<ResponseField name="total" type="number">
  Total suggestions available.
</ResponseField>

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.memoclaw.com/v1/suggested?limit=5&category=stale"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.memoclaw.com/v1/suggested?limit=5&category=stale"
  );
  const data = await response.json();
  ```

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

  client = MemoClaw()
  result = client.suggested(limit=5, category="stale")
  ```
</CodeGroup>

```json Response theme={null}
{
  "suggested": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "content": "User's API key for production is stored in 1Password",
      "metadata": { "tags": ["secrets"] },
      "importance": 0.9,
      "memory_type": "preference",
      "namespace": "default",
      "session_id": null,
      "agent_id": null,
      "created_at": "2024-01-01T08:00:00Z",
      "accessed_at": "2024-01-15T10:30:00Z",
      "access_count": 5,
      "relation_count": 2,
      "category": "stale",
      "review_score": 1.35
    }
  ],
  "categories": {
    "stale": 12,
    "fresh": 5,
    "hot": 8,
    "decaying": 3
  },
  "total": 28
}
```

<Tip>
  Run `/v1/suggested` periodically (e.g., daily) to maintain memory health. Accessing a memory resets its decay timer.
</Tip>