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

# List Memories

> GET /v1/memories — List memories with pagination and filters.

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

**Price:** FREE

## Query Parameters

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

<ParamField query="offset" type="integer">
  Pagination offset. Default: `0`.
</ParamField>

<ParamField query="tags" type="string">
  Comma-separated tags. Filter memories matching any of the specified tags.
</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 (200)

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

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

    <ResponseField name="memories[].user_id" type="string">
      UUID of the owning user.
    </ResponseField>

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

    <ResponseField name="memories[].content" type="string">
      The memory text.
    </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[].memory_type" type="string">
      Memory type: `correction`, `preference`, `decision`, `project`, `observation`, or `general`.
    </ResponseField>

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

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

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

    <ResponseField name="memories[].expires_at" type="string">
      ISO 8601 expiry date, if set.
    </ResponseField>

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

    <ResponseField name="memories[].updated_at" type="string">
      ISO 8601 last update timestamp.
    </ResponseField>

    <ResponseField name="memories[].accessed_at" type="string">
      ISO 8601 last access timestamp.
    </ResponseField>

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

<ResponseField name="total" type="number">
  Total number of matching memories.
</ResponseField>

<ResponseField name="limit" type="number">
  Applied limit.
</ResponseField>

<ResponseField name="offset" type="number">
  Applied offset.
</ResponseField>

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.memoclaw.com/v1/memories?limit=10&offset=0&tags=preferences,ui"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    limit: "10",
    offset: "0",
    tags: "preferences,ui",
  });

  const response = await fetch(
    `https://api.memoclaw.com/v1/memories?${params}`
  );

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

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

  client = MemoClaw()
  result = client.list(limit=10, tags=["preferences", "ui"])
  ```
</CodeGroup>

```json Response theme={null}
{
  "memories": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "namespace": "default",
      "content": "User prefers dark mode and vim keybindings",
      "metadata": {
        "tags": ["preferences", "ui"]
      },
      "importance": 0.8,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z",
      "accessed_at": "2025-01-20T14:22:00Z",
      "access_count": 3
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}
```