Temporal Planes

The platform's deep contextual understanding comes from organizing data across three temporal dimensions.

The Three Planes

Plane of the Past — The Historical Archive

The immutable record of everything that has ever happened. All data ingested from connectors, all events, all communications.

NATS JetStream (Event Store) The absolute source of truth. Every state change is a published event that is persisted and replayable. If you need to reconstruct the state of the knowledge graph at any point in the past, you replay events from NATS.

PostgreSQL + pgvector (Knowledge Graph) Normalized entities and relationships — Person, Message, Conversation, Event, Document, Location, Task. This is the queryable, structured view of the past. pgvector adds semantic search via stored embeddings.

Meilisearch (Search Index) Full-text search across all textual data. Documents, email bodies, SMS threads, call transcripts, notes. Fast, typo-tolerant, filterable. Populated via IndexDocumentJob background jobs triggered by data.EntityCreated events.

TimescaleDB — High-Volume Time-Series (aspirational — not yet deployed) High-volume time-series data (GPS fixes, sensor readings, health metrics) would benefit from TimescaleDB's compression and time-range query optimization. The current deployment uses a plain PostgreSQL location_history table with a time-based index; no TimescaleDB image is present in docker-compose.yml and no hypertable migration exists. Migration to TimescaleDB hypertables is a future step when volume justifies it.

Past Plane Data Flow

Connector Plugin
  └─► connector.DataReceived (NATS — persisted)
        └─► ETL Service (ProcessIncomingDataJob)
              └─► Data Service → PostgreSQL entities
                    └─► data.EntityCreated (NATS — persisted)
                          ├─► Search Service → Meilisearch index
                          └─► AI Service → pgvector embeddings

Plane of the Present — The Attention Stream

Real-time, millisecond-latency representation of the user's current state. The "attention" data — what is happening right now.

Redis (State Store) Key-value store for current state:

user:{userId}:location:current    → {lat, lon, locationName, updatedAt}
user:{userId}:activity:current    → {type: "driving|walking|stationary", updatedAt}
user:{userId}:device:active       → {deviceId, appName, updatedAt}
user:{userId}:availability        → {status: "available|busy|dnd", until: timestamp}

All keys have TTL. If no update arrives, the key expires and state is "unknown."

Stream Processing Service Subscribes to high-frequency device events (connector.LocationUpdated, connector.DeviceEventReceived) and:

1. Updates Redis state immediately (< 100ms path)
2. Archives to PostgreSQL/TimescaleDB asynchronously (background path)
3. Enriches raw location fixes against known Location entities (geofence matching)
4. Triggers real-time rules when state changes cross thresholds

Present Plane Data Flow

Android GPS fix
  └─► POST /device-events (hub)
        └─► Device Connector Plugin
              └─► connector.LocationUpdated (NATS)
                    ├─► Stream Processing Service
                    │     ├─► Redis: user:X:location:current = {lat, lon, "Work", ...}
                    │     └─► Geofence check: entered "Work" → trigger DND rule
                    └─► location_history → PostgreSQL (background, via job)

Why this matters for the call router: When a call arrives, the Rules Service needs to know right now if the user is at work. A database query against location_history would give the last known location, but could be stale. The Redis state store gives the current location with guaranteed freshness (or signals that it's unknown if the device hasn't synced recently).

Plane of the Future — The Intentions Engine

Declarative representation of the user's plans, goals, and commitments.

Intentions Service Manages all future-oriented data:

• Calendar events (synced from MS Graph / Google Calendar)
• Tasks with due dates (synced or created natively)
• Goals and commitments (user-defined)
• Recurring patterns (automatically inferred from past behavior)

Scheduler (pg-boss cron) Schedules jobs to fire at specific future times:

• "Remind me 45 minutes before the meeting at Dr. Smith's office"
• "Sync this connector every hour"
• "If no response in 5 minutes, escalate"

Future Plane Data Flow

MS Graph Calendar sync
  └─► Event entity in PostgreSQL (Past plane)
        └─► Intentions Service picks up upcoming events
              └─► Schedules reminder jobs in pg-boss
                    └─► At T-45min: notification sent + travel time checked

Why this matters: The system can be proactive without requiring AI. "Leave in 10 minutes for your appointment — current traffic adds 8 minutes to your usual 23 minute drive" — this is a rule + scheduler + location data, not an LLM call.

Deployment Stages

Foundation:

• NATS JetStream deployed and running
• PostgreSQL knowledge graph (all v1 entities)
• Meilisearch full-text search
• location_history table (plain PG)
• pg-boss for scheduled sync jobs
• Present plane: Redis for current location (basic; hub updates Redis directly on device events)

Full Stream Processing:

• Dedicated Stream Processing Service with full geofence evaluation (StreamProcessingService exists at apps/hub/src/services/stream/StreamProcessingService.ts; full geofence evaluation scope is aspirational)
• TimescaleDB hypertables for location_history and health metrics (aspirational — see note above)
• Full Intentions Service with goal tracking and pattern inference (IntentionsService exists; pattern inference is aspirational)
• Redis state store covers all current-state dimensions (activity, app, availability) (Redis is deployed; full dimension coverage is aspirational)