JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 179
  • Score
    100M100P100Q94485F
  • License Apache-2.0

Cognitive infrastructure for AI agents. A persistent, portable cognitive layer that travels with your agents — provenance, confidence, and temporal awareness baked into every assertion.

Package Exports

  • @subcortex-ai/sdk

Readme

@subcortex-ai/sdk

TypeScript SDK for the SubCortex cognitive engine — persistent memory, identity, signals, and knowledge graph for AI agents.

Install

npm install @subcortex-ai/sdk

Quick Start

import { SubCortexClient } from '@subcortex-ai/sdk'

const subcortex = new SubCortexClient({
  endpoint: 'https://your-subcortex-instance.com',
  tenantId: 'your-tenant-id',
  apiKey: 'scx_live_...',
})

// Store a fact about a user
await subcortex.assertions.create({
  subject: 'user:alice',
  predicate: 'role',
  value: 'Engineering Manager',
  confidence: 0.99,
})

// Query everything known about a subject
const facts = await subcortex.assertions.query('user:alice')

// Identify a returning user — memories, reminders, conflicts, signals, all in one call
const user = await subcortex.users.identify({ userId: 'alice', displayName: 'Alice Smith' })

// Record an emotional signal
await subcortex.signals.record({
  userId: 'alice',
  type: 'frustration',
  content: 'Frustrated about the hiring timeline slipping',
  intensity: 0.8,
  resolveConflicting: false,
})

// Record a positive signal and automatically resolve prior negative ones on the same subject
await subcortex.signals.record({
  userId: 'alice',
  type: 'satisfaction',
  content: 'Excited — found a great candidate',
  intensity: 0.85,
  resolveConflicting: true,
})

// Check server health
const health = await subcortex.health()

API Reference

new SubCortexClient(options)

Option Type Required Default Description
endpoint string Yes Base URL of the SubCortex REST API
tenantId string Yes Tenant ID for all operations
apiKey string No* API key (scx_live_...)
token string No* JWT token (alternative to apiKey)
retry object No { maxRetries: 3, baseDelayMs: 500, maxDelayMs: 10000 } Retry config
timeoutMs number No 30000 Request timeout in ms
fetch typeof fetch No globalThis.fetch Custom fetch (for testing / Cloudflare Workers)
headers Record<string, string> No {} Custom headers added to every request

*At least one of apiKey or token should be provided for authenticated requests.

Assertions

subcortex.assertions.create({ subject, predicate, value, confidence? })
subcortex.assertions.get(assertionId)
subcortex.assertions.query(subject)
subcortex.assertions.list()
subcortex.assertions.supersede({ originalAssertionId, subject, predicate, value })
subcortex.assertions.retract(assertionId)

Relationships

subcortex.relationships.create({ fromSubject, toSubject, relationshipType, confidence? })
subcortex.relationships.query(subject)
subcortex.relationships.list()

Agents

subcortex.agents.create({ name, description, personality, instructions, model, capabilities, memoryPolicy })
subcortex.agents.get(agentId)
subcortex.agents.update(agentId, input)
subcortex.agents.delete(agentId)
subcortex.agents.list()
subcortex.agents.getInstructions(agentId)  // returns composed system prompt

Memory

// Routes through Thalamus pipeline (dedup, conflict detection) by default
subcortex.memory.store({ subject, predicate, value, agentId })

// Bypass Thalamus for bulk imports
subcortex.memory.store({ subject, predicate, value, raw: true })

subcortex.memory.recall(subject)
subcortex.memory.forget(assertionId)

Users

// Full user context in one call — memories, reminders, conflicts, signals, connected people
const user = await subcortex.users.identify({ userId, displayName?, agentId? })

// Register a person the user mentioned, with role and bidirectional relationships
await subcortex.users.registerPerson({ name, userId, relationship, role?, confidence? })

// Record a rapport signal about the user (legacy — prefer signals.record)
await subcortex.users.recordRapport({ userId, type, value, aboutPerson? })

// Dismiss a surfaced reminder
await subcortex.users.dismissReminder(userId, reminderContent)

Signals

