Skip to main content

Types & Interfaces Reference

Last Updated: January 9, 2026 SDK Version: 0.29.0 Source: src/types/index.ts

Overview​

Complete TypeScript type reference for the Cortex SDK. All type definitions are extracted directly from the SDK source code and represent the authoritative type definitions.

Import Types:

import type {
  // Core entities
  Conversation,
  Message,
  MemoryEntry,
  UserProfile,
  Session,
  RegisteredAgent,

  // Facts
  FactRecord,
  StoreFactParams,

  // Filters
  UniversalFilters,
  MemoryFilters,
  ConversationFilters,

  // Results
  RememberResult,
  SearchResult,
  RememberStreamResult,

  // Options
  RememberParams,
  SearchOptions,
  RecallParams,

  // And all other types...
} from "@cortexmemory/sdk";

Table of Contents​

Core Entities​

Orchestration Types​

Filter Types​

A2A Communication​

Governance & Policies​

Graph Integration​

Observer Pattern​

Resilience Types​

Enums & Literals​

Detailed Type Definitions​

Conversation​

Layer 1a: ACID Conversations

interface Conversation {
  _id: string;
  conversationId: string;
  memorySpaceId: string; // Memory space isolation
  tenantId?: string; // Multi-tenancy: SaaS platform isolation
  participantId?: string; // Hive Mode tracking
  type: ConversationType;
  participants: {
    userId?: string; // The human user in the conversation
    agentId?: string; // The agent/assistant in the conversation
    participantId?: string; // Hive Mode: who created this
    memorySpaceIds?: string[]; // Collaboration Mode (agent-agent)
  };
  messages: Message[];
  messageCount: number;
  metadata?: Record<string, unknown>;
  createdAt: number;
  updatedAt: number;
}

Used in:

Related types:

Message​

interface Message {
  id: string;
  role: "user" | "agent" | "system";
  content: string;
  timestamp: number;
  participantId?: string; // Hive Mode: which participant sent this
  metadata?: Record<string, unknown>;
}

Used in:

MemoryEntry​

Layer 2: Vector Memory

interface MemoryEntry {
  _id: string;
  memoryId: string;
  memorySpaceId: string;
  tenantId?: string; // Multi-tenancy: SaaS platform isolation
  participantId?: string; // Hive Mode
  userId?: string; // For user-owned memories
  agentId?: string; // For agent-owned memories
  content: string;
  contentType: ContentType;
  embedding?: number[];
  sourceType: SourceType;
  sourceUserId?: string;
  sourceUserName?: string;
  sourceTimestamp: number;
  messageRole?: "user" | "agent" | "system"; // For semantic search weighting
  conversationRef?: ConversationRef;
  immutableRef?: ImmutableRef;
  mutableRef?: MutableRef;
  factsRef?: FactsRef; // Reference to Layer 3 fact
  importance: number;
  tags: string[];

  // Enrichment fields (for bullet-proof retrieval)
  enrichedContent?: string; // Concatenated searchable content for embedding
  factCategory?: string; // Category for filtering (e.g., "addressing_preference")

  version: number;
  previousVersions: MemoryVersion[];
  createdAt: number;
  updatedAt: number;
  lastAccessed?: number;
  accessCount: number;
}

Used in:

Related types:

FactRecord​

Layer 3: Facts Store

interface FactRecord {
  _id: string;
  factId: string;
  memorySpaceId: string;
  tenantId?: string; // Multi-tenancy: SaaS platform isolation
  participantId?: string; // Hive Mode tracking
  userId?: string; // GDPR compliance - links to user
  fact: string; // The fact statement
  factType:
    | "preference"
    | "identity"
    | "knowledge"
    | "relationship"
    | "event"
    | "observation"
    | "custom";
  subject?: string; // Primary entity
  predicate?: string; // Relationship type
  object?: string; // Secondary entity
  confidence: number; // 0-100
  sourceType: "conversation" | "system" | "tool" | "manual" | "a2a";
  sourceRef?: {
    conversationId?: string;
    messageIds?: string[];
    memoryId?: string;
  };
  metadata?: Record<string, unknown>;
  tags: string[];

  // Enrichment fields (for bullet-proof retrieval)
  category?: string; // Specific sub-category (e.g., "addressing_preference")
  searchAliases?: string[]; // Alternative search terms
  semanticContext?: string; // Usage context sentence
  entities?: EnrichedEntity[]; // Extracted entities with types
  relations?: EnrichedRelation[]; // Subject-predicate-object triples for graph

