Skip to main content

API Enhancements

Planned Features

These API enhancements are planned for future releases. All current APIs are fully functional—these enhancements focus on improving developer experience, safety, and flexibility.

Bulk Operations Safety​

Enhanced safety controls for bulk operations to prevent accidental data loss.

Dry Run Mode​

Preview operations without executing them.

Memory Operations:

// Preview deletion
const result = await cortex.memory.deleteMany(spaceId, {
  filters: { "metadata.importance": { $lt: 20 } },
  dryRun: true,
});

console.log(`Would delete ${result.wouldDelete} memories`);
// Decide whether to proceed

if (result.wouldDelete < 100) {
  await cortex.memory.deleteMany(spaceId, {
    filters: { "metadata.importance": { $lt: 20 } },
  });
}

Context Operations:

// Preview updates
const result = await cortex.contexts.updateMany(spaceId, {
  filters: { status: "blocked" },
  updates: { status: "cancelled" },
  dryRun: true,
});

console.log(`Would update ${result.wouldUpdate} contexts`);

Confirmation Thresholds​

Require explicit confirmation for large bulk operations.

// Automatic confirmation if below threshold
await cortex.memory.deleteMany(spaceId, {
  filters: { accessCount: 0 },
  confirmationThreshold: 10, // Auto-confirm if ≤ 10 records
  requireConfirmation: true,  // Prompt if > 10 records
});

// If > 10 records:
// Error: Confirmation required (47 records would be deleted)
// Use { confirmed: true } to proceed

await cortex.memory.deleteMany(spaceId, {
  filters: { accessCount: 0 },
  confirmed: true, // Explicit confirmation
});

Cascade Deletion Tracking​

Track descendants deleted in cascade operations.

const result = await cortex.contexts.deleteMany(spaceId, {
  filters: { status: "cancelled" },
});

console.log(result.deleted);            // 5 (direct matches)
console.log(result.descendantsDeleted); // 12 (children/grandchildren)

Advanced Filtering​

Enhanced filtering capabilities for queries and bulk operations.

Text Search Filters​

Search by text content in string fields.

Context Operations:

// Search by purpose
const contexts = await cortex.contexts.list(spaceId, {
  filters: {
    purposeContains: "user authentication", // Text search
  },
});

Nested Data Queries​

Filter by nested object fields in data or metadata.

Memory Operations:

// Query nested metadata
const memories = await cortex.memory.list({
  memorySpaceId: spaceId,
  filters: {
    "metadata.tags": "urgent",              // Array contains
    "metadata.priority": { $gte: 8 },       // Comparison
    "data.user.tier": "premium",            // Nested object
  },
});

User Operations:

// Query nested profile data
const users = await cortex.users.list({
  filters: {
    "preferences.theme": "dark",            // Nested preference
    "metadata.tier": "enterprise",          // Metadata field
  },
});

Range Query Operators​

Use comparison operators for numeric and date fields.

Supported Operators:

  • $gte - Greater than or equal
  • $lte - Less than or equal
  • $gt - Greater than
  • $lt - Less than
  • $eq - Equal
  • $ne - Not equal

Examples:

// Numeric range
const memories = await cortex.memory.list({
  memorySpaceId: spaceId,
  filters: {
    "metadata.importance": { $gte: 70, $lte: 90 },
    accessCount: { $gt: 10 },
  },
});

// Date range
const contexts = await cortex.contexts.list(spaceId, {
  filters: {
    createdAfter: new Date("2026-01-01"),
    createdBefore: new Date("2026-12-31"),
    completedAfter: new Date("2026-06-01"),
  },
});

Conversation Reference Filters​

Filter by linked ACID conversation properties.

const contexts = await cortex.contexts.list(spaceId, {
  filters: {
    "conversationRef.conversationId": "conv-123",
  },
});

Version Filtering​

Filter by version numbers (for versioned entities).

const contexts = await cortex.contexts.list(spaceId, {
  filters: {
    version: { $gte: 5 }, // Version 5 or higher
  },
});

Facts Confidence Range Queries​

Filter facts by confidence ranges.

// Current: Only lower bound
const facts = await cortex.facts.list({
  memorySpaceId: spaceId,
  minConfidence: 0.8, // confidence >= 0.8
});

// Planned: Full range queries
const facts = await cortex.facts.list({
  memorySpaceId: spaceId,
  filters: {
    confidence: { $gte: 0.7, $lte: 0.9 }, // 0.7 ≤ confidence ≤ 0.9
  },
});

Enhanced Export Capabilities​

More powerful export options for data portability.

Direct File Writing​

Write exports directly to file paths.

// Current: Returns data as string
const data = await cortex.memory.export(spaceId);
await fs.writeFile("memories.json", data);

// Planned: Direct file writing
await cortex.memory.export(spaceId, {
  outputPath: "./backups/memories-2026-01.json",
});

