TypeScript SDK

The TypeScript SDK is a REST client for contextdb, located in sdk/typescript/.

Installation

npm install contextdb

Connection

import { ContextDB } from "contextdb";

const db = new ContextDB("http://localhost:7701");

Namespace

const ns = db.namespace("my-app", "general");

The mode parameter accepts: general, belief_system, agent_memory, procedural.

Write

const result = await ns.write({
  content: "Go 1.22 added routing patterns to net/http",
  sourceId: "docs-crawler",
  labels: ["Claim"],
  properties: { url: "https://go.dev/blog" },
  confidence: 0.9,
});

console.log(result.nodeId);     // UUID string
console.log(result.admitted);   // true/false
console.log(result.reason);     // rejection reason if not admitted
console.log(result.conflictIds); // contradicting node IDs

WriteRequest fields

Field	Type	Required	Description
content	string	Yes	Text content
sourceId	string	Yes	External source identifier
labels	string[]	No	Node labels
properties	Record<string, unknown>	No	Arbitrary metadata
vector	number[]	No	Pre-computed embedding
modelId	string	No	Embedding model identifier
confidence	number	No	Confidence [0, 1]

WriteResult fields

Field	Type	Description
nodeId	string	UUID of the written node
admitted	boolean	Whether the write was accepted
reason	string	Rejection reason (empty if admitted)
conflictIds	string[]	UUIDs of contradicting nodes

Retrieve

// Vector-based query
const results = await ns.retrieve({ vector: [0.1, 0.2, 0.3], topK: 5 });

// Text-based query (lexical; also vector search if an embedder is configured)
const results = await ns.retrieve({ text: "What changed in Go 1.22?", topK: 5, candidateK: 40, rerankK: 12 });

// With label filtering
const results = await ns.retrieve({
  text: "routing patterns",
  labels: ["Claim"],
  topK: 10,
});

// With custom score weights
const results = await ns.retrieve({
  text: "routing patterns",
  topK: 5,
  scoreParams: {
    similarityWeight: 0.6,
    confidenceWeight: 0.2,
    recencyWeight: 0.1,
    utilityWeight: 0.1,
  },
});

for (const r of results) {
  console.log(`${r.score.toFixed(2)} ${r.node.properties.text}`);
}

// Retract one source's support without removing other corroboration.
await ns.retractSourceAssertion("<node-uuid>", "ledger", "corrected");

RetrieveRequest fields

Field	Type	Required	Description
vector	number[]	For vector search	Query embedding
text	string	For text search	Lexical search; also auto-embedded when configured
seedIds	string[]	For graph walk	Known relevant node IDs
topK	number	No	Max results (default: 10)
candidateK	number	No	Per-path candidate budget before fusion
rerankK	number	No	Number of fused candidates sent to an optional reranker
labels	string[]	No	Filter to nodes with all specified labels
scoreParams	ScoreParams	No	Override scoring weights

Result fields

Field	Type	Description
node	Node	Full node with labels, properties, metadata
score	number	Composite score [0, 1]
similarityScore	number	Vector similarity component
confidenceScore	number	Confidence component
recencyScore	number	Recency component
utilityScore	number	Utility component
retrievalSource	string	"vector", "graph", or "fused"

Ingest text

const result = await ns.ingestText(
  "Alice knows Go and Python. Bob specializes in Rust.",
  "docs-crawler",
);

console.log(result.nodesWritten); // 4
console.log(result.edgesWritten); // 3
console.log(result.rejected);     // 0

Label source

await ns.labelSource("user:spammer", ["troll"]);
await ns.labelSource("moderator:alice", ["moderator"]);

Acquisition execution

const preview = await ns.acquisitionExecution({
  budget: 2,
  maxResults: 3,
  maxAttempts: 2,
  allowedSourceIds: ["docs/runbook"],
  connectors: [{
    id: "docs-search",
    type: "search",
    endpoint: "https://search.example.internal/contextdb",
    allowedSourceIds: ["docs/runbook"],
    defaultLabels: ["acquired"],
  }],
});

console.log(preview.dry_run); // true

Set execute: true only after reviewing the dry-run connector calls. Execution writes returned connector items through the normal contextdb write path after source allow-list filtering. maxAttempts opts into retrying transient connector failures. Use acquisitionExecutionReceipts, acquisitionRetryCandidates, and acquisitionRetryRecommendations to inspect append-only attempt receipts and retry guidance.

Health check

await db.ping();   // { status: "ok" }
await db.stats();  // server statistics object