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

namespace · string

Filter by namespace. Defaults to all namespaces.

limit · number · default: "20"

Maximum number of results (1–100).

offset · number · default: "0"

Pagination offset.

Response (200)

memories · array

Array of pinned memory objects.

total · number

Total count of core memories.

Example

curl

curl https://api.memoclaw.com/v1/memories/core \
  -H "x-wallet-auth: 0xYourWallet:1699900000:0xSignature..."

from memoclaw import MemoClaw

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

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();

Response

{
  "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

memory_id · string · required

UUID of the memory to pin.

Response (200)

pinned · boolean

Always true.

id · string

The pinned memory’s UUID.

Example

curl

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"}'

client.update("550e8400-e29b-41d4-a716-446655440000", pinned=True)

await client.update("550e8400-e29b-41d4-a716-446655440000", { pinned: true });

Response

{
  "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

id · string · required

UUID of the memory to unpin.

Response (200)

unpinned · boolean

Always true.

id · string

The unpinned memory’s UUID.

Example

curl

curl -X DELETE https://api.memoclaw.com/v1/memories/core/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-wallet-auth: 0xYourWallet:1699900000:0xSignature..."

client.update("550e8400-e29b-41d4-a716-446655440000", pinned=False)

await client.update("550e8400-e29b-41d4-a716-446655440000", { pinned: false });

Response

{
  "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

Good candidates for pinning:

• User identity (name, timezone, role)
• Foundational preferences that rarely change
• Critical project decisions
• Corrections that must persist indefinitely

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.

How Memory Works

Learn about type-based decay and why pinning matters.

Store Memory

Set pinned: true at store time to pin immediately.