[Feature]: Bi-Temporal Model for Historical Queries and Compliance

[zircote]

Problem Statement

Subcog currently tracks only creation time (created_at) and update time (updated_at). This is insufficient for:

• Compliance requirements ("What did we know on date X?")
• Conflict resolution ("Which fact is more recent?")
• Audit trails ("When was this information ingested?")
• Historical queries ("Reconstruct state at time T")

Zep Graphiti engine implements a bi-temporal model that enables powerful historical capabilities, achieving 18.5% accuracy improvement on temporal queries.

Proposed Solution

Implement bi-temporal tracking with three timestamps:

1. t_valid: When the event/fact actually occurred
2. t_invalid: When the fact became outdated (null if still valid)
3. t_ingested: When it was recorded in the system

Benefits:

• Historical state reconstruction at any point in time
• Intelligent conflict resolution using temporal metadata
• Compliance audit trails with full lineage
• Temporal queries: "What did we know about X in March?"

Proposed API:

pub struct TemporalMetadata {
    valid_from: DateTime,           // When fact became true
    valid_until: Option<DateTime>,  // When fact became false (null = still valid)
    ingested_at: DateTime,          // When we recorded it
}

MCP tool parameters:

subcog_capture:
  content: "PostgreSQL 15 is now supported"
  namespace: decisions
  valid_from: "2024-01-15"  # When this became true

subcog_recall:
  query: "database decisions"
  as_of: "2024-06-01"       # Point-in-time query
  valid_at: "2024-03-01"    # Filter by validity period

CLI:

subcog recall "database" --as-of 2024-06-01

Alternatives Considered

• Single timestamp (current) - insufficient for compliance
• Soft delete only - loses historical context
• Separate history table - query complexity

Additional Context

• Zep bi-temporal: https://arxiv.org/abs/2501.13956
• Essential for regulated industries (finance, healthcare)
• Integrates with conflict resolution feature

Breaking Change: Yes - minor changes (new timestamp fields)
Priority: Important
Contribution: Yes, with guidance