Include Version History​

Export with full version history.

await cortex.memory.export(spaceId, {
  outputPath: "./backups/memories-full.json",
  includeVersionHistory: true, // Include previousVersions array
});

Include Linked Conversations​

Export with linked ACID conversation data.

await cortex.contexts.export(spaceId, {
  outputPath: "./backups/contexts.json",
  includeConversations: true, // Include linked conversation messages
});

await cortex.memory.export(spaceId, {
  outputPath: "./backups/memories.json",
  includeConversationContext: true, // Include ACID source conversations
});

Selective Message Export​

Filter messages in conversation exports.

// Current: Includes all messages
const data = await cortex.conversations.export(spaceId, conversationId);

// Planned: Filter messages
await cortex.conversations.export(spaceId, conversationId, {
  outputPath: "./backups/conversation.json",
  includeFullMessages: false, // Only include message metadata
  messageFilters: {
    role: "assistant", // Only assistant messages
  },
});

Multi-Tenancy Filters​

Filter by tenant ID in multi-tenant deployments.

// Count memories by tenant
const count = await cortex.memory.count({
  memorySpaceId: spaceId,
  tenantId: "tenant-123", // Multi-tenancy filter
});

// List memories by tenant
const memories = await cortex.memory.list({
  memorySpaceId: spaceId,
  tenantId: "tenant-123",
});

Note: Currently, tenantId and participantId parameters are defined in TypeScript types but not yet passed to the backend.

Sessions API Enhancements​

Improved session management capabilities.

Date Range Filters​

Filter sessions by start date.

const sessions = await cortex.sessions.list(spaceId, {
  startedAfter: new Date("2026-01-01"),
  startedBefore: new Date("2026-01-31"),
});

Dry Run for Expiration​

Preview idle session expiration.

const result = await cortex.sessions.expireIdle(spaceId, {
  idleTimeoutMs: 30 * 60 * 1000, // 30 minutes
  dryRun: true,
});

console.log(`Would expire ${result.expired.length} sessions`);

Session-Specific Error Codes​

Dedicated error codes for session operations.

try {
  await cortex.sessions.get(spaceId, sessionId);
} catch (error) {
  if (error.code === CortexErrorCode.SESSION_NOT_FOUND) {
    // Session doesn't exist
  } else if (error.code === CortexErrorCode.SESSION_EXPIRED) {
    // Session expired
  } else if (error.code === CortexErrorCode.SESSION_ALREADY_ENDED) {
    // Session already ended
  }
}

User Operations Enhancements​

Advanced user profile management features.

Profile Validation Configuration​

Configure profile validation rules.

const cortex = new Cortex({
  convexUrl: process.env.CONVEX_URL!,
  userProfileValidation: {
    requiredFields: ["displayName", "email"],
    maxDisplayNameLength: 100,
    emailRequired: true,
    validateEmail: true,
  },
});

// Validation enforced on create/update
await cortex.users.create({
  id: "user-123",
  displayName: "Alice",
  // Error: email is required
});

Version Retention Configuration​

Control how many profile versions to keep.

const cortex = new Cortex({
  convexUrl: process.env.CONVEX_URL!,
  userProfileVersionRetention: 10, // Keep last 10 versions only
});

Skip Versioning Option​

Skip version creation for routine updates.

// Routine update (no version created)
await cortex.users.update("user-123", {
  displayName: "Alice Smith",
  skipVersioning: true,
});

Agent Management Enhancements​

Sorting Implementation​

Sort agent lists by various fields.

// Currently: Returns agents in database order
const agents = await cortex.agents.list();

// Planned: Sorting support
const agents = await cortex.agents.list({
  sortBy: "totalMemories",  // Sort by memory count
  sortOrder: "desc",        // Descending order
});

Analytics for Unregistered Agents​

Get statistics for unregistered agents.

// Planned: Analytics for any agent ID
const stats = await cortex.analytics.getAgentStats("unregistered-agent-456");

console.log(stats.totalMemories);
console.log(stats.totalConversations);

Workarounds (Current Implementation)​

Until these features are available, use these patterns:

Manual Dry Run​

// Count before deleting
const count = await cortex.memory.count({
  memorySpaceId: spaceId,
  filters: { accessCount: 0 },
});

console.log(`Will delete ${count} memories`);

if (count < 100) {
  await cortex.memory.deleteMany(spaceId, {
    filters: { accessCount: 0 },
  });
}

Manual Nested Filtering​

// Client-side filtering for nested fields
const allMemories = await cortex.memory.list({ memorySpaceId: spaceId });
const filtered = allMemories.filter(m => m.metadata.tags?.includes("urgent"));

Manual Export to File​

const data = await cortex.memory.export(spaceId);
await fs.writeFile("./backups/memories.json", data, "utf-8");