Skip to main content

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 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 https://api.memoclaw.com/v1/memories/core \
  -H "x-wallet-auth: 0xYourWallet:1699900000:0xSignature..."
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 -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"}'
Response
{
  "pinned": true,
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

​
Errors

StatusDescription
404Memory not found or belongs to another wallet.
422Invalid 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 -X DELETE https://api.memoclaw.com/v1/memories/core/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-wallet-auth: 0xYourWallet:1699900000:0xSignature..."
Response
{
  "unpinned": true,
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

​
Errors

StatusDescription
404Memory not found or not pinned.
422Invalid 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.