Soul Memory Architecture

On-Chain Structure

// Shared object — one per Soul, bound at mint
public struct SoulMemory has key {
    id: UID,
    soul_id: ID,
    entries: Table<u64, ID>,      // timestamp_key (ms) → blob_object_id
    entry_count: u64,
}

// Walrus Blob stored as dynamic object field
public struct MemoryBlobKey has copy, drop, store {
    timestamp_key: u64,
}

The entries table maps a timestamp_key (milliseconds from the Sui clock at write time) to the Walrus Blob object ID. If two entries land in the same millisecond, the contract increments the key until it finds a free slot. The Blob object itself is stored as a dynamic object field under MemoryBlobKey, making it inspectable on-chain.

Writer Kinds

The MemoryEntryAppended event records writer_kind, writer address, timestamp_key, and blob_object_id. The DB mirrors these from the event log.

Encrypted by Default

All memory entries are Seal-encrypted at upload time. The document ID is bound to the SoulMemory object ID and the timestamp_key:

"soul-memory:" + version_byte(1) + memory_id_bytes(32) + timestamp_key_be(8) + nonce(16)

This means only the Soul owner (or a holder of an active SCOPE_MEMORY grant) can decrypt any entry. There is no public memory mode.

DB Mirror Fields

After a successful on-chain append, the API mirrors a SoulMemoryEntry row with these key fields:

• memoryOnChainId — the SoulMemory shared object ID
• timestampKey — the on-chain table key (bigint, stored as decimal string in JSON)
• writerAddress — the address that signed the append TX
• writerKind — "founder" | "owner" | "granted-agent"
• blobObjectId — Sui object ID of the Walrus Blob
• blobId — Walrus blob ID (used to build the download URL)
• sealSidecar — encrypted DEK envelope for client-side decryption

The entry is looked up by (memoryOnChainId, timestampKey) — not by a legacy entry object ID. This is the canonical addressing scheme.

Memory Access API

• GET /api/souls/[id]/memory/[entryKey]/access
  Returns a MemoryAccessResponse containing the Walrus blob URL, sidecar, Seal server config, and approval policy. The entryKey path segment is the decimal timestamp_key.
• The route validates the viewer identity from the wallet session or agent API key, checks rate limits (30 req/min), and resolves the access via resolveMemoryAccessPayload — which fetches live SoulState from chain to verify ownership or active grant.
• Credentialed Seal server configs are not permitted for browser access. Server-side agent access uses a separate code path.

// Access response shape
{
  artifact: { walrusBlobUrl, walrusBlobId, blobObjectId },
  accessPolicy: {
    packageId, stateObjectId, memoryObjectId, timestampKey,
    moduleName: "seal_policy",
    functionName: "seal_approve_memory_owner" | "seal_approve_memory_granted_agent",
    soulGrantObjectId: string | null,
    documentIdHex: string,
  },
  seal: { network, threshold, serverConfigs, verifyKeyServers },
  sealSidecar: { encryptedDek, iv, cipher, fileName, mimeType, contentHash },
  viewerAddress: string,
  accessKind: "owner" | "granted-agent",
  sessionTtlMin: number,
}