Governance Policies API

Info

Last Updated: 2026-01-08

Complete API reference for configuring retention, purging, and governance rules across all Cortex layers.

Overview

The Governance Policies API provides centralized control over data retention, purging, and compliance rules across all Cortex storage layers.

Governs:

Layer 1a (Conversations) - Private conversation retention
Layer 1b (Immutable) - Shared immutable data versioning
Layer 1c (Mutable) - Shared mutable data lifecycle
Layer 2 (Vector) - Vector memory versioning
Layer 3 (Memory API) - Convenience layer policies

Key Features:

Per-layer retention rules
Per-type/importance rules
Manual enforcement (automatic enforcement planned)
Compliance templates (GDPR, HIPAA, SOC2, FINRA)
Organization-wide or per-agent
Dry-run mode for testing (via simulate())

Policy Structure

Complete Governance Policy

interface GovernancePolicy {
  organizationId?: string; // Optional: org-wide policy
  memorySpaceId?: string; // Optional: memory-space-specific override

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

  // Layer 1b: Immutable
  immutable: {
    retention: {
      defaultVersions: number; // Default versions to keep
      byType: Record<
        string,
        {
          versionsToKeep: number; // -1 = unlimited
          deleteAfter?: string;
        }
      >;
    };
    purging: {
      autoCleanupVersions: boolean;
      purgeUnusedAfter?: string;
    };
  };

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

  // Layer 2: Vector
  vector: {
    retention: {
      defaultVersions: number; // Per memory
      byImportance: Array<{
        range: [number, number]; // [min, max] importance
        versions: number;
      }>;
      bySourceType?: Record<string, number>;
    };
    purging: {
      autoCleanupVersions: boolean;
      deleteOrphaned: boolean; // No conversationRef/immutableRef
    };
  };

  // Sessions: Lifecycle configuration (optional)
  sessions?: {
    lifecycle: {
      idleTimeout: string; // Duration until idle (e.g., '30m', '1h') - default: '30m'
      maxDuration: string; // Max session lifetime (e.g., '24h', '7d') - default: '24h'
      autoExtend: boolean; // Extend session on activity - default: true
      warnBeforeExpiry?: string; // Warning duration (e.g., '5m', '15m')
    };
    cleanup: {
      autoExpireIdle: boolean; // Auto-expire idle sessions - default: true
      deleteEndedAfter?: string; // Delete ended sessions after duration (e.g., '30d')
      archiveAfter?: string; // Archive before deletion (e.g., '7d')
    };
    limits?: {
      maxActiveSessions?: number; // Max concurrent sessions per user
      maxSessionsPerDevice?: number; // Max sessions per device type
    };
  };

  // Cross-layer rules
  compliance: {
    mode: "GDPR" | "HIPAA" | "SOC2" | "FINRA" | "Custom";
    dataRetentionYears: number;
    requireJustification: number[]; // Importance levels needing justification
    auditLogging: boolean;
  };
}

Core Operations

setPolicy()

Set governance policy for organization or agent.

Signature:

cortex.governance.setPolicy(
  policy: GovernancePolicy
): Promise<PolicyResult>

Example:

// Organization-wide policy
await cortex.governance.setPolicy({
  organizationId: "org-123",

  conversations: {
    retention: {
      deleteAfter: "7y", // GDPR compliance
      archiveAfter: "1y",
      purgeOnUserRequest: true,
    },
    purging: {
      autoDelete: true,
      deleteInactiveAfter: "2y",
    },
  },

  immutable: {
    retention: {
      defaultVersions: 20,
      byType: {
        "audit-log": { versionsToKeep: -1 }, // Unlimited
        "kb-article": { versionsToKeep: 50 },
        policy: { versionsToKeep: -1 }, // Unlimited
        "agent-reasoning": { versionsToKeep: 10 },
      },
    },
    purging: {
      autoCleanupVersions: true,
    },
  },

  mutable: {
    retention: {
      defaultTTL: null, // No expiration
      purgeInactiveAfter: "2y",
    },
    purging: {
      autoDelete: false,
    },
  },

  vector: {
    retention: {
      defaultVersions: 10,
      byImportance: [
        { range: [0, 20], versions: 1 }, // Trivial: current only
        { range: [21, 40], versions: 3 }, // Low: 3 versions
        { range: [41, 70], versions: 10 }, // Medium: 10 versions
        { range: [71, 89], versions: 20 }, // High: 20 versions
        { range: [90, 100], versions: 30 }, // Critical: 30 versions
      ],
      bySourceType: {
        conversation: 10,
        a2a: 15,
        system: 5,
        tool: 3,
      },
    },
    purging: {
      autoCleanupVersions: true,
      deleteOrphaned: false, // Keep even if refs broken
    },
  },

  compliance: {
    mode: "GDPR",
    dataRetentionYears: 7,
    requireJustification: [90, 100], // Critical data needs reason
    auditLogging: true,
  },
});

