ClueState
Evidence-backed customer and entity intelligence infrastructure.
Understand every customer beyond the data. Turn fragmented customer interactions, transactions, and conversations into a continuously updated, evidence-backed entity 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 or entities 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 according to explicit rules.
- Enforced State Schemas: Define typed contracts (
text,number,boolean,enum,list) with explicit cardinality (singlevs.multiple) and update policies (replace,append,review). Values that violate a topic's type or enum contract are quarantined topending_reviewrather than entering active state. - 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. - Event-Time State Resolution: Distinguishes between coexisting attributes (
add), corroborating evidence (support), and superseding facts (supersede), while respecting chronologicaloccurred_attimestamps so late-arriving historical imports do not overwrite newer state. - 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, privilege-separated API keys (
cs_live_...), Alembic database migrations, and a built-in dark-mode management UI.
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 includes official typed SDKs in sdks/python and sdks/typescript for integrating continuous customer and entity intelligence into backend services, AI agent loops, and web applications.
Python SDK (Documentation · sdks/python)
Option A — Lightweight Client (cluestate-sdk, depends only on httpx and pydantic):
pip install cluestate-sdk
from cluestate_sdk import ClueState
client = ClueState(
api_key="cs_live_YOUR_API_KEY",
base_url="http://localhost:8000", # or your deployed ClueState instance URL
)
# 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("cust_402")
print(intel.formatted_prompt)
Option B — Full Platform Distribution (cluestate):
pip install cluestate
from cluestate import ClueState, AsyncClueState
See the Python SDK Reference and examples/python_quickstart.py.
TypeScript / JavaScript SDK (Documentation · sdks/typescript)
Zero runtime dependencies. Runs natively in Node.js 18+, Bun, Deno, Cloudflare Workers, and Vercel Edge:
npm install @cluestate/sdk
import { ClueState } from "@cluestate/sdk";
const cluestate = new ClueState({
apiKey: process.env.CLUESTATE_API_KEY!,
baseUrl: "http://localhost:8000", // or your deployed ClueState instance URL
});
// 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 & Self-Hosting
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 (required)
docker compose up -d --build
Open http://localhost:8000 to create your workspace account and generate a cs_live_... API key. Database migrations run automatically via Alembic on startup (cluestate migrate).
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, which are required for user and API-key administration (/api/auth/api-keys). - Privilege-Separated API Keys (
cs_live_...): Generate and revoke per-workspace API keys in the API & Settings tab. Keys are stored as SHA-256 hashes, scoped to data-plane operations within their workspace, and explicitly blocked (403 Forbidden) from minting or revoking keys. - Static Master Key (Optional): For single-tenant CLI automation, you can set
API_KEYin.envto authenticate data-plane requests 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.1
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.1.tar.gz | 242.8 kB | With provenance | Details for cluestate-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cluestate-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for cluestate-0.1.1-py3-none-any.whl |
Total release size: 398.2 kB
Release files / cluestate-0.1.1.tar.gz
| Download URL | cluestate-0.1.1.tar.gz |
|---|---|
| Size | 242.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4e2c0021eaee88ba9c60da3ca30a9056c4b1d6f7395c11ffe5b6721723d49e44
|
|
BLAKE2b-256 checksum How to use checksums |
e8d9fa14d7ccfb760720f26f7d1e6b866107543f9c5f31bbb175b281965f1db4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.
Transparency logRelease files / cluestate-0.1.1-py3-none-any.whl
| Download URL | cluestate-0.1.1-py3-none-any.whl |
|---|---|
| Size | 155.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
256343f3f8a1f02a6b92aa0c08baede86e9675ade4bd9468650bdd0d82c71a54
|
|
BLAKE2b-256 checksum How to use checksums |
018a4df87de0be8e2b1260d0e27dfd454a17a5c16eb07740c0851488f5797c40
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.
Transparency logSecurity for cluestate 0.1.1
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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for cluestate-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.
Transparency logA 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.