Database / Memory

What It Does

The storage layer underpins everything. Three distinct systems handle different kinds of data:

• PostgreSQL — structured data store for all contacts, conversations, care plans, content, billing, and tenant config. Also hosts pgvector for semantic memory search (vector embeddings stored alongside text). 90+ tables total.
• Redis + BullMQ — job queue for all background and scheduled work: follow-ups, care plan steps, content generation, nurture sequences, watchdog checks. Jobs are persisted and retried on failure.
• PHI vault — sensitive medical data (procedure photos, intake forms, clinical notes) stored in an isolated directory on the Hetzner server, separate from the main database. Compliant with DPA 2020. Ready for migration to AWS S3 when required.

External Service Details

• PostgreSQL: container iv_postgres, database irievybz_core, user irievybz
• Redis: container iv_redis
• PHI storage: /opt/irievybz/data/oshun-phi/photos on the Hetzner VPS. Hetzner GDPR-compliant hosting. AWS migration path is documented but not yet scheduled.

Journeys

The database layer supports all 10 patient and operational journeys:

• Journey 1 — Lead to First Response
• Journey 2 — Inquiry to Booking
• Journey 3 — Pre-Appointment
• Journey 4 — Procedure to Post-Care
• Journey 5 — Re-Engagement
• Journey 6 — Content Engine
• Journey 7 — Email Campaigns
• Journey 8 — Voice Calls
• Journey 9 — Billing
• Journey 10 — Analytics

Key Source Files

• src/db.js — PostgreSQL connection pool. All modules import from here — never create a separate pool.
• src/memory.js — Knowledge storage and retrieval. Key exports: storeConversation() (line 177), storeKnowledge() (line 195), storeProfile() (line 213), hybridSearch() (line 125), searchVector() (line 28), searchKeyword() (line 83).
• src/core_memory.js — Persistent per-tenant core memory (persona, goals, business context). Key exports: getCoreMemory(), upsertSection().
• src/consolidator_memory.js — Per-turn memory consolidation and daily digests. Key exports: consolidateTurn() (line 38), runDailyDigest().
• src/contacts.js — Contact CRUD with auto-merge across channels. Key exports: findOrCreateContact() (line 6), mergeContacts() (line 202), acquireContactLock() (line 128).
• src/scheduler.js — BullMQ job scheduling for follow-ups and timed sequences.
• antigravity-core/schema.sql — Full database schema definition.
• antigravity-core/migrations/ — 33 numbered migration files. All are idempotent (IF NOT EXISTS). Run manually via psql — never auto-applied.

Memory Search System

Karen uses a hybrid search approach to retrieve relevant memory. All four methods are combined via Reciprocal Rank Fusion (RRF) to produce a single ranked result set:

1. searchVector() — pgvector semantic similarity. Converts the query to an embedding and finds the nearest stored vectors. Best for meaning-based retrieval ("what did this patient ask about last time").
2. searchKeyword() — PostgreSQL full-text search (tsvector/tsquery). Best for exact term matching ("Botox", procedure names, contact names).
3. searchTags() — Tag-based filtering. Memories can be tagged by category (e.g. care_plan, booking, complaint) for fast scoped retrieval.
4. searchExact() — Exact string match against indexed fields. Used for lookups by ID, phone number, or known unique values.

The combined hybridSearch() function (line 125 of src/memory.js) runs all four in parallel and merges the ranked results before returning to the context builder.

Known Issues