Skip to main content

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.

License Status Python SDK TypeScript SDK Docker


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 (single vs. multiple) and update policies (replace, append, review). Values that violate a topic's type or enum contract are quarantined to pending_review rather 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 chronological occurred_at timestamps 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, universal fetch).
  • 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
  1. 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).
  2. 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.
  3. Static Master Key (Optional): For single-tenant CLI automation, you can set API_KEY in .env to 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


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)

Source distribution for cluestate 0.1.1
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)

Table of built distributions (wheels) for cluestate 0.1.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page