getPolicy()

Get current governance policy.

Signature:

cortex.governance.getPolicy(
  scope?: {
    organizationId?: string;
    memorySpaceId?: string;
  }
): Promise<GovernancePolicy>

Example:

// Get org-wide policy
const orgPolicy = await cortex.governance.getPolicy({
  organizationId: "org-123",
});

// Get agent-specific policy (includes org defaults + overrides)
const agentPolicy = await cortex.governance.getPolicy({
  memorySpaceId: "audit-agent-space",
});

console.log(
  `Vector retention for agent: ${agentPolicy.vector.retention.defaultVersions}`,
);

setAgentOverride()

Override policy for specific agent.

Signature:

cortex.governance.setAgentOverride(
  memorySpaceId: string,
  overrides: Partial<GovernancePolicy>
): Promise<void>

Example:

// Audit agent needs unlimited retention
await cortex.governance.setAgentOverride("audit-agent", {
  vector: {
    retention: {
      defaultVersions: -1, // Unlimited
      byImportance: [
        { range: [0, 100], versions: -1 }, // All versions forever
      ],
    },
  },
  immutable: {
    retention: {
      defaultVersions: -1, // Unlimited
    },
  },
});

// Temp agent needs minimal retention
await cortex.governance.setAgentOverride("temp-agent", {
  vector: {
    retention: {
      defaultVersions: 1, // Current only
    },
  },
  conversations: {
    retention: {
      deleteAfter: "7d", // Delete after 7 days
    },
  },
});

Compliance Templates

const gdprPolicy = await cortex.governance.getTemplate("GDPR");

// Applies:
// - 7-year conversation retention
// - Right to be forgotten
// - Data portability
// - Audit logging
// - Justification for critical data

await cortex.governance.setPolicy({
  organizationId: "org-123",
  ...gdprPolicy,
});

HIPAA Template

const hipaaPolicy = await cortex.governance.getTemplate("HIPAA");

// Applies:
// - 6-year retention minimum
// - Unlimited audit logs
// - No auto-deletion
// - Strict access logging
// - Enhanced purge controls

await cortex.governance.setPolicy({
  organizationId: "healthcare-org",
  ...hipaaPolicy,
});

SOC2 Template

const soc2Policy = await cortex.governance.getTemplate("SOC2");

// Applies:
// - 7-year audit retention
// - Comprehensive logging
// - Version tracking
// - Access controls
// - Purge auditing

await cortex.governance.setPolicy({
  organizationId: "enterprise-org",
  ...soc2Policy,
});

FINRA Template

const finraPolicy = await cortex.governance.getTemplate("FINRA");

// Applies:
// - 7-year mandatory retention (no early deletion)
// - Unlimited versions for financial records
// - No purgeOnUserRequest (regulatory override)
// - No auto-deletion
// - Strict audit logging
// - All importance levels require justification

await cortex.governance.setPolicy({
  organizationId: "financial-services-org",
  ...finraPolicy,
});

Warning

FINRA regulations require retention even when users request deletion. The purgeOnUserRequest: false setting ensures regulatory compliance takes precedence over deletion requests.

Session Policies

Configure session lifecycle timeouts and limits.

Session Timeouts

await cortex.governance.setPolicy({
  organizationId: "org-123",

  // ... other policy fields (conversations, immutable, mutable, vector, compliance) ...

  sessions: {
    lifecycle: {
      idleTimeout: "30m", // Inactivity timeout (default: 30 minutes)
      maxDuration: "24h", // Absolute session lifetime (default: 24 hours)
      autoExtend: true, // Extend session on activity
      warnBeforeExpiry: "5m", // Warn user 5 minutes before expiry
    },
    cleanup: {
      autoExpireIdle: true, // Auto-expire idle sessions
      deleteEndedAfter: "30d", // Delete ended sessions after 30 days
      archiveAfter: "7d", // Archive sessions before deletion
    },
    limits: {
      maxActiveSessions: 5, // Max concurrent sessions per user
      maxSessionsPerDevice: 3, // Max sessions per device type
    },
  },
});