// Record an emotional signal
await subcortex.signals.record({
  userId,
  type,          // 'frustration' | 'excitement' | 'concern' | 'satisfaction' | 'confusion' | 'gratitude' | 'tension' | 'sentiment'
  content,
  intensity?,    // 0–1, default 0.7
  aboutSubject?, // e.g. 'person:sarah-johnson', 'context:hiring'
  resolveConflicting?,  // true = auto-resolve prior negative signals on the same subject
})

// Query signals for a user with decay and trajectory
const snapshot = await subcortex.signals.query('user:alice', { windowHours: 72, type?: 'frustration' })
// snapshot.signals, snapshot.trajectory ('warming'|'cooling'|'stable'|'neutral'), snapshot.aggregateIntensity

// Manually resolve a signal
await subcortex.signals.resolve({ signalId, resolvedBySignalId })

Intake (Thalamus)

// Submit candidate assertions for pipeline processing
const result = await subcortex.intake.submit({ correlationId, agentId, candidates, context? })
// result.accepted, result.reinforced, result.conflicts, result.rejected, result.items

// Poll for pending results (conflicts, clarification requests)
const pending = await subcortex.intake.pending(agentId, { status?, limit? })

subcortex.intake.acknowledge(itemId)
subcortex.intake.acknowledgeAll(agentId)
subcortex.intake.stats(agentId)

Schema Helpers

import {
  SubjectPrefix, subject,
  ConfidenceLevel, ConfidenceScores, confidenceToScore, scoreToConfidence,
  Predicates, OrgRelationship, EntityRelationship,
  POSITIVE_SIGNALS, NEGATIVE_SIGNALS,
  SYSTEM_SIGNAL_TYPES,
} from '@subcortex-ai/sdk'

// Build subject strings
subject(SubjectPrefix.USER, 'alice')      // → 'user:alice'
subject(SubjectPrefix.PERSON, 'Sarah Johnson')  // → 'person:sarah-johnson'

// Confidence levels
confidenceToScore(ConfidenceLevel.CONFIRMED)  // → 0.99
confidenceToScore('high')                     // → 0.85
scoreToConfidence(0.72)                       // → ConfidenceLevel.MODERATE

Context Formatting

import { toContextXml } from '@subcortex-ai/sdk'

const user = await subcortex.users.identify({ userId })
const xml = toContextXml(user)  // Inject into LLM system prompt

Error Handling

import {
  SubCortexNotFoundError,
  SubCortexValidationError,
  SubCortexConflictError,
  SubCortexRateLimitError,
  SubCortexServerError,
  SubCortexNetworkError,
  SubCortexTimeoutError,
} from '@subcortex-ai/sdk'

try {
  await subcortex.assertions.get('nonexistent-id')
} catch (error) {
  if (error instanceof SubCortexNotFoundError) {
    console.log('Not found')
  } else if (error instanceof SubCortexRateLimitError) {
    console.log(`Rate limited — retry after ${error.retryAfter}s`)
  } else if (error instanceof SubCortexNetworkError) {
    console.log('SubCortex unreachable')
  }
}

All errors extend SubCortexError with:

  • statusCode — HTTP status (0 for network/timeout errors)
  • requestId — server-assigned ID for debugging
  • retryable — whether the SDK will retry automatically

Retry & Timeout

Requests automatically retry on 5xx errors and network failures with exponential backoff + jitter. 429 respects the Retry-After header. 4xx errors are never retried.

const subcortex = new SubCortexClient({
  endpoint: 'https://api.subcortex.example.com',
  tenantId: 'my-tenant',
  apiKey: 'scx_live_...',
  retry: { maxRetries: 5, baseDelayMs: 1000, maxDelayMs: 30000 },
  timeoutMs: 60000,
})

What is SubCortex?

SubCortex is a purpose-built cognitive engine for AI agents — persistent memory, identity, emotional signals, and knowledge graph in one system.

Concept Description
Assertion An atomic fact: subject + predicate + value, with confidence and temporal bounds
Relationship A directional edge between two subjects
Signal An emotional/rapport data point that decays over time and has a trajectory
Thalamus The intake pipeline — classifies, deduplicates, and detects contradictions
Agent A named AI identity with composable instructions, capabilities, and memory policy

License

Apache-2.0