  validFrom?: number;
  validUntil?: number;
  version: number;
  supersededBy?: string; // factId of newer version
  supersedes?: string; // factId of previous version
  createdAt: number;
  updatedAt: number;
}

Used in:

UserProfile​

interface UserProfile {
  id: string;
  tenantId?: string; // Multi-tenancy: SaaS platform isolation
  data: Record<string, unknown>;
  version: number;
  createdAt: number;
  updatedAt: number;
}

Used in:

ImmutableRecord​

Layer 1b: Immutable Store

interface ImmutableRecord {
  _id: string;
  type: string;
  id: string;
  data: Record<string, unknown>;
  tenantId?: string; // Multi-tenancy: SaaS platform isolation
  userId?: string;
  version: number;
  previousVersions: ImmutableVersion[];
  metadata?: {
    publishedBy?: string;
    tags?: string[];
    importance?: number;
    [key: string]: unknown;
  };
  createdAt: number;
  updatedAt: number;
}

Used in:

Related types:

MutableRecord​

Layer 1c: Mutable Store

interface MutableRecord {
  _id: string;
  namespace: string;
  key: string;
  value: unknown;
  tenantId?: string; // Multi-tenancy: SaaS platform isolation
  userId?: string;
  metadata?: Record<string, unknown>;
  createdAt: number;
  updatedAt: number;
}

Used in:

MemorySpace​

interface MemorySpace {
  _id: string;
  memorySpaceId: string;
  tenantId?: string; // Multi-tenancy: SaaS platform isolation
  name?: string;
  type: "personal" | "team" | "project" | "custom";
  participants: Array<{
    id: string;
    type: string;
    joinedAt: number;
  }>;
  metadata: Record<string, unknown>;
  status: "active" | "archived";
  createdAt: number;
  updatedAt: number;
}

Used in:

RegisteredAgent​

interface RegisteredAgent {
  id: string;
  tenantId?: string; // Multi-tenancy: SaaS platform isolation
  name: string;
  description?: string;
  metadata: Record<string, unknown>;
  config: Record<string, unknown>;
  status: "active" | "inactive" | "archived";
  registeredAt: number;
  updatedAt: number;
  lastActive?: number;
  stats?: AgentStats;
}

Used in:

Related types:

Session​

type SessionStatus = "active" | "idle" | "ended";

interface SessionMetadata {
  device?: string;
  browser?: string;
  browserVersion?: string;
  os?: string;
  deviceType?: "desktop" | "mobile" | "tablet" | string;
  ip?: string;
  location?: string;
  timezone?: string;
  language?: string;
  userAgent?: string;
  [key: string]: unknown;
}

interface Session {
  _id: string;
  sessionId: string;
  userId: string;
  tenantId?: string;
  memorySpaceId?: string;
  status: SessionStatus;
  startedAt: number;
  lastActiveAt: number;
  endedAt?: number;
  expiresAt?: number;
  metadata?: SessionMetadata;
  messageCount: number;
  memoryCount: number;
}

Used in:

Orchestration Types​

RememberParams​

Parameters for memory.remember() - the primary orchestration API

interface RememberParams {
  /**
   * Memory space for isolation. If not provided, defaults to 'default'
   * with a warning. Auto-registers the memory space if it doesn't exist.
   */
  memorySpaceId?: string;

  /**
   * Multi-tenancy: SaaS platform isolation.
   * When provided, all data is scoped to this tenant.
   * Note: If using authContext, tenantId is auto-injected unless explicitly provided here.
   */
  tenantId?: string;

  /**
   * Conversation ID. Required.
   */
  conversationId: string;

  /**
   * The user's message content. Required.
   */
  userMessage: string;

  /**
   * The agent's response content. Required.
   */
  agentResponse: string;

  /**
   * User ID for user-owned memories. At least one of userId or agentId is required.
   * Auto-creates user profile if it doesn't exist (unless 'users' is in skipLayers).
   */
  userId?: string;

  /**
   * Agent ID for agent-owned memories. At least one of userId or agentId is required.
   * Auto-registers agent if it doesn't exist (unless 'agents' is in skipLayers).
   */
  agentId?: string;

  /**
   * Display name for the user (used in conversation tracking).
   * Required when userId is provided.
   */
  userName?: string;

  /**
   * Participant ID for Hive Mode tracking.
   * This tracks WHO stored the memory within a shared memory space,
   * distinct from userId/agentId which indicates ownership.
   */
  participantId?: string;

  /**
   * Layers to explicitly skip during orchestration.
   * By default, all configured layers are enabled.
   */
  skipLayers?: SkippableLayer[];

