CueCruxVaultCrux

SDKs · 0. Which SDK should I use?

Talking to the Crux Daemon: install @cuecrux/client for TypeScript, or corecrux-client for Python. Both live in the Crux repository under sdks/, and the daemon's own developer portal names them "the supported public SDK surface" (docs/developer-portal.md:61). Talking to the CueCrux Engine, a different service with a different API; your only client is @cuecrux/engine-client, and you should read chapter 6 before you depend on it.

Everything else published under the @cuecrux/ npm scope comes from a second, unrelated repository called SDKCrux, which last shipped on 2026-06-12. Neither repository mentions the other. Chapter 5 documents that estate for people already using it; this chapter tells you when it applies, which is rarely.

This chapter is explanation: why the landscape looks like this and how to choose within it. The per-package reference is chapters 1, 2 and 5.

0.0 In plain English

An SDK is a library that wraps an HTTP API so that you call a function instead of assembling a request. Nothing here is doing anything you could not do with curl. What it saves you is the tedious and easily-got-wrong part: building the URL, attaching the auth header in the right form, serialising the body, decoding the error shape, and giving you types your editor understands.

The reason this chapter exists at all is less happy than that, and you should know it before you install anything. There are two unrelated code estates publishing packages into the same @cuecrux/ npm scope, and neither repository mentions the other. Scope membership is therefore not evidence of anything. Two packages sitting next to each other in the registry may come from different teams, different repositories and different release cadences, and one of them may be considerably staler than the other.

You will read this chapter exactly once, before you install, and the payoff is that you install the right thing first time. §0.1 is the decision table and is the whole answer if you are in a hurry. §0.2 states what each registry actually serves today, which is worth checking rather than assuming, because a package existing is not the same as a package being current.

The thing people get wrong is treating the daemon client and the Engine client as interchangeable because the names look like siblings. They are not. They talk to two different services with two different APIs, and pointing one at the other does not fail in an obvious way at install time. Work out which service you are talking to first, then pick the client, and read §0.5 for the things none of these libraries do for you regardless of which you choose.

0.1 Decision table

What you are doingLanguageInstallChapterStatus
Read and write facts, sessions and queries on the Crux DaemonTypeScript / JavaScriptnpm install @cuecrux/client1SHIPPED
Read and write facts, sessions and queries on the Crux DaemonPythonpip install corecrux-client2SHIPPED
Subscribe to daemon mutation events over SSETypeScript onlynpm install @cuecrux/client1SHIPPED, unauthenticated only, see 1.9
Read receipts from the daemonNeither Crux SDK covers thisCall GET /v1/receipts/{id} directly, or use SDKCrux @cuecrux/memory from source5Not in either Crux SDK
Ask the CueCrux Engine for an answerTypeScript / JavaScriptnpm install @cuecrux/engine-client5SHIPPED, typings broken, see 6.1
Verify a CueCrux Engine answer receipt from a terminalCLINot published. Build from SDKCrux source5Unpublished
Ergonomic remember() / recall() / forget() over the daemonTypeScript / JavaScriptNot published. Vendor from SDKCrux source5Unpublished prototype
Anything in Rust, Go, Java, C#-No SDK exists. Use the HTTP API-Not built

There is no Rust, Go, Java or C# client. The daemon publishes its own OpenAPI document at GET /v1/openapi.json, which is the supported route for a language we do not ship.

0.2 Install commands, and what the registry actually serves

Registry state was queried on 2026-07-27. Manifest version means the version in the repository today; published version means what npm install or pip install resolves to.

PackageRegistryManifest versionPublished versionFirst published
@cuecrux/clientnpm0.2.00.1.02026-06-12
corecrux-clientPyPI0.1.00.1.02026-06-12
@cuecrux/engine-clientnpm1.1.11.1.1-
@cuecrux/factorynpm (declared target)0.1.0not published-
@cuecrux/memorynpm (declared target)0.1.0not published-
cuecrux-receiptnpm (declared target)0.1.1not published-
@cuecrux/policy-clinpm (default, unintended)0.14.1not published-

Two consequences you need before you write any code.

@cuecrux/client is one minor version behind its repository. npm install @cuecrux/client gives you 0.1.0. The repository is at 0.2.0 (package.json:3), whose only change is three optional fields on VersionResponse.update (CHANGELOG.md:3). Every method and every other type documented in chapter 1 is present in the published 0.1.0. The publish job only fires on an sdk-typescript-v* tag (sdk-typescript.yml:58); no such tag exists in the repository, so 0.2.0 has not shipped. See 6.9.

Three of the four "public" SDKCrux packages have never been published. Their manifests declare publishConfig.registry: registry.npmjs.org and access: public, but no workflow publishes them, and the registry returns 404. @cuecrux/engine-client is the only SDKCrux package you can actually install. Chapter 5 documents the rest from source, because vendoring is the only way to use them.

