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 { "record_id": "018f3c2a-...", "content_hash": "b3a7c2d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2", "parent_hash": "0000000000000000000000000000000000000000000000000000000000000000", "timestamp_hlc": 1751900065536000, "timestamp_ms": 1751900000000, "flags": 1, "payload": { "message": "Hello, SapixDB!", "ts": "2026-08-06" }, "schema_version": 0 } `

Field-by-field

record_id — UUID assigned at write time. Useful for external references.

content_hash — BLAKE3 hash of (parent_hash ‖ timestamp_hlc ‖ flags ‖ payload_msgpack). The record's permanent address. 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). Changing any record breaks its hash and every subsequent parent_hash, making tampering detectable.

timestamp_hlc — Hybrid Logical Clock timestamp: unix_milliseconds × 65536. The ×65536 gives 16 bits of logical counter so writes within the same millisecond stay ordered. timestamp_ms = timestamp_hlc >> 16.

timestamp_ms — Wall-clock milliseconds extracted from the HLC. Convenient for display and human-readable time conversion.

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.

HLC timestamp arithmetic

`python import time, datetime

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

# HLC → datetime unix_ms = 1751900065536000 >> 16 # same as // 65536 dt = datetime.datetime.fromtimestamp(unix_ms / 1000) print(dt) # 2026-08-06 ... `

Challenge

1. Fetch the record you wrote in Lesson 2 using its content_hash. Confirm parent_hash is all zeros (genesis record).
2. What would happen to all records after record #5 if you changed record #5's payload?

---