Per-Tenant Session Configuration

// Enterprise tenant: longer sessions
await cortex.governance.setAgentOverride("enterprise-memory-space", {
  sessions: {
    lifecycle: {
      idleTimeout: "1h", // 1 hour idle timeout
      maxDuration: "7d", // 7 day max session
      autoExtend: true,
    },
    cleanup: {
      autoExpireIdle: true,
      deleteEndedAfter: "90d",
    },
    limits: {
      maxActiveSessions: 20,
    },
  },
});

// Security-sensitive tenant: shorter sessions
await cortex.governance.setAgentOverride("banking-memory-space", {
  sessions: {
    lifecycle: {
      idleTimeout: "5m", // 5 minute idle timeout
      maxDuration: "1h", // 1 hour max session
      autoExtend: false, // No auto-extension for security
      warnBeforeExpiry: "2m", // Warn 2 minutes before expiry
    },
    cleanup: {
      autoExpireIdle: true,
      deleteEndedAfter: "7d",
    },
    limits: {
      maxActiveSessions: 3,
    },
  },
});

Session Policy Integration

Session policies defined here configure the behavior enforced by the Sessions API. The Governance API defines the rules, while the Sessions API executes them.

// Governance defines the policy
await cortex.governance.setPolicy({
  organizationId: "org-123",
  // ... other policy fields ...
  sessions: {
    lifecycle: { idleTimeout: "30m", maxDuration: "24h", autoExtend: true },
    cleanup: { autoExpireIdle: true, deleteEndedAfter: "30d" },
  },
});

// Sessions API operations respect these governance policies
// See Sessions API documentation for expireIdle(), cleanup(), etc.

Info

Session operations like expireIdle() are part of the Sessions API, not the Governance API. The governance policy configures timeouts and limits that the Sessions API enforces.

Enforcement

Automatic Enforcement

Warning

PLANNED FEATURE: Automatic policy enforcement is on the roadmap but not yet fully implemented. Currently, use enforce() for manual policy execution. Automatic hooks into storage operations are planned for a future release.

When fully implemented, policies will be enforced automatically on storage operations:

// PLANNED: Policy will be enforced automatically on store/update operations

// Example: Vector with importance-based retention
await cortex.vector.store('agent-1', {
  content: 'Trivial log message',
  metadata: { importance: 5 }  // 0-20 range
});

// Policy says: 0-20 = keep 1 version
// PLANNED: After first update, v1 would be automatically purged
await cortex.vector.update('agent-1', memoryId, {...});
// PLANNED: v1 deleted automatically, only v2 kept

// CURRENT: Use manual enforcement instead
await cortex.governance.enforce({
  scope: { organizationId: 'org-123' },
  layers: ['vector'],
  rules: ['retention'],
});

Manual Enforcement

Signature:

cortex.governance.enforce(
  options: {
    scope: { organizationId?: string; memorySpaceId?: string }; // Required
    layers?: ("conversations" | "immutable" | "mutable" | "vector")[];
    rules?: ("retention" | "purging")[];
  }
): Promise<EnforcementResult>

Example:

// Trigger immediate policy enforcement
const result = await cortex.governance.enforce({
  scope: { organizationId: "org-123" }, // Required: org or memory space
  layers: ["vector", "immutable"], // Which layers
  rules: ["retention", "purging"], // Which rules
});

console.log(`Enforced retention: ${result.versionsDeleted} versions deleted`);
console.log(`Purged records: ${result.recordsPurged}`);
console.log(`Storage freed: ${result.storageFreed} MB`);

// Enforce for specific memory space
const spaceResult = await cortex.governance.enforce({
  scope: { memorySpaceId: "audit-agent-space" },
  layers: ["vector"],
  rules: ["retention"],
});

EnforcementResult Interface

interface EnforcementResult {
  enforcedAt: number; // Unix timestamp when enforcement ran
  versionsDeleted: number; // Total versions deleted across all layers
  recordsPurged: number; // Total records purged
  storageFreed: number; // Storage freed in MB
  affectedLayers: string[]; // Layers that were affected
}

EnforcementStats Interface