0.3 Why there are two estates

The two SDK programmes were built for two different services and never reconciled.

Crux sdks/SDKCrux
RepositoryCueCrux/Crux, directory sdks/CueCrux/SDKCrux
Last change to SDK code9fbc8ab, 2026-07-22896cfc3, 2026-06-12
Target serviceCrux Daemon (corecruxd), HTTP on port 14800CueCrux Engine, a separate hosted service
Public packages@cuecrux/client (npm), corecrux-client (PyPI)@cuecrux/engine-client (npm) plus three unpublished
Release triggerGit tag sdk-python-v* / sdk-typescript-v*Manual workflow_dispatch
Registry credentialsNone. OIDC Trusted Publishing on both registriesNone for the public lane. OIDC Trusted Publishing
Reproducibility gatePython builds twice under SOURCE_DATE_EPOCH and diffs the sha256 sumsNone
Endorsed by the daemon docsYes, explicitlyNot mentioned anywhere

The canonical answer is the Crux sdks/ estate, on four grounds, all checkable:

  1. The daemon's own documentation says so. "The in-repo SDKs are the supported public SDK surface" (developer-portal.md:61).
  2. It is the only one still moving. 2026-07-22 against 2026-06-12.
  3. Its release path cannot publish by accident. Both workflows carry top-level permissions: contents: read, so a build run can never obtain registry write; only a version-matched sdk-*-v* tag starts a publish job with id-token: write (sdk-typescript.yml:16, sdk-python.yml:16).
  4. The Python lane proves its own artifact. It builds the distribution twice under a pinned SOURCE_DATE_EPOCH and fails the run if the sha256 sums differ (sdk-python.yml:43). See 2.10.

What the counter-claim says. SDKCrux's README states the repository "contains the entire CueCrux SDK surface" (README.md:7). Both statements cannot be true. That README predates @cuecrux/memory entirely and its package map omits nine of the packages in the repository. We are stating the resolution here because neither repository states it, and an integrator who picks wrong loses a day.

0.4 The two services are not interchangeable

The most expensive mistake available here is installing a client for the wrong service. They share a brand and nothing else.

Crux DaemonCueCrux Engine
What it isA single Rust binary you run yourselfA hosted answer/ingest service
Default address127.0.0.1:14800 (config.rs:801)https://engine.cuecrux.com
Primary nounsfacts, sessions, entities, segmentsanswers, corpora, artifacts, quality jobs
Error formatRFC 9457 Problem Details, application/problem+jsonJSON body, shape varies by route
AuthAuthorization: Bearer, plus scope headersX-API-Key or Authorization: Bearer
Client@cuecrux/client, corecrux-client@cuecrux/engine-client

If your code calls storeFact, queryFacts or textSearch, you want the daemon. If it calls answers, qualityBoost or provenance, you want the Engine. Nothing in either client will tell you that you pointed it at the wrong one; you will get connection refusals or 404s.

0.5 What none of these SDKs do

Stated here once so no chapter has to disclaim it twice.

CapabilityState
Automatic retry or backoffNot built in @cuecrux/client, corecrux-client or @cuecrux/memory. Only SDKCrux's FactoryClient retries. See chapter 4
Connection pooling control, proxies, custom TLSNot exposed. TypeScript uses global fetch; Python uses httpx defaults with a flat 30 s timeout
Reading a token from the environmentNot done by either Crux SDK. You pass the token explicitly. Only SDKCrux @cuecrux/memory reads env vars
Pagination helpers or async iteratorsNot built. exportFacts returns a cursor you advance yourself
Authenticated SSENot possible via subscribeEvents, native EventSource cannot send headers (index.ts:222)
A generated clientNeither Crux SDK is generated. Both are hand-written, despite what the portal doc implies, see 6.10
A stability guaranteeBoth Crux SDKs are 0.x. Policy is that a minor may break while below 1.0 (sdk-release-lifecycle.md:27); neither README says so

0.6 Chapter map

ChapterModeCovers
1. TypeScript SDKReference@cuecrux/client: every export, signature, type and thrown error
2. Python SDKReferencecorecrux-client: sync and async clients, dataclasses, the reproducibility gate
3. AuthenticationReferenceTokens, env vars, scopes, and what 401, 403 and 503 each mean
4. Errors and retriesReferenceThe error model, which conditions recover, and what must never be retried
5. SDKCrux packagesReferenceThe complete SDKCrux inventory with published status
6. Known issuesReferenceThe dated defect register, with evidence and consequence per defect

For the daemon's HTTP surface itself, routes, scopes, the extension model, see the Crux Daemon developer guide. This set documents the clients, not the server.

Sources