ContextDB server-only chat example

A complete TypeScript web chat showing the ContextDB Cloud memory loop without putting a project key in browser code. The browser talks only to a small Node server. The server uses native fetch against https://api.contextdb.ai.

The example demonstrates:

• recalling customer history when a chat session starts;
• preserving structured user and agent turns;
• calling POST /v1/extract_memories with mode: "commit" after each exchange;
• calling POST /v1/recall_for_action before a simulated booking;
• asking for confirmation when no action-safe memory is returned;
• calling POST /v1/confirm only after an explicit yes, then checking the action gate again;
• preserving named non-2xx FormationResponse terminals such as provider_error together with their HTTP status;
• running without credentials in deterministic demo mode.

Architecture

flowchart LR
    B["Browser\nstatic HTML/CSS/JS"] -->|"same-origin /api/* only"| N["Node TypeScript server"]
    N -->|"Bearer cdb_…\nnative fetch"| C["ContextDB Cloud\napi.contextdb.ai"]
    N -.->|"optional native fetch"| O["OpenAI"]
    E[".env / secret store"] -->|"server process only"| N
    C --> R["recall → extract/commit\n→ recall_for_action → confirm"]

Loading

The ContextDB project key is read from the server environment, kept in a private field, and used only to construct the server-to-server Authorization header. Static assets contain no ContextDB URL, key, or authorization logic. A strict Content Security Policy limits browser connections to the same origin.

Run the credential-free demo

Requirements: Node.js 20.10 or newer.

cp .env.example .env
npm install
npm run dev

Open http://127.0.0.1:3000, start the default customer session, then:

1. Send Book me Thursday afternoon.
2. Choose Try booking action.
3. Choose Yes, use it when the server asks for confirmation.

Demo mode keeps memory in the Node process and uses a deterministic responder. It intentionally keeps booking details untrusted until the confirmation route receives answer: "yes".

Use ContextDB Cloud

Copy the environment template and edit .env:

DEMO_MODE=false
CONTEXTDB_PROJECT_KEY=cdb_your_server_only_project_key
CONTEXTDB_BASE_URL=https://api.contextdb.ai

Then run:

npm install
npm run dev

Do not rename the project key to a browser-exposed variable such as NEXT_PUBLIC_* or VITE_*. In a real application, derive userId from your authenticated server session rather than accepting an arbitrary customer ID.

Optional OpenAI responses

The default responder is deterministic. To use OpenAI for chat wording, set:

OPENAI_API_KEY=your_server_only_openai_key
OPENAI_MODEL=gpt-4o-mini

Memory behavior and the verify-before-act gate do not depend on OpenAI. If the optional model call fails, chat falls back to the deterministic response.

Request flow

1. POST /api/session calls ContextDB POST /v1/recall.
2. POST /api/chat stores the exact user turn and generated agent turn in the server session, then sends that pair to POST /v1/extract_memories with mode: "commit".
3. POST /api/actions/book calls POST /v1/recall_for_action.
4. If the trusted list is empty, the server uses ordinary recall to locate the pending action-relevant memory and asks the browser for an explicit yes.
5. POST /api/actions/confirm accepts only answer: "yes", calls ContextDB POST /v1/confirm, calls recall_for_action again, and simulates the booking only if the confirmed memory now passes the active policy.

extract_memories is different from ordinary API errors. ContextDB can return a well-formed terminal body with HTTP 502, 503, or 504. The client resolves that body as a FormationResult and retains both status and httpStatus; it throws only when the response is not a named formation terminal (for example, a 401 authentication error or malformed response).

Browser-facing routes

• POST /api/session
• POST /api/chat
• POST /api/actions/book
• POST /api/actions/confirm
• GET /api/health

These routes are the only network surface used by public/app.js.

Verify

npm test
npm run typecheck
npm run build

The Vitest suite mocks native fetch for recall, extraction/commit, recall-for-action, confirmation, protocol errors, and named non-2xx formation terminals. It also serves the browser assets with a sentinel project key and asserts that the key never appears in any browser-visible asset or response.

Run the compiled server

npm run build
npm start

Docker

docker build -t contextdb-chat .
docker run --rm -p 3000:3000 --env-file .env contextdb-chat

The container defaults to DEMO_MODE=true; values in --env-file override it.

Example scope

The booking is deliberately simulated: it returns a generated bookingId but does not call a real booking provider. Server sessions and pending confirmations are bounded, in-memory examples with expiry. Replace them with authenticated, durable application state before deploying multiple server instances.

ContextDB Cloud is currently alpha. Confirmation records an attestation; it does not prove objective truth.

License

Apache-2.0. See LICENSE.