Record Anatomy

What you'll learn

Every field on a stored record — what each one is, how it is computed, and why it matters.

Read back what you wrote

# Replace <HASH> with the content_hash from Lesson 2
curl -s http://localhost:7475/v1/agents/my-first-agent/records/<HASH> \
  -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
  | python3 -m json.tool

Response: `json { "content_hash": "b3a7c2d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2", "parent_hash": "0000000000000000000000000000000000000000000000000000000000000000", "ts_hlc": 1751900065536000, "flags": 1, "payload": { "message": "Hello, SapixDB!", "ts": "2026-07-09" }, "signature": "ed25519:3a7f..." } `

Field-by-field

content_hash — BLAKE3 hash of (parent_hash ‖ ts_hlc ‖ flags ‖ payload_msgpack). This is the record's permanent address. It is computed deterministically — if two agents write identical content at the same HLC, they get the same hash.

parent_hash — The content_hash of the previous record in this strand. The first record ever written has parent_hash = "000...000" (64 zeros). This is what makes the chain tamper-evident: changing any record changes its hash, which breaks every subsequent parent_hash.

ts_hlc — Hybrid Logical Clock timestamp: unix_milliseconds × 65536. To convert back: ts_hlc // 65536 = unix_ms. The ×65536 gives 16 bits of logical counter so writes within the same millisecond stay ordered.

flags — Bit field: - 0x01 = genesis (first record on the strand) - 0x02 = tombstone (soft delete) - 0x20 = encrypted payload (set by the engine, not you)

payload — Your JSON data. Stored internally as MessagePack, encrypted with AES-256-GCM using a per-agent key derived from SAPIX_MASTER_SEED. Returned to you as decrypted JSON.

signature — Ed25519 signature over content_hash, made by the agent's keypair derived from SAPIX_KEYPAIR_SEED_HEX. Anyone who knows the agent's public key can verify this offline.

HLC timestamp arithmetic

`python import time, datetime

# Current HLC hlc = int(time.time() * 1000) * 65536

# HLC → datetime unix_ms = 1751900065536000 // 65536 dt = datetime.datetime.fromtimestamp(unix_ms / 1000) print(dt) # 2026-07-09 ... `

Challenge

1. Write two records in rapid succession. Is the second record's parent_hash equal to the first record's content_hash?
2. What would happen to all records after record #5 if you changed record #5's payload?

---