Identity Engine SDK

Initialize → Record → Check drift

Two structures: immutable core and mutable state

The SDK defines two interfaces from src/identity.ts. Fields listed below are the exact source fields — nothing is invented.

Append-only history of every meaningful event

Every SDK operation that changes state or runs a drift check returns a JournalEntry with four fields: seq (entry sequence number, equal to the current version), timestamp (ISO 8601), type (one of four event types below), and payload (structured data specific to the event type). Journal entries are not stored automatically — the caller appends them via store.appendJournal(id, entry).

import { createIdentity, updateState, FileIdentityStore } from '@certaworks/identity-engine-sdk';

const store = new FileIdentityStore('./.identity-store');

// Create identity
let identity = createIdentity('ResearchAgent', 'Summarize academic papers on AI safety');

// Persist initial state
await store.save(identity);

// Update mutable state and record the journal entry
const { identity: next, entry } = updateState(identity, {
  currentTask: 'paper-review-2026-05',
  lastRunAt: new Date().toISOString(),
});

// Save updated state and append the journal entry
await store.save(next);
await store.appendJournal(next.core.id, entry);
// entry.type === 'state_updated'
// entry.payload === { patch: { currentTask, lastRunAt }, previousVersion: 1 }

Deterministic lexical alignment — no LLM required

Drift detection compares the agent's purpose string against a caller-supplied description of recent behavior. Both strings are tokenized by lowercasing, stripping punctuation, splitting on whitespace, removing tokens shorter than 3 characters, and removing a fixed stopword list. The alignment score is the number of shared tokens divided by the number of reference (purpose) tokens. The drift score is 1 minus that alignment score. No vector embeddings, no cosine similarity, and no external model call are made — the check is fully deterministic and offline.

import { checkDrift, FileIdentityStore } from '@certaworks/identity-engine-sdk';

const store = new FileIdentityStore('./.identity-store');
const identity = await store.load('<agent-uuid>');

const recentBehavior = 'Generated marketing copy for a product launch campaign';

const { result, entry } = checkDrift(identity, recentBehavior, 0.4);
// result.aligned       → false (marketing/product/launch don't overlap well with "AI safety papers")
// result.alignmentScore → e.g. 0.10
// result.driftScore     → e.g. 0.90
// result.detail         → "DRIFT DETECTED — score 90% exceeds threshold 40%"

// Record the drift check in the journal
await store.appendJournal(identity.core.id, entry);

Exported functions and class

All public exports are defined in src/identity.ts and re-exported from src/index.ts. Names below are exact — no aliases or undocumented exports exist in the current build.

File-backed local store, one directory per agent

FileIdentityStore takes a directory path in its constructor. For each identity, it writes two files: a JSON state file at <dir>/<uuid>.json (the full IdentityState object, pretty-printed) and an append-only journal at <dir>/<uuid>.journal.jsonl (one JSON object per line). The directory is created automatically on first save or append if it does not exist.

There is no in-memory-only mode in this version — FileIdentityStore always reads and writes disk files. The SDK does not currently ship an in-memory or database-backed store adapter, but the constructor pattern is easy to extend by implementing the same save / load / appendJournal / readJournal interface.

{
  "core": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "ResearchAgent",
    "purpose": "Summarize academic papers on AI safety",
    "createdAt": "2026-05-19T10:00:00.000Z",
    "fingerprint": "a3f1c2d4e5b6a7c8"
  },
  "mutableState": {
    "currentTask": "paper-review-2026-05"
  },
  "version": 2,
  "updatedAt": "2026-05-19T10:05:00.000Z"
}

Stronger together

Identity Engine pairs naturally with the CertaWorks products that extend memory and session-level monitoring — together they form the agent continuity layer.