interface EnforcementStats {
  period: {
    start: number; // Unix timestamp
    end: number; // Unix timestamp
  };
  conversations: {
    purged: number; // Conversations deleted
    archived: number; // Conversations archived
  };
  immutable: {
    versionsDeleted: number; // Immutable versions cleaned up
    entitiesPurged: number; // Immutable entities removed
  };
  vector: {
    versionsDeleted: number; // Vector memory versions deleted
    memoriesPurged: number; // Vector memories removed
  };
  mutable: {
    keysDeleted: number; // Mutable keys deleted
  };
  storageFreed: number; // Total storage freed in MB
  costSavings: number; // Estimated cost savings in USD
}

Policy Simulation

Test Policy Impact

// Simulate policy without applying
const impact = await cortex.governance.simulate({
  organizationId: 'org-123',
  vector: {
    retention: {
      byImportance: [
        { range: [0, 30], versions: 1 }  // More aggressive
      ]
    }
  }
});

console.log('Impact analysis:');
console.log(`Would delete ${impact.versionsAffected} Vector versions`);
console.log(`Would save ${impact.storageFreed} MB`);
console.log(`Estimated monthly savings: $${impact.costSavings}`);

// If acceptable, apply
if (impact.costSavings > 50) {
  await cortex.governance.setPolicy({...});
}

Reporting

Compliance Report

// Generate compliance report
const report = await cortex.governance.getComplianceReport({
  organizationId: "org-123",
  period: {
    start: new Date("2025-01-01"),
    end: new Date("2025-10-31"),
  },
});

console.log(report);
// {
//   conversations: {
//     total: 5432,
//     deleted: 123,
//     archived: 1200,
//     complianceStatus: 'COMPLIANT'
//   },
//   immutable: {
//     entities: 234,
//     totalVersions: 1543,
//     versionsDeleted: 300,
//     complianceStatus: 'COMPLIANT'
//   },
//   vector: {
//     memories: 15432,
//     versionsDeleted: 5000,
//     orphanedCleaned: 45,
//     complianceStatus: 'COMPLIANT'
//   },
//   dataRetention: {
//     oldestRecord: new Date('2018-01-01'),
//     withinPolicy: true
//   },
//   userRequests: {
//     deletionRequests: 5,
//     fulfilled: 5,
//     avgFulfillmentTime: '2.3 hours'
//   }
// }

Error Handling

The Governance API provides a custom error class for validation failures, allowing you to catch and handle governance-specific errors.

GovernanceValidationError

import { GovernanceValidationError } from "@cortex/sdk";

class GovernanceValidationError extends Error {
  name: "GovernanceValidationError";
  code: string; // Error code for programmatic handling
  field?: string; // Field that caused the error (if applicable)
}

Error Codes

Parameter	Type	Required	Default	Description
`MISSING_POLICY`	`error`	No	—	Policy object is required but not provided
`MISSING_REQUIRED_FIELD`	`error`	No	—	Required field missing (e.g., `conversations`, `compliance`)
`MISSING_SCOPE`	`error`	No	—	Scope (organizationId or memorySpaceId) is required
`INVALID_SCOPE`	`error`	No	—	Scope provided but invalid (empty string, etc.)
`INVALID_PERIOD_FORMAT`	`error`	No	—	Period string doesn't match format (e.g., `7d`, `1y`)
`INVALID_IMPORTANCE_RANGE`	`error`	No	—	Importance range invalid (not 0-100, min >= max)
`OVERLAPPING_IMPORTANCE_RANGES`	`error`	No	—	Two importance ranges overlap
`INVALID_VERSIONS`	`error`	No	—	Version count invalid (must be >= -1)
`INVALID_LAYERS`	`error`	No	—	Invalid layer specified for enforcement
`INVALID_RULES`	`error`	No	—	Invalid rule specified for enforcement
`INVALID_DATE_RANGE`	`error`	No	—	Start date must be before end date
`INVALID_PERIOD`	`error`	No	—	Stats period invalid (must be `7d`, `30d`, `90d`, `1y`)
`INVALID_COMPLIANCE_MODE`	`error`	No	—	Invalid compliance template name

Example Usage

import { GovernanceValidationError } from "@cortex/sdk";

