Memo – dbzero

`@dbzero.memo(singleton: bool = False, prefix: str | None = None, no_default_tags: bool = False, immutable: bool = False, intern: bool = False, protect_fields: bool = False, access_control: bool = False)`

Open SourceStandard

The @dbzero.memo decorator is the core of dbzero, transforming a standard Python class into a persistent, memory-managed data model. It transparently handles the serialization, storage, and lifecycle of your objects, allowing you to interact with them as if they were regular in-memory instances.

Parameters

singleton bool, default False
When True, the decorated class becomes a singleton within its prefix. The first time you instantiate the class, the object is created and persisted. All subsequent calls to the constructor within the same prefix will return the existing instance, ignoring any new arguments.
prefix str, optional
Specifies a static namespace for the class and all its instances. This is useful for organizing data. If not provided, the class uses the current active prefix set by dbzero.open().
no_default_tags bool, default False
If True, dbzero will not automatically add default system tags (such as the class name) to new instances of this class.
immutable bool, default False
dbzero-procommercial edition
If True, instances use the dbzero-pro immutable memo layout. Fields are assigned during construction and are not intended to be mutated afterward. Immutable memo objects retain regular memo features such as tagging, references, drop by reference, UUIDs, fetch(), and typed find() queries.
intern bool, default False
dbzero-procommercial edition
If True, instances are content-addressed. Equal temporary Python instances of the same memo class resolve to the same canonical durable identity when materialized, UUID-ed, referenced, tagged, or otherwise given durable identity. The same UUID is guaranteed. This option requires immutable=True. Interned objects may reference other interned immutable memo objects, but not mutable or non-intern memo objects.
protect_fields bool, default False
dbzero-procommercial edition
If True, the memo class is marked for protected-field access. When data masking is activated with db0.init(..., data_masking={...}), dbzero checks reads, creates, updates, and deletes at Python object field access points. Denied reads raise PermissionError unless a missing-value placeholder is configured. See Security.
access_control bool, default False
dbzero-procommercial edition
If True, the memo class is marked as access controlled for data filtering predicates. When data filtering is activated with db0.init(..., data_filter={...}), dbzero applies the current db0.predicate(...) to access-controlled objects during queries, fetches, deserialized queries, and object-reference access. See Security.

Returns

The decorated Memo class.

Immutable memo objects are optimized for write-once data such as audit traces, events, append-only logs, and historical records. For complex immutable data graphs, embedded storage and the optimized object layout may reduce storage by up to 10-20x.

For interned memo classes, db0.materialized(...) forces content-index lookup immediately and returns the canonical standalone object. Calling db0.uuid(...), storing a reference, or tagging an interned value also resolves it to the canonical durable identity. Omitting explicit materialization lets dbzero materialize lazily, which is required when you want interned values embedded inside an immutable parent instead of first referenced as standalone objects.

Examples

In-depth explanation and examples can be found here

Immutable memo object

dbzero-procommercial edition

import dbzero as db0
 
@db0.memo(immutable=True)
class AuditEvent:
    def __init__(self, actor_id: str, action: str, payload: dict):
        self.actor_id = actor_id
        self.action = action
        self.payload = payload
 
event = AuditEvent(
    actor_id="user-123",
    action="invoice.approved",
    payload={"invoice_id": "inv-001"},
)
 
db0.tags(event).add("audit", "invoice")
 
event_uuid = db0.uuid(event)
same_event = db0.fetch(event_uuid)
 
assert same_event.action == "invoice.approved"
assert list(db0.find(AuditEvent, "invoice")) == [event]

Interned memo object

dbzero-procommercial edition

import dbzero as db0
 
@db0.memo(immutable=True, intern=True)
class EventLabel:
    def __init__(self, name: str):
        self.name = name
 
first = db0.materialized(EventLabel("invoice"))
second = db0.materialized(EventLabel("invoice"))
 
assert db0.uuid(first) == db0.uuid(second)

Use explicit materialization when you need a canonical standalone object or UUID immediately:

label = db0.materialized(EventLabel("payment"))
label_uuid = db0.uuid(label)

Calling db0.uuid(...) on an unmaterialized interned value also resolves equal content to the same durable identity:

first_uuid = db0.uuid(EventLabel("audit"))
second_uuid = db0.uuid(EventLabel("audit"))
 
assert first_uuid == second_uuid

Leave the interned value unmaterialized when you want dbzero to embed it into an immutable parent:

@db0.memo(immutable=True)
class LabeledEvent:
    def __init__(self, event_id: str, label: EventLabel):
        self.event_id = event_id
        self.label = label
 
event = LabeledEvent("evt-001", EventLabel("invoice"))

You can inspect the current content index size for an interned type with db0.get_type_stats(EventLabel)["content_index"]["size"].

materialized no