01 / ARCHITECTURE · THE STRUCTURED ENTITY-STATE ENGINE
Structured entity state. Traceable to verified source evidence.
ClueState acts as a governed state layer between raw interaction streams and application logic. It enforces schema contracts, retains source quotes with character offsets, and manages chronological state changes with explicit resolution policies.
02 / MODEL · DOMAIN HIERARCHY
The Core Entity Hierarchy
Workspace Isolation
Multi-tenant container. Scopes all entities, topics, episodes, API keys, and configurations.
The Target Object
Customer, user, or organization tracked via external ID (e.g. cust_402, user_819).
Interaction Event
Raw ticket, chat, transaction, or note with timestamp, source record ID, and idempotency key.
Extracted Claim
Atomic fact mapped to a topic schema with confidence, status (active/superseded/review).
Source Offsets
Verified character offsets (char_start, char_end) linking memory back to source text.
03 / CONTRACT · TOPIC SCHEMAS & UPDATE POLICIES
Governed Topic Contracts
Topics are schema contracts that instruct the extraction and resolution engines how values must behave. Rather than unconstrained text, ClueState enforces typed invariants.
PROPERTY
VALUES
PURPOSE
EXAMPLE
data_type
text | number | boolean | enum | list
Enforces value type coercion; invalid values are quarantined to pending_review.
annual_budget -> number
cardinality
single | multiple
Whether an entity has exactly one active value or multiple concurrent coexisting values.
tech_stack -> multiple
update_policy
replace | append | review
Determines resolution behavior when new evidence arrives for an existing topic.
replace: supersedes old value
04 / RESOLUTION · STATE OPERATIONS
Explicit State Resolution Outcomes
OPERATION: ADD
New Coexisting State
A topic with cardinality multiple records a new value (e.g. brand preference Salomon added alongside Nike and Adidas).
OPERATION: SUPPORT
Corroborating Evidence
New interaction reinforces an existing claim. Links secondary source offset and boosts confidence without duplicating the state record.
OPERATION: SUPERSEDE
Historical Transition
A newer chronological event replaces a single-value topic (e.g. budget 0,000 -> 5,000). Old value is marked superseded, retaining audit history.