try {
  await cortex.governance.setPolicy({
    organizationId: "org-123",
    conversations: {
      retention: { deleteAfter: "invalid" }, // Invalid format
      purging: { autoDelete: true },
    },
    // ... other fields
  });
} catch (error) {
  if (error instanceof GovernanceValidationError) {
    console.error(`Validation failed: ${error.message}`);
    console.error(`Error code: ${error.code}`);
    console.error(`Field: ${error.field}`);

    // Handle specific error codes
    switch (error.code) {
      case "INVALID_PERIOD_FORMAT":
        console.error('Period must be like "7d", "30d", "1y"');
        break;
      case "MISSING_SCOPE":
        console.error("Provide organizationId or memorySpaceId");
        break;
    }
  } else {
    throw error; // Re-throw non-validation errors
  }
}

Best Practices

1. Start with Template

// Use compliance template as base
const basePolicy = await cortex.governance.getTemplate("GDPR");

// Customize as needed
await cortex.governance.setPolicy({
  organizationId: "org-123",
  ...basePolicy,
  vector: {
    ...basePolicy.vector,
    retention: {
      ...basePolicy.vector.retention,
      defaultVersions: 15, // Override default
    },
  },
});

2. Test Before Applying

// Always simulate first
const impact = await cortex.governance.simulate(newPolicy);

if (impact.versionsAffected > 1000) {
  console.warn("Policy would delete significant data - review carefully");
}

3. Agent-Specific Overrides Sparingly

// Most agents use org policy
// Only override for special cases

await cortex.governance.setAgentOverride("audit-agent", {
  // Unlimited retention for audit agent
  vector: { retention: { defaultVersions: -1 } },
});

await cortex.governance.setAgentOverride("temp-agent", {
  // Minimal retention for temporary agent
  vector: { retention: { defaultVersions: 1 } },
  conversations: { retention: { deleteAfter: "7d" } },
});

4. Monitor Enforcement

// Track what's being purged
const stats = await cortex.governance.getEnforcementStats({
  period: "30d",
});

console.log(`Last 30 days:`);
console.log(`- Vector versions deleted: ${stats.vector.versionsDeleted}`);
console.log(`- Immutable versions deleted: ${stats.immutable.versionsDeleted}`);
console.log(`- Conversations purged: ${stats.conversations.purged}`);
console.log(`- Storage freed: ${stats.storageFreed} MB`);
console.log(`- Cost savings: $${stats.costSavings}`);

Summary

Governance Policies provide:

Centralized retention rules
Per-layer configuration
Compliance templates (GDPR, HIPAA, SOC2, FINRA)
Manual enforcement via enforce()
Automatic enforcement (planned)
Cost optimization via simulate()
Audit trail via getComplianceReport()

Configuration Hierarchy:

Global defaults (Cortex defaults)
Compliance template (GDPR, HIPAA, etc.)
Organization policy
Agent-specific overrides

Enterprise Value:

Compliance template support (GDPR, HIPAA, SOC2, FINRA)
Cost control at scale via policy simulation
Centralized retention management
Built-in audit trails and compliance reporting

Next Steps

Questions? Ask in GitHub Discussions.

Overview​

Policy Structure​

Complete Governance Policy​

Core Operations​

setPolicy()​

getPolicy()​

setAgentOverride()​

Compliance Templates​

GDPR Template​

HIPAA Template​

SOC2 Template​

FINRA Template​

Session Policies​

Session Timeouts​

Per-Tenant Session Configuration​

Session Policy Integration​

Enforcement​

Automatic Enforcement​

Manual Enforcement​

EnforcementResult Interface​

EnforcementStats Interface​

Policy Simulation​

Test Policy Impact​

Reporting​

Compliance Report​

Error Handling​

GovernanceValidationError​

Error Codes​

Example Usage​

Best Practices​

1. Start with Template​

2. Test Before Applying​

3. Agent-Specific Overrides Sparingly​

4. Monitor Enforcement​

Summary​

Next Steps​

Overview

Policy Structure

Complete Governance Policy

Core Operations

setPolicy()

getPolicy()

setAgentOverride()

Compliance Templates

GDPR Template

HIPAA Template

SOC2 Template

FINRA Template

Session Policies

Session Timeouts

Per-Tenant Session Configuration

Session Policy Integration

Enforcement

Automatic Enforcement

Manual Enforcement

EnforcementResult Interface

EnforcementStats Interface

Policy Simulation

Test Policy Impact

Reporting

Compliance Report

Error Handling

GovernanceValidationError

Error Codes

Example Usage

Best Practices

1. Start with Template

2. Test Before Applying

3. Agent-Specific Overrides Sparingly

4. Monitor Enforcement

Summary

Next Steps