  // Optional extraction
  extractContent?: (
    userMessage: string,
    agentResponse: string,
  ) => Promise<string | null>;

  // Optional embedding
  generateEmbedding?: (content: string) => Promise<number[] | null>;

  // Optional fact extraction
  extractFacts?: (
    userMessage: string,
    agentResponse: string,
  ) => Promise<Array<{
    fact: string;
    factType:
      | "preference"
      | "identity"
      | "knowledge"
      | "relationship"
      | "event"
      | "observation"
      | "custom";
    subject?: string;
    predicate?: string;
    object?: string;
    confidence: number;
    tags?: string[];
  }> | null>;

  // Cloud Mode options
  autoEmbed?: boolean;
  autoSummarize?: boolean;

  // Metadata
  importance?: number;
  tags?: string[];

  /**
   * Fact deduplication strategy. Defaults to 'semantic' for maximum effectiveness.
   *
   * - 'semantic': Embedding-based similarity (most accurate, requires generateEmbedding)
   * - 'structural': Subject + predicate + object match (fast, good accuracy)
   * - 'exact': Normalized text match (fastest, lowest accuracy)
   * - false: Disable deduplication (previous behavior)
   *
   * The generateEmbedding function (if provided) is automatically reused for semantic matching.
   *
   * @default 'semantic' (with fallback to 'structural' if no generateEmbedding)
   */
  factDeduplication?: "semantic" | "structural" | "exact" | false;

  /**
   * Observer for real-time orchestration monitoring.
   *
   * Provides callbacks for tracking layer-by-layer progress during
   * the remember() orchestration flow. Integration-agnostic.
   */
  observer?: OrchestrationObserver;
}

Used in:

Related types:

RememberResult​

interface RememberResult {
  conversation: {
    messageIds: string[];
    conversationId: string;
  };
  memories: MemoryEntry[];
  facts: FactRecord[];

  /**
   * Belief revision actions taken for each extracted fact (v0.24.0+)
   *
   * Only populated when belief revision is enabled (default when LLM configured).
   * Each entry describes what action was taken for a fact and why.
   */
  factRevisions?: Array<{
    /** Action taken: ADD (new), UPDATE (merged), SUPERSEDE (replaced), NONE (skipped) */
    action: "ADD" | "UPDATE" | "SUPERSEDE" | "NONE";
    /** The resulting fact (or existing fact for NONE) */
    fact: FactRecord;
    /** Facts that were superseded by this action */
    superseded?: FactRecord[];
    /** Reason for the action from LLM or heuristics */
    reason?: string;
  }>;
}

Used in:

Related types:

RecallParams​

Parameters for memory.recall() - unified context retrieval

interface RecallParams {
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  // REQUIRED - Just these two for basic usage
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  /** Memory space to search in */
  memorySpaceId: string;

  /** Natural language query */
  query: string;

  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  // OPTIONAL - All have sensible defaults for AI chatbot use cases
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  /** Pre-computed embedding for semantic search (recommended for best results) */
  embedding?: number[];

  /** Filter by user ID (common in H2A chatbots) */
  userId?: string;

  /** Filter by tenant ID for multi-tenancy (SaaS platform isolation) */
  tenantId?: string;

  /**
   * Source selection - ALL ENABLED BY DEFAULT.
   * Only specify to DISABLE sources.
   */
  sources?: {
    /** Search vector memories (Layer 2). Default: true */
    vector?: boolean;
    /** Search facts directly (Layer 3). Default: true */
    facts?: boolean;
    /** Query graph for relationships. Default: true if graph configured */
    graph?: boolean;
  };

  /**
   * Graph expansion configuration - ENABLED BY DEFAULT if graph configured.
   * Graph is the key to relational context discovery.
   */
  graphExpansion?: {
    /** Enable graph expansion. Default: true if graph configured */
    enabled?: boolean;
    /** Maximum traversal depth. Default: 2 */
    maxDepth?: number;
    /** Relationship types to follow. Default: all types */
    relationshipTypes?: string[];
    /** Expand from discovered facts. Default: true */
    expandFromFacts?: boolean;
    /** Expand from discovered memories. Default: true */
    expandFromMemories?: boolean;
  };

  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  // FILTERING (optional refinement)
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  /** Minimum importance score (0-100) */
  minImportance?: number;

  /** Minimum confidence for facts (0-100) */
  minConfidence?: number;

  /** Filter by tags */
  tags?: string[];

  /** Only include items created after this date */
  createdAfter?: Date;

