@verifiedstate/sdk

TypeScript SDK for the VerifiedState verified memory API.

Install

npm install @verifiedstate/sdk

Quick Start

import { VerifiedStateClient } from '@verifiedstate/sdk';

const client = new VerifiedStateClient({
  apiKey: 'vs_live_...',
  baseUrl: 'https://api.verifiedstate.ai', // optional, this is the default
});

// Store content
const artifact = await client.ingest({
  namespace_id: 'your-namespace-uuid',
  content: 'The user prefers dark mode and uses PostgreSQL.',
  source_type: 'user_input',
});

// Extract assertions
const extracted = await client.extract({
  namespace_id: 'your-namespace-uuid',
  artifact_id: artifact.artifact_id,
});

// Verify an assertion
const receipt = await client.verify({
  assertion_id: extracted.assertion_ids[0],
  namespace_id: 'your-namespace-uuid',
});

// Query memory
const results = await client.query({
  namespace_id: 'your-namespace-uuid',
  query_text: 'What database does the user prefer?',
});

API Methods

ingest(params)

Store raw content and create an artifact with spans.

const result = await client.ingest({
  namespace_id: 'uuid',
  content: 'Raw text content to store',
  source_type: 'user_input', // or 'document', 'api', etc.
  source_id: 'optional-external-id',
});
// => { artifact_id, span_count, r2_stored }

extract(params)

Extract structured assertions from an artifact using LLM.

const result = await client.extract({
  namespace_id: 'uuid',
  artifact_id: 'artifact-uuid',
});
// => { assertions_created, assertion_ids }

verify(params)

Run the verification ladder and produce a signed receipt.

const result = await client.verify({
  assertion_id: 'assertion-uuid',
  namespace_id: 'uuid',
});
// => { receipt_id, status, final_confidence, conflicts_found }

query(params)

Multi-channel retrieval with intent-aware routing.

const result = await client.query({
  namespace_id: 'uuid',
  query_text: 'What is the user's preferred language?',
  mode: 'current',    // 'current' | 'point_in_time' | 'trusted'
  limit: 10,
  filters: { valid_only: true },
});
// => { assertions, receipts, total, answerable, channels_used }

Structured queries:

const result = await client.query({
  namespace_id: 'uuid',
  query: { subject: 'user:42', predicate: 'prefers' },
});

receipt(receiptId)

Retrieve a verification receipt by ID.

const detail = await client.receipt('receipt-uuid');
// => { receipt, assertion, evidence_spans }

chain(writerPrincipal)

Get the Merkle chain for a writer.

const chain = await client.chain('agent:billing');
// => { writer_principal, current_hash, assertion_count, recent_assertions }

compress(params)

Compress an artifact to IR1 format.

const result = await client.compress({
  namespace_id: 'uuid',
  artifact_id: 'artifact-uuid',
});
// => { encoded_artifact_id, compression_ratio }

decompress(params)

Decompress an encoded artifact.

const result = await client.decompress({
  namespace_id: 'uuid',
  encoded_artifact_id: 'encoded-uuid',
});
// => { content, verified }

challenge(params)

Challenge an assertion with counter-evidence.

const result = await client.challenge({
  assertion_id: 'assertion-uuid',
  namespace_id: 'uuid',
  reason: 'Contradicted by updated policy',
  counter_evidence: 'Policy v2 states...',
});
// => { challenge_id, status }

retract(params)

Retract an assertion.

const result = await client.retract({
  assertion_id: 'assertion-uuid',
  namespace_id: 'uuid',
  reason: 'Information no longer valid',
});
// => { retraction_id, status }

health(namespaceId)

Get memory health metrics.

const health = await client.health('namespace-uuid');
// => { namespace_id, total_assertions, verified_count, disputed_count, coverage_score }

Proof Meter

Billing attestation for AI agents. Every transaction signed, chained, and independently verifiable.

// Create a spend authorization
const cap = await client.meter.authorize({
  namespace_id: 'your-namespace-uuid',
  authorizedAgentId: 'agent-alpha',
  maxBudgetCents: 1000,
  scope: { allowedProviders: ['openai', 'anthropic'] },
});

// Submit a spend receipt
const receipt = await client.meter.spend({
  namespace_id: 'your-namespace-uuid',
  capabilityId: cap.capability_id,
  actorId: 'agent-alpha',
  providerId: 'openai',
  usageUnit: 'tokens',
  usageQuantity: 1500,
  costCents: 45,
  occurredAt: new Date().toISOString(),
});
// => { receipt_id, receipt_hash, signature, status: 'verified' }

// Check remaining budget
const budget = await client.meter.budget(cap.capability_id);
// => { spent_cents, remaining_cents, receipt_count, children }

// Verify a receipt (cryptographic integrity check)
const check = await client.meter.verify(receipt.receipt_id);
// => { verified: true, checks: { hash_integrity, signature_valid, chain_continuity, merkle_inclusion } }

// Settle receipts into a Merkle root
const settlement = await client.meter.settle({
  namespace_id: 'your-namespace-uuid',
  capabilityId: cap.capability_id,
});
// => { settlement_id, merkle_root, total_cost_cents, receipt_count }

Real-Time Subscriptions

Subscribe once. Get instant answers.

// Subscribe to your namespace
await client.subscribe(namespaceId);

// Four-tier retrieval — automatically takes the fastest path
const fact = await client.quickQuery(namespaceId, 'user|prefers.drink|morning');

Retrieval speed:

• Existence check: 0.01ms (local filter, no network)
• Cached facts: <1ms (live in memory via real-time stream)
• Direct queries: <5ms (pre-computed state)
• Complex queries: <100ms (full retrieval)

Before VerifiedState: 80ms per query, every time. After VerifiedState: 0.01ms to know if a fact exists, <1ms to retrieve it.

New Methods

• subscribe(namespaceId) — load filter + cache + start receiving state
• unsubscribe() — clean up subscription and clear cache
• refreshFilter(namespaceId) — refresh existence filter (call every ~5 min for long-running agents)
• quickQuery(namespaceId, slotKey) — four-tier retrieval with automatic fastest path
• resync(namespaceId) — catch up on missed deltas

Error Handling

import { VerifiedStateError } from '@verifiedstate/sdk';

try {
  await client.query({ namespace_id: 'uuid', query_text: '...' });
} catch (err) {
  if (err instanceof VerifiedStateError) {
    console.error(err.status, err.message, err.body);
  }
}

License

MIT