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

# Core Memories

> Pin important memories to exempt them from type-based decay.

Core memories are pinned memories that are exempt from type-based decay. Use them for critical facts that should persist indefinitely — user identity, foundational preferences, or key decisions that never expire.

**Price:** FREE (all core memory endpoints)

## GET /v1/memories/core

List all pinned core memories for your wallet.

### Query Parameters

<ParamField query="namespace" type="string">
  Filter by namespace. Defaults to all namespaces.
</ParamField>

<ParamField query="limit" type="number" default="20">
  Maximum number of results (1–100).
</ParamField>

<ParamField query="offset" type="number" default="0">
  Pagination offset.
</ParamField>

### Response (200)

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

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

### Example

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.memoclaw.com/v1/memories/core \
    -H "x-wallet-auth: 0xYourWallet:1699900000:0xSignature..."
  ```

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

  client = MemoClaw()
  core = client.list(filters={"pinned": True})
  for m in core.memories:
      print(f"[core] {m.content}")
  ```

  ```typescript TypeScript theme={null}

  import { MemoClawClient } from "memoclaw";

  const client = new MemoClawClient();
  const response = await fetch("https://api.memoclaw.com/v1/memories/core", {
    headers: { "x-wallet-auth": await getAuthHeader() },
  });
  const { memories } = await response.json();
  ```
</CodeGroup>

```json Response theme={null}
{
  "memories": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "content": "User's name is Ana",
      "importance": 1.0,
      "pinned": true,
      "memory_type": "preference",
      "tags": ["identity"],
      "created_at": "2026-02-01T12:00:00Z"
    }
  ],
  "total": 1
}
```

***

## POST /v1/memories/core

Pin an existing memory as a core memory. Pinned memories are exempt from type-based decay — they never fade regardless of their `memory_type` half-life.

### Request Body

<ParamField body="memory_id" type="string" required>
  UUID of the memory to pin.
</ParamField>

### Response (200)

<ResponseField name="pinned" type="boolean">
  Always `true`.
</ResponseField>

<ResponseField name="id" type="string">
  The pinned memory's UUID.
</ResponseField>

### Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.memoclaw.com/v1/memories/core \
    -H "Content-Type: application/json" \
    -H "x-wallet-auth: 0xYourWallet:1699900000:0xSignature..." \
    -d '{"memory_id": "550e8400-e29b-41d4-a716-446655440000"}'
  ```

  ```python Python theme={null}
  client.update("550e8400-e29b-41d4-a716-446655440000", pinned=True)
  ```

  ```typescript TypeScript theme={null}
  await client.update("550e8400-e29b-41d4-a716-446655440000", { pinned: true });
  ```
</CodeGroup>

```json Response theme={null}
{
  "pinned": true,
  "id": "550e8400-e29b-41d4-a716-446655440000"
}
```

### Errors

| Status | Description                                    |
| ------ | ---------------------------------------------- |
| 404    | Memory not found or belongs to another wallet. |
| 422    | Invalid UUID format.                           |

***

## DELETE /v1/memories/core/:id

Unpin a core memory. The memory is not deleted — it simply resumes normal type-based decay.

### Path Parameters

<ParamField path="id" type="string" required>
  UUID of the memory to unpin.
</ParamField>

### Response (200)

<ResponseField name="unpinned" type="boolean">
  Always `true`.
</ResponseField>

<ResponseField name="id" type="string">
  The unpinned memory's UUID.
</ResponseField>

### Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE https://api.memoclaw.com/v1/memories/core/550e8400-e29b-41d4-a716-446655440000 \
    -H "x-wallet-auth: 0xYourWallet:1699900000:0xSignature..."
  ```

  ```python Python theme={null}
  client.update("550e8400-e29b-41d4-a716-446655440000", pinned=False)
  ```

  ```typescript TypeScript theme={null}
  await client.update("550e8400-e29b-41d4-a716-446655440000", { pinned: false });
  ```
</CodeGroup>

```json Response theme={null}
{
  "unpinned": true,
  "id": "550e8400-e29b-41d4-a716-446655440000"
}
```

### Errors

| Status | Description                     |
| ------ | ------------------------------- |
| 404    | Memory not found or not pinned. |
| 422    | Invalid UUID format.            |

***

## When to Use Core Memories

<Tip>
  **Good candidates for pinning:**

  * User identity (name, timezone, role)
  * Foundational preferences that rarely change
  * Critical project decisions
  * Corrections that must persist indefinitely
</Tip>

<Warning>
  **Avoid over-pinning.** If everything is a core memory, nothing is. Reserve pinning for truly permanent facts. Most memories benefit from natural decay — it keeps recall results relevant.
</Warning>

<CardGroup cols={2}>
  <Card title="How Memory Works" icon="brain" href="/concepts/how-memory-works">
    Learn about type-based decay and why pinning matters.
  </Card>

  <Card title="Store Memory" icon="database" href="/api-reference/store">
    Set `pinned: true` at store time to pin immediately.
  </Card>
</CardGroup>