  /** Only include items created before this date */
  createdBefore?: Date;

  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  // RESULT OPTIONS - OPTIMIZED FOR LLM INJECTION BY DEFAULT
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  /** Maximum number of results. Default: 20 */
  limit?: number;

  /** Enrich with ACID conversation data. Default: true */
  includeConversation?: boolean;

  /** Generate LLM-ready context string. Default: true */
  formatForLLM?: boolean;
}

Used in:

Related types:

RecallResult​

interface RecallResult {
  /** Unified results (merged, deduped, ranked) */
  items: RecallItem[];

  /** Breakdown by source */
  sources: RecallSourceBreakdown;

  /**
   * Formatted context for LLM injection.
   * Present when formatForLLM: true (default).
   */
  context?: string;

  /** Total number of results before limit */
  totalResults: number;

  /** Query execution time in milliseconds */
  queryTimeMs: number;

  /** Whether graph expansion was applied */
  graphExpansionApplied: boolean;
}

Related types:

  • RecallItem
  • RecallSourceBreakdown (inline type in RecallResult)

Observer Pattern Types​

OrchestrationObserver​

Integration-agnostic orchestration monitoring

interface OrchestrationObserver {
  /**
   * Called when orchestration starts
   */
  onOrchestrationStart?: (orchestrationId: string) => void | Promise<void>;

  /**
   * Called when a layer's status changes
   */
  onLayerUpdate?: (event: LayerEvent) => void | Promise<void>;

  /**
   * Called when orchestration completes (all layers done)
   */
  onOrchestrationComplete?: (
    summary: OrchestrationSummary,
  ) => void | Promise<void>;
}

Used in:

Related types:

LayerEvent​

type MemoryLayer =
  | "memorySpace"
  | "user"
  | "agent"
  | "conversation"
  | "vector"
  | "facts"
  | "graph";

type LayerStatus = "pending" | "in_progress" | "complete" | "error" | "skipped";

type RevisionAction = "ADD" | "UPDATE" | "SUPERSEDE" | "NONE";

interface LayerEvent {
  /** Which layer this event is for */
  layer: MemoryLayer;

  /** Current status of the layer */
  status: LayerStatus;

  /** Timestamp when this status was set */
  timestamp: number;

  /** Time elapsed since orchestration started (ms) */
  latencyMs?: number;

  /** Data stored in this layer (if complete) */
  data?: {
    /** ID of the stored record */
    id?: string;
    /** Summary or preview of the data */
    preview?: string;
    /** Additional metadata */
    metadata?: Record<string, unknown>;
  };

  /** Error details (if error status) */
  error?: {
    message: string;
    code?: string;
  };

  /**
   * Revision action taken (for facts layer with belief revision enabled)
   */
  revisionAction?: RevisionAction;

  /**
   * Facts that were superseded by this action
   * Only present when revisionAction is "SUPERSEDE"
   */
  supersededFacts?: string[];
}

Governance & Policy Types​

GovernancePolicy​

type ComplianceMode = "GDPR" | "HIPAA" | "SOC2" | "FINRA" | "Custom";

interface GovernancePolicy {
  organizationId?: string;
  memorySpaceId?: string;

  // Layer 1a: Conversations
  conversations: {
    retention: {
      deleteAfter: string; // '7y', '30d', etc.
      archiveAfter?: string;
      purgeOnUserRequest: boolean;
    };
    purging: {
      autoDelete: boolean;
      deleteInactiveAfter?: string;
    };
  };

  // Layer 1b: Immutable
  immutable: {
    retention: {
      defaultVersions: number;
      byType: Record<
        string,
        {
          versionsToKeep: number;
          deleteAfter?: string;
        }
      >;
    };
    purging: {
      autoCleanupVersions: boolean;
      purgeUnusedAfter?: string;
    };
  };

  // Layer 1c: Mutable
  mutable: {
    retention: {
      defaultTTL?: string;
      purgeInactiveAfter?: string;
    };
    purging: {
      autoDelete: boolean;
      deleteUnaccessedAfter?: string;
    };
  };

  // Layer 2: Vector
  vector: {
    retention: {
      defaultVersions: number;
      byImportance: Array<{
        range: [number, number];
        versions: number;
      }>;
      bySourceType?: Record<string, number>;
    };
    purging: {
      autoCleanupVersions: boolean;
      deleteOrphaned: boolean;
    };
  };

  // Sessions: Session lifecycle policies
  sessions?: SessionPolicy;

