ClueState
Customer Intelligence Infrastructure
Understand every customer beyond the data. Turn fragmented customer interactions, transactions, and conversations into a continuously updated, evidence-backed customer state.
Give your customer service teams, personalization engines, and AI agents the structured context they need.
Overview
Organizations define what they want to know about their customers using typed State Schemas (Topic). ClueState ingests structured and unstructured interactions (Episode), extracts atomic claims (Memory), verifies source quotations (Evidence), and maintains the resulting entity state over time.
- Structured Customer State: Define typed schemas (
text,number,boolean,enum,list) with explicit cardinality (singlevs.multiple) and update policies (replace,append,review). - Evidence & Provenance: Every claim links to its source episode with programmatically verified character offsets (
char_start,char_end), source record IDs, interaction timestamps (occurred_at), and SHA-256 content hashes. - Explicit State Transitions: Rather than blindly overwriting by category, ClueState distinguishes between coexisting attributes (
add), supporting evidence (support), and superseding outdated facts (supersede). - Official Typed SDKs: Ergonomic, type-safe clients for Python (
ClueState&AsyncClueState) and TypeScript / JavaScript (@cluestate/sdk, zero dependencies, universalfetch). - Multi-Tenant Platform & UI: Includes workspace isolation, user authentication, scoped API keys (
cs_live_...), and a built-in dark-mode management UI (app.cluestate.comor self-hosted).
Business Applications
- Customer Service: Give support teams and workflows immediate access to a customer's reported issues, account tier, communication preferences, and prior resolutions—backed by source quotes.
- Personalization: Enrich customer profiles with brand affinities, sizing, price sensitivity, and behavioral patterns without overwriting coexisting preferences.
- AI Agents: Provide deterministic, structured entity state in system prompts or via the Model Context Protocol (MCP) instead of relying solely on raw transcript retrieval.
How State Maintenance Works
1. Define Topic Schemas
Topics act as an enforced schema contract rather than a loose prompt hint:
| Property | Purpose | Example (annual_budget) |
Example (brand_preferences) |
|---|---|---|---|
data_type |
Enforces and coerces value types | number |
list |
cardinality |
Whether an entity has one or many active values | single |
multiple |
update_policy |
How new claims interact with existing state | replace |
append |
When a customer with existing preferences for Nike and Adidas running shoes mentions buying Salomon trail shoes, cardinality: multiple (update_policy: append) ensures all three preferences coexist. When the same customer updates their annual budget from $10,000 to $15,000, cardinality: single (update_policy: replace) marks the $10,000 claim as superseded and promotes $15,000 as the active state.
2. Ingest an Interaction
Send an interaction via SDK or REST API:
# Python SDK
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="We migrated our primary database from MySQL to PostgreSQL last month. Our approved software budget for Q4 is $25,000, and we prefer technical updates via Slack.",
)
Or via TypeScript SDK / cURL
// TypeScript SDK
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: "We migrated our primary database from MySQL to PostgreSQL last month. Our approved software budget for Q4 is $25,000, and we prefer technical updates via Slack.",
});
# cURL
curl -X POST http://localhost:8000/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",
"source_record_id": "ticket_8841",
"idempotency_key": "evt_ticket_8841",
"occurred_at": "2026-10-31T14:20:00Z",
"content": "We migrated our primary database from MySQL to PostgreSQL last month. Our approved software budget for Q4 is $25,000, and we prefer technical updates via Slack."
}'
3. Extracted & Verified Output
ClueState validates extracted values against your topic schemas and verifies that every excerpt exists in the source episode:
{
"episode_id": 14,
"entity_id": 1,
"memories_extracted": 3,
"memories_updated": 1,
"memories_new": 2,
"idempotent_replay": false,
"memories": [
{
"id": 31,
"topic_name": "tech_stack",
"claim": "Uses PostgreSQL as primary database after migrating from MySQL",
"value": "PostgreSQL",
"structured_value": ["PostgreSQL"],
"claim_type": "explicit",
"confidence": 0.95,
"status": "active",
"evidence": [
{
"episode_id": 14,
"excerpt": "We migrated our primary database from MySQL to PostgreSQL last month.",
"is_verified": true,
"char_start": 0,
"char_end": 69
}
]
},
{
"id": 32,
"topic_name": "budget",
"claim": "Approved Q4 software budget is $25,000",
"value": "25000",
"structured_value": 25000,
"claim_type": "explicit",
"confidence": 0.95,
"status": "active",
"evidence": [
{
"episode_id": 14,
"excerpt": "Our approved software budget for Q4 is $25,000",
"is_verified": true,
"char_start": 70,
"char_end": 116
}
]
}
]
}
4. Query Customer State
# Python SDK
intel = client.get_intel(external_id="cust_402")
print(intel.formatted_prompt)
Or via TypeScript SDK / cURL
// TypeScript SDK
const intel = await cluestate.getIntel({ externalId: "cust_402" });
console.log(intel.formatted_prompt);
# cURL
curl http://localhost:8000/api/intel/by-external-id/cust_402 \
-H "Authorization: Bearer cs_live_YOUR_API_KEY"
Returns both the structured memories array (for application logic, CRMs, and personalization) and a pre-formatted formatted_prompt block (for LLM context injection).
Official SDKs (Python & TypeScript)
ClueState provides official typed SDKs for integrating continuous customer intelligence into your backend services, AI agent loops, and web applications.
Python SDK (Documentation · Package)
Install the lightweight client (no server or database dependencies):
pip install cluestate-sdk
# or install full engine: pip install cluestate
from cluestate import ClueState
client = ClueState(
api_key="cs_live_YOUR_API_KEY",
base_url="https://app.cluestate.com", # or http://localhost:8000
)
# 1. Ingest a customer interaction
response = client.ingest(
external_id="cust_402",
entity_name="Marcus Vance",
content="We migrated our primary database to PostgreSQL and set our Q4 budget to $25,000.",
source_type="support_ticket",
idempotency_key="evt_ticket_8841",
)
# 2. Retrieve verified customer state
intel = client.get_intel(external_id="cust_402")
print(intel.formatted_prompt)
Also includes AsyncClueState for asyncio services. See the Python SDK Reference and examples/python_quickstart.py.
TypeScript / JavaScript SDK (Documentation · Package)
Zero runtime dependencies. Runs natively in Node.js 18+, Bun, Deno, Cloudflare Workers, and Vercel Edge:
npm install @cluestate/sdk
# or: pnpm add @cluestate/sdk / bun add @cluestate/sdk
import { ClueState } from "@cluestate/sdk";
const cluestate = new ClueState({
apiKey: process.env.CLUESTATE_API_KEY!,
baseUrl: "https://app.cluestate.com", // or http://localhost:8000
});
// 1. Ingest an interaction
await cluestate.ingest({
externalId: "cust_402",
entityName: "Marcus Vance",
content: "We migrated our primary database to PostgreSQL and set our Q4 budget to $25,000.",
sourceType: "support_ticket",
idempotencyKey: "evt_ticket_8841",
});
// 2. Retrieve verified customer state
const intel = await cluestate.getIntel({ externalId: "cust_402" });
console.log(intel.formatted_prompt);
See the TypeScript SDK Reference and examples/typescript_quickstart.ts.
Installation & Deployment
Quickest Start: Use the SDK with ClueState Cloud
If you use app.cluestate.com, simply install the SDK (pip install cluestate-sdk or npm install @cluestate/sdk), get your API key from the web console, and start ingesting interactions.
Self-Hosting the ClueState Platform
Option 1: Docker Compose (PostgreSQL + API + Platform UI)
git clone https://github.com/cluestate/cluestate.git
cd cluestate
cp .env.example .env
# Edit .env to set OPENAI_API_KEY, POSTGRES_PASSWORD, and SECRET_KEY
docker compose up -d --build
Open http://localhost:8000 to create your workspace account and generate a cs_live_... API key.
Option 2: Local Python Installation (SQLite or PostgreSQL)
Requires Python 3.11+ and Node.js 20+ (to build the frontend assets):
git clone https://github.com/cluestate/cluestate.git
cd cluestate
# 1. Build the React platform UI
cd admin && npm install && npm run build && cd ..
# 2. Install the Python package in a virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .\.venv\Scripts\activate
pip install -e ".[postgres,dev]"
# 3. Configure environment and start the server
cp .env.example .env
cluestate serve
- Platform UI:
http://localhost:8000 - OpenAPI / Swagger Docs:
http://localhost:8000/docs - Health Check:
http://localhost:8000/api/health
Authentication & Security
All /api/* endpoints (except /api/health, /api/auth/signup, and /api/auth/login) require authentication via the HTTP Authorization header:
Authorization: Bearer cs_live_YOUR_WORKSPACE_API_KEY
- Workspace Accounts & JWTs: Sign up in the web UI (
/api/auth/signup) to create an isolated workspace. Interactive browser sessions authenticate with HMAC-SHA256 signed JWTs. - Scoped API Keys (
cs_live_...): Generate and revoke per-workspace API keys in the API & Settings tab. Keys are stored as SHA-256 hashes in the database. - Static Master Key (Optional): For single-tenant CLI automation, you can set
API_KEYin.envto authenticate against the default workspace.
Model Context Protocol (MCP) Server
ClueState includes an MCP server that works either directly against a local database or against a remote ClueState API instance (https://app.cluestate.com or self-hosted).
{
"mcpServers": {
"cluestate": {
"command": "cluestate",
"args": ["mcp"],
"env": {
"CLUESTATE_API_URL": "https://app.cluestate.com",
"CLUESTATE_API_KEY": "cs_live_your_key_here"
}
}
}
}
| Tool / Resource | Type | Description |
|---|---|---|
cluestate_ingest |
Tool | Ingest an interaction and extract claims with verified evidence |
cluestate_get_intel |
Tool | Retrieve the structured customer state summary for an entity |
cluestate_list_memories |
Tool | List claims for an entity with confidence, status, and verified quotes |
cluestate_search_entities |
Tool | Search entities by name or external ID |
cluestate_forget |
Tool | Delete a specific claim and its linked evidence by ID |
cluestate://entities/{external_id} |
Resource | Entity state context resource |
Configuration
ClueState uses LiteLLM and supports OpenAI, Anthropic, Google Gemini, or local Ollama models via environment variables:
| Variable | Default | Description |
|---|---|---|
LLM_MODEL |
openai/gpt-4o-mini |
LiteLLM model identifier |
OPENAI_API_KEY |
— | API key for OpenAI (or ANTHROPIC_API_KEY / GEMINI_API_KEY) |
DATABASE_URL |
sqlite+aiosqlite:///./cluestate.db |
Async SQLAlchemy database URL |
SECRET_KEY |
(auto-generated) | Secret key for signing JWT session tokens |
CORS_ORIGINS |
https://app.cluestate.com,... |
Comma-separated allowed CORS origins |
Documentation & Community
- System Architecture & State Resolution Engine — Deep dive into topic schemas, cardinality, evidence verification, and workspace isolation.
- Python SDK Documentation — Sync (
ClueState) and async (AsyncClueState) client reference. - TypeScript / JS SDK Documentation —
@cluestate/sdkclient reference for Node.js, Bun, Deno, and Edge runtimes. - Contributing Guide — Development setup, testing, and pull request workflow.
- Security Policy — Vulnerability reporting and security architecture.
- Changelog — Release history.
License
Apache 2.0 — see LICENSE for details.
Metadata
Release files for cluestate 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cluestate-0.1.0.tar.gz | 231.6 kB | Without provenance | Details for cluestate-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cluestate-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for cluestate-0.1.0-py3-none-any.whl |
Total release size: 381.1 kB
Release files / cluestate-0.1.0.tar.gz
| Download URL | cluestate-0.1.0.tar.gz |
|---|---|
| Size | 231.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a6263254c03f17489652a2653d0f0070d331ac33650e5e23de9f7040e91ab674
|
|
BLAKE2b-256 checksum How to use checksums |
eb9bfc583869b8f18e5f010a3912e5c51baae93c7b287215b645f5d36e046bbb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / cluestate-0.1.0-py3-none-any.whl
| Download URL | cluestate-0.1.0-py3-none-any.whl |
|---|---|
| Size | 149.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
08af93ed2215c1a8e0850e31f23f7867b474a55c40bd43e4392b47a4857f9898
|
|
BLAKE2b-256 checksum How to use checksums |
19e67e7094ff177f04a44d07bcb0b473fd61a71afb61a269a54c11a859d6365d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Security for cluestate 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.