01 // CUSTOMER & ENTITY STATE INFRASTRUCTURE
Turn customer interactions into an index of decisions.
01 // RETAIL & POS
STREAMING
"Salomon Speedcross · Size 43 ·
45"02 // SUPPORT CALL
STANDBY
"Migrated to PostgreSQL · Q4 budget $25,000"
03 // USER SURVEY
STANDBY
"NPS 9/10 · Goal: Churn < 2%"
04 // CRM & EMAIL
STANDBY
"Requires SOC2 · Prefers Slack updates"
05 // AI COMPANION
STANDBY
"Oct Mountain Marathon · Knee-sensitive"
ENTITY LEDGER // MARCUS VANCE (
cust_402
)
sha256: 9f4c...8a2e [VERIFIED]
brand_affinities · multiple · append
3 ACTIVE
Nike, Adidas, + Salomon (Size 43)
approved_q4_budget · single · replace
REPLACED
$25,000 USD
customer_health_goal · single · replace
ACTIVE
Churn < 2% · NPS 9/10
tech_and_ops_stack · single · replace
VERIFIED
PostgreSQL · Slack · SOC2 Req
ai_companion_memory · multiple · append
MCP READY
Oct Marathon · Knee-Sensitive
CONSUMPTION: CRM · MCP AGENTS · APIS
OFFSET VERIFIED
[0..116]
PROGRAMMATIC CHARACTER-OFFSET VERIFICATION
03
SCHEMA POLICIES: REPLACE, APPEND, OR QUARANTINE
SHA-256
TAMPER-EVIDENT SOURCE EPISODE PROVENANCE
0-DEP
OFFICIAL PYTHON & ZERO-DEPENDENCY TYPESCRIPT SDKS
02 // THE CONTEXT GAP
Your systems store what happened. Not what is current.
Transcripts, tickets, and CRM notes are append-only chronologies. They tell you what was once said, not what remains true. ClueState runs between raw customer communication and your operational state, extracting atomic claims and resolving them into deterministic entity profiles.
PANEL A: INCOMING INTERACTION STREAM (UI FEED)
AUTO-PLAYING
[ACTIVE] 2026-10-31 · ticket_8841
EXTERNAL ID: cust_402
"Migrated DB to PostgreSQL. Approved Q4 budget is
[$25,000]
."
2026-10-31 · ticket_8841
EXTERNAL ID: cust_402
"Migrated primary DB to
[PostgreSQL]
; updates via Slack."
2026-10-14 · order_309
EXTERNAL ID: cust_402
"Purchased
[Salomon Speedcross trail shoes]
for winter training."
2026-11-02 · csv_import_2025 (occurred_at: 2025-04-10)
EXTERNAL ID: cust_402
"Historical CRM dump:
[Initial pilot budget $5,000]
."
3000ms CYCLE
PANEL B: CLUESTATE STORED MEMORY LEDGER // CUST_402
MAINTAINED PROJECTION
TOPIC
STORED MEMORY VALUE
PROVENANCE
STATUS
annual_budget
$25,000 USD
(Replaced
0k)char 70..116 · ticket_8841
•ACTIVE
tech_stack
["PostgreSQL"]
char 0..49 · ticket_8841
ACTIVE
brand_affinity
["Nike", "Salomon"]
char 10..37 · order_309
APPENDED
historical_audit
$5,000 (2025 Import)
occurred 2025 (Event-Time)
GUARDED
EVENT-TIME DETERMINISM:
Older out-of-order events never corrupt newer active state projections.
03 // THE 4-STAGE PIPELINE
From raw episode to verified state.
01
STAGE 01 // DEFINE TOPIC SCHEMAS
[CONTRACT]
Enforced State Contracts, Not Prompt Hints
Define typed attributes (text, number, boolean, enum, list) with explicit cardinality and update policies.
cardinality: single | multiple · policy: replace | append | review
02
STAGE 02 // INGEST EPISODES
[EPISODE]
Idempotent Interaction & Event Ingestion
Stream support tickets, transcripts, notes, or custom domain events with idempotency_key deduplication and chronological occurred_at timestamps.
POST /api/ingest · client.ingest(external_id, content)
03
STAGE 03 // VERIFY & RESOLVE
[PROVENANCE]
Programmatic Offset Check & State Resolution
Every quoted excerpt is verified against the stored episode text with exact character coordinates and SHA-256 hashes. Schema violations quarantine safely to pending_review.
char_start · char_end · is_verified: true · SHA-256
04
STAGE 04 // RETRIEVE INTEL
[READ STATE]
Structured JSON & Prompt-Ready Context
Query active entity state as typed memories[] for application logic and CRMs, or inject formatted_prompt directly into agents via SDK or MCP.
client.get_intel("cust_402") · cluestate_get_intel
04 // STATE RESOLUTION ENGINE
Three deterministic laws govern how state mutates.
Source excerpt verification confirms that every extracted claim exists in the record. Mutation policies dictate what happens next. No silent overwrites, no hallucinations.
LAW 01 — SUPERSEDE
number · single · replace
TOPIC: annual_budget
INCOMING SOURCE EXCERPT (ticket_8841)
“Our approved software budget for Q4 is $25,000”
char_start: 70..116 · VERIFIED
RESOLUTION GATE
25000 > t_prev
Single active slot -> promote new, archive prior
$25,000
ACTIVE
SUPERSEDED
LAW 02 — COEXIST
list · multiple · append
TOPIC: brand_preferences
INCOMING SOURCE EXCERPT (order_note_309)
“Picked up Salomon trail running shoes for winter ultra training.”
char_start: 10..37 · VERIFIED
RESOLUTION GATE
operation: add
Multiple cardinality -> append without overwrite
["Nike", "Adidas", "Salomon"]
3 coexisting claims
ALL ACTIVE
LAW 03 — QUARANTINE
contract violation -> pending_review
TOPIC: annual_budget (expects number)
AMBIGUOUS STATEMENT (call_note_912)
“Next year’s software budget is undecided until Q1 board review.”
extracted: "undecided until Q1"
SCHEMA GUARD
TypeMismatch: NaN
Blocked from active projection
"undecided until Q1"
PENDING_REVIEW
Active state remains intact at $25,000.
05 // APPLICATIONS
One maintained state layer. Every surface.
05.1 // SUPPORT
Customer Service & Support Workflows
Give support teams immediate access to reported issues, account tier, communication preferences, and prior resolutions — backed by inspectable source quotes before they ask the customer again.
account_tier · open_blockers · comm_preference: "Slack" · prior_resolution
05.2 // PROFILES
Personalization & CRM Enrichment
Maintain coexisting brand affinities, sizing, and price sensitivity across interactions under multiple / append rules without flattening customer nuance into a single overwritten string.
brand_preferences: ["Nike", "Adidas", "Salomon"] · sizing · price_sensitivity
05.3 // AGENTS
AI Agents & Model Context Protocol (MCP)
Inject deterministic, structured entity state directly into system prompts via REST or native MCP (cluestate_get_intel) instead of relying solely on noisy raw transcript RAG.
cluestate://entities/{external_id} -> memories[] + formatted_prompt
FIRST-PARTY ARCHITECTURAL EXAMPLE // ELEVIST
Beyond customer data: personal execution state.
Elevist — an AI execution system in our product ecosystem organized around goals, metrics, tasks, habits, notes, and reviews — illustrates the same challenge on personal state. While Elevist owns canonical operational records, ClueState's state model turns reflections and check-ins into durable, source-linked context for AI planning.
ILLUSTRATIVE PERSONAL STATE SCHEMA
current_focus
single · replace
active_goals
multiple · append
active_blockers
multiple · review
user_preferences
multiple · append
06 // DEVELOPER SURFACE
A small integration surface. Typed end to end.
Use the official Python (cluestate-sdk) or zero-dependency TypeScript (@cluestate/sdk) clients, call the REST API directly, or connect any MCP-compatible agent.
$ pip install cluestate-sdk
$ npm install @cluestate/sdk
NATIVE MCP TOOL REGISTER
cluestate mcp
cluestate_ingest
Extract & verify claims
cluestate_get_intel
Structured state summary
cluestate_list_memories
Claims + verified quotes
cluestate_search_entities
Lookup by name / ext ID
cluestate_forget
Delete claim & evidence
SPECIMEN // END-TO-END INGEST & RETRIEVE
01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16
from cluestate_sdk import ClueState client = ClueState( api_key="cs_live_YOUR_API_KEY", base_url="https://app.cluestate.com" )
# 1. Ingest customer interaction with idempotency key client.ingest( external_id="cust_402", entity_name="Marcus Vance", source_type="support_ticket", source_record_id="ticket_8841", idempotency_key="evt_ticket_8841", occurred_at="2026-10-31T14:20:00Z", content="Migrated DB to PostgreSQL. Approved Q4 budget is $25,000.", )
# 2. Retrieve verified customer state intel = client.get_intel(external_id="cust_402") print(intel.formatted_prompt)
01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16
import { ClueState } from "@cluestate/sdk"; const cluestate = new ClueState({ apiKey: process.env.CLUESTATE_API_KEY!, baseUrl: "https://app.cluestate.com", });
// 1. Ingest interaction (zero dependencies, universal fetch) await cluestate.ingest({ externalId: "cust_402", entityName: "Marcus Vance", sourceType: "support_ticket", sourceRecordId: "ticket_8841", idempotencyKey: "evt_ticket_8841", occurredAt: "2026-10-31T14:20:00Z", content: "Migrated DB to PostgreSQL. Approved Q4 budget is $25,000.", });
// 2. Retrieve structured memories[] + formatted_prompt const intel = await cluestate.getIntel({ externalId: "cust_402" }); console.log(intel.formatted_prompt);
01 02 03 04 05 06 07 08 09 10 11
curl -X POST https://app.cluestate.com/api/ingest \ -H "Authorization: Bearer cs_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "external_id": "cust_402", "entity_name": "Marcus Vance", "source_type": "support_ticket", "idempotency_key": "evt_ticket_8841", "occurred_at": "2026-10-31T14:20:00Z", "content": "Migrated DB to PostgreSQL. Approved Q4 budget is $25,000." }'
01 02 03 04 05 06 07 08 09 10 11 12
{ "mcpServers": { "cluestate": { "command": "cluestate", "args": ["mcp"], "env": { "CLUESTATE_API_URL": "https://app.cluestate.com", "CLUESTATE_API_KEY": "cs_live_your_key_here" } } } }
VERIFIED OUTPUT PAYLOAD // EPISODE #14
idempotent_replay: false · is_verified: true
{ "episode_id": 14, "memories_extracted": 2, "memories_updated": 1, "memories": [{ "id": 32, "topic_name": "annual_budget", "structured_value": 25000, "confidence": 0.95, "status": "active", "evidence": [{ "episode_id": 14, "is_verified": true, "char_start": 70, "char_end": 116, "excerpt": "Our approved software budget for Q4 is $25,000" }] }] }
07 // DEPLOYMENT & GOVERNANCE
Use ClueState Cloud. Or run the engine yourself.
STRICT MULTI-TENANCY
Workspace-isolated entities, topics, episodes, and claims.
SHA-256 API KEYS
cs_live_... hashed at rest; privilege-separated from key admin.
MODEL AGNOSTIC
OpenAI, Anthropic, Gemini, or local Ollama via LiteLLM.
APACHE 2.0 LICENSE
Inspect every SQL migration, offset check, and state transition.
01 // SELF-HOSTED ENGINE
FREE FOREVER · APACHE 2.0
Run Full Stack in Your Own VPC
Deploy PostgreSQL, the FastAPI state engine, automatic Alembic migrations, and the built-in management UI in your own environment using identical SDK interfaces.
$ git clone https://github.com/cluestate/cluestate.git $ cd cluestate && cp .env.example .env $ docker compose up -d --build
02 // CLUESTATE CLOUD
MANAGED INFRASTRUCTURE
Zero-Ops Hosted State Engine
Instant workspace provisioning, managed PostgreSQL state persistence, background claim extraction and character-offset verification, and the full management UI without operating infrastructure.
USAGE-BASED INFRASTRUCTURE MODEL
NO PER-SEAT TAX
PROCESSING METER
Scales with episodes ingested & resolved. Idempotent replays do not double-bill; standard get_intel reads are included.
MODEL INFERENCE
Supply your own provider key (BYOK) or use ClueState Cloud managed model allowance.