  // Cross-layer compliance
  compliance: {
    mode: ComplianceMode;
    dataRetentionYears: number;
    requireJustification: number[];
    auditLogging: boolean;
  };
}

Used in:

Related types:

SessionPolicy​

interface SessionLifecyclePolicy {
  /**
   * Idle timeout before session becomes idle/expires.
   * Format: duration string ('30m', '1h', '24h')
   * @default '30m'
   */
  idleTimeout: string;

  /**
   * Maximum session duration regardless of activity.
   * Format: duration string ('12h', '24h', '7d')
   * @default '24h'
   */
  maxDuration: string;

  /**
   * Automatically extend session on activity.
   * @default true
   */
  autoExtend: boolean;

  /**
   * Warn user before session expires.
   * Format: duration string ('5m', '15m')
   */
  warnBeforeExpiry?: string;
}

interface SessionCleanupPolicy {
  /**
   * Automatically expire idle sessions.
   * @default true
   */
  autoExpireIdle: boolean;

  /**
   * Delete ended sessions after this duration.
   * Format: duration string ('7d', '30d', '90d')
   */
  deleteEndedAfter?: string;

  /**
   * Archive sessions before deletion.
   * Format: duration string
   */
  archiveAfter?: string;
}

interface SessionLimitsPolicy {
  /**
   * Maximum concurrent active sessions per user.
   */
  maxActiveSessions?: number;

  /**
   * Maximum sessions per device type.
   */
  maxSessionsPerDevice?: number;
}

interface SessionPolicy {
  lifecycle: SessionLifecyclePolicy;
  cleanup: SessionCleanupPolicy;
  limits?: SessionLimitsPolicy;
}

Resilience Types​

Priority​

type Priority = "critical" | "high" | "normal" | "low" | "background";

Priority order (highest first):

  1. critical - GDPR/security operations (never dropped)
  2. high - Real-time conversation storage
  3. normal - Standard reads/writes
  4. low - Bulk operations, exports
  5. background - Async sync, analytics

CircuitState​

type CircuitState = "closed" | "open" | "half-open";

Used in:

ResilienceConfig​

interface ResilienceConfig {
  /** Enable/disable resilience layer - default: true */
  enabled?: boolean;

  /** Token bucket rate limiter settings */
  rateLimiter?: RateLimiterConfig;

  /** Semaphore concurrency limiter settings */
  concurrency?: ConcurrencyConfig;

  /** Circuit breaker settings */
  circuitBreaker?: CircuitBreakerConfig;

  /** Priority queue settings */
  queue?: QueueConfig;

  /** Retry settings for transient failures */
  retry?: RetryConfig;

  // Monitoring Hooks
  onCircuitOpen?: (failures: number) => void;
  onCircuitClose?: () => void;
  onCircuitHalfOpen?: () => void;
  onQueueFull?: (priority: Priority) => void;
  onThrottle?: (waitTimeMs: number) => void;
  onMetrics?: (metrics: ResilienceMetrics) => void;
  onRetry?: (attempt: number, error: Error, delayMs: number) => void;
}

Used in:

Enum & Literal Types​

ConversationType​

type ConversationType = "user-agent" | "agent-agent";

SourceType​

type SourceType = "conversation" | "system" | "tool" | "a2a" | "fact-extraction";

ContentType​

type ContentType = "raw" | "summarized" | "fact";

FactType​

type FactType =
  | "preference"
  | "identity"
  | "knowledge"
  | "relationship"
  | "event"
  | "observation"
  | "custom";

SkippableLayer​

type SkippableLayer =
  | "users"
  | "agents"
  | "conversations"
  | "vector"
  | "facts"
  | "graph";

Layers that can be explicitly skipped during remember() orchestration:

  • users - Don't auto-create user profile
  • agents - Don't auto-register agent
  • conversations - Don't store messages in ACID conversation layer
  • vector - Don't store in vector memory layer
  • facts - Don't auto-extract facts (even if LLM configured)
  • graph - Don't sync to graph database (even if configured)

DeduplicationStrategy​

type DeduplicationStrategy = "none" | "exact" | "structural" | "semantic";

Fact deduplication strategies:

  • none - Skip deduplication (fastest, no accuracy)
  • exact - Normalized text match (fast, low accuracy)
  • structural - Subject + predicate + object match (fast, medium accuracy)
  • semantic - Embedding similarity search (slower, highest accuracy)

Used in:

Type Index​

Quick alphabetical reference for all types (links to this page or external API docs):

A​

C​

D​

F​

G​

I​

L​

M​

O​

P​

R​

S​

U​

See Also​