Memory record

The MemoryRecord is memledger's atomic unit of memory. Every governance field is first-class — first-class fields are contract; ad-hoc metadata is convention.

Fields

Identity & content

Field	Type	Purpose
id	str	Stable identifier (UUID-string); what derived_from and supersedes reference.
content	str	The memory itself.
record_type	str	semantic / episodic / procedural.
namespace	str	Hierarchical scope, e.g. /ops/incidents/payment-svc. RBAC and conflict detection both gate on this.

Attribution

Field	Type	Purpose
created_by	str	Author agent. Auditable.
created_at	datetime	Auto-set on add().
session_id	str	Groups records from one agent run; aliased to OTel session.id.
workflow_id	str	Groups records across multi-agent flows.
triggered_by	str	What caused this write — alert id, ticket, parent task.

Confidence & lineage

Field	Type	Purpose
confidence	float [0,1]	The author's declared confidence.
hedged	bool	Author flagged this as a guess. Surfaces to consumers and deducts 5 points from the Memory Quality Score.
derived_from	list[str]	Provenance — the chain. Forms a DAG.
supersedes	Optional[str]	This record replaces an older record.

Governance (populated by memledger)

Field	Type	Purpose
confidence_flag	Optional[str]	PASS / FLAG / FILTER, set per search by the confidence gate.
quality_score	Optional[int]	Composite Memory Quality Score, 0–100.
conflicts	list[ConflictRef]	Near-duplicates detected at write time. See Conflicts.

Open metadata

Field	Type	Purpose
metadata	dict	Arbitrary domain-specific keys. Never used for governance.

Why first-class?

Sidecar metadata is convention-driven; first-class fields are contract. memledger's confidence gate, conflict detector, RTBF cascades, and MAI rubric all read these fields directly — they cannot be schema-drifted away by a careless add() call. The metadata dict exists for app-level extension and is intentionally outside that contract.

Where it goes

• Provenance chain — how derived_from becomes a DAG
• Effective confidence — how confidence becomes weakest-link bounded
• Conflicts — how same-namespace duplicates are detected at write time