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 Filter by namespace. Defaults to all namespaces.
Maximum number of results (1–100).
Response (200) Array of pinned memory objects.
Total count of core memories.
Example curl https://api.memoclaw.com/v1/memories/core \ -H "x-wallet-auth: 0xYourWallet:1699900000:0xSignature..."
{ "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 UUID of the memory to pin.
Response (200) 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"}'
{ "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 UUID of the memory to unpin.
Response (200) 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..."
{ "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.
