@ultragit/core

Agent memory that earns its knowledge from the physical world.

UltraGit is a storage-agnostic memory protocol for AI agents operating in physical environments. It turns real-world interactions — barcode scans, voice reports, clock events, work orders, GPS presence — into a tiered memory stack that grows smarter over time.

The gap between an AI that retrieves and an AI that knows is context richness. UltraGit closes that gap by anchoring memory to real events, with time and fatigue running through every record.

Why UltraGit

Most AI memory systems are flat databases with a chat interface. UltraGit is different:

• Physical anchors create ground truth — the AI knows things because a human touched a real object, not because someone typed a report
• Fatigue is a first-class dimension — every event carries who did it, when in their shift, and how tired they likely were
• Instinct emerges from repetition — patterns aren't configured, they're distilled from the ledger over time
• Confidence is earned — a pattern that's fired twice opens at confidence 30. After 30 days of real data it might be at 95. The AI doesn't assert certainty, it earns it
• Storage-agnostic — bring your own database. Postgres, Firestore, SQLite — the core never changes

How It Works

Physical write-heads (QR scan, voice, clock-in, form submit)
        ↓
Append-only event ledger (timestamped, dimensioned, actor-linked)
        ↓
The Vet (nightly compression engine)
  → pins high-signal events permanently
  → compresses old noise into weekly summaries
  → distills instinct patterns from the ledger
        ↓
Rolling state context (injected into AI system prompt at query time)
        ↓
AI that knows things because humans did things in the real world

Install

npm install @ultragit/core

Pick an adapter for your database:

npm install @ultragit/adapter-firebase    # Firebase / Firestore
npm install @ultragit/adapter-postgres    # PostgreSQL / Drizzle

Quickstart

import { createFirebaseAdapter } from '@ultragit/adapter-firebase'
import {
  runVetCycle,
  assembleRollingState,
  formatBriefing,
  calculateDimensions,
  deriveValenceFromOutcome,
  deriveStakes,
  getTemporalContext,
} from '@ultragit/core'
import { initializeApp } from 'firebase/app'
import { getFirestore } from 'firebase/firestore'

const app = initializeApp(firebaseConfig)
const db = getFirestore(app)
const adapter = createFirebaseAdapter(db)

// 1. Write an event when something happens in the physical world
const now = new Date()
const dims = calculateDimensions(shiftElapsedMinutes, 'qr_scan', true)

await adapter.insertEvent({
  trigger: 'qr_scan',
  entityType: 'equipment',
  entityId: 'asset-001',
  entityLabel: 'Excavator #4',
  actorUid: 'worker-123',
  actorName: 'Matt Henderson',
  actorTrade: 'plant_operator',
  shiftElapsedMinutes: 320,
  site: 'Kent Renovation — Main St',
  outcome: 'scan_only',
  source: 'worker',
  timestamp: now,
  ...dims,
  valence: deriveValenceFromOutcome('scan_only'),
  stakes: deriveStakes('qr_scan', dims.arousal, dims.fatigueIndex),
  ...getTemporalContext(now),
  silentFault: false,
  timeSinceLastEventMinutes: null,
  daysSinceLastScanEntity: null,
  gpsLat: null, gpsLng: null,
  weather: null, activeWo: null,
  clockedInSince: null, payload: null, note: null,
})

// 2. Run the Vet cycle (nightly — compresses old events, distills patterns)
const result = await runVetCycle(adapter)
console.log(result)
// { eventsProcessed: 142, eventsCompressed: 89, instinctPatternsUpdated: 5 }

// 3. Assemble rolling state and inject into your AI system prompt
const state = await assembleRollingState(adapter, {
  actorUid: 'worker-123',
  site: 'Kent Renovation — Main St',
})
const briefing = formatBriefing(state)

const systemPrompt = `You are a field intelligence assistant.\n\n${briefing}`
// → AI now knows active personnel, recent high-signal events,
//   pinned anchors, and instinct patterns from the ledger

The Memory Stack

| Tier | What it is | How long it lives | |------|-----------|------------------| | Raw events | Every physical interaction, fully dimensioned | Until compressed by The Vet | | Pinned anchors | High-stakes events (emergencies, delta triggers) | Forever | | Compressed summaries | Weekly rollups of low-signal events | Forever | | Instinct patterns | Behavioral patterns distilled from the ledger | Forever, confidence-weighted |

Instinct Pattern Types

The Vet automatically detects and distills these patterns:

| Pattern | What it means | |---------|--------------| | recurring_defect | Entity has repeated defect events | | fatigue_correlation | Defects on this entity correlate with high-fatigue interactions | | compliance_drift | Safety compliance declining over the last 14 days | | actor_fatigue | Actor consistently interacts with this entity late in shift | | silent_fault_cluster | Repeated scans with no follow-up — systematic oversight |

Dimensions

Every event carries a full dimensional signature:

| Dimension | What it captures | |-----------|----------------| | fatigueIndex | (shiftElapsedMinutes / 600)² — exponential cliff after 10hrs | | arousal | Signal strength of the trigger type | | valence | Outcome sentiment (-1.0 to +1.0) | | temporalWeight | Combined signal weight for memory prioritisation | | deltaTrigger | True if this event breaks the established pattern | | silentFault | True if a scan had no follow-up action within the window |

StorageAdapter Interface

UltraGit is storage-agnostic. Implement StorageAdapter to use any backend:

import type { StorageAdapter } from '@ultragit/core'

const myAdapter: StorageAdapter = {
  insertEvent: async (event) => { /* ... */ },
  queryEvents: async (filters) => { /* ... */ },
  // ... 12 methods total
}

Official adapters:

• @ultragit/adapter-firebase — Firebase / Firestore
• @ultragit/adapter-postgres — PostgreSQL via Drizzle ORM

License

MIT © OnliestWizard