logicspike/docs

Contact Intelligence

Contact Intelligence

Last Updated: 2026-06-29 Status: Active

Contact Intelligence (CI) is the per-contact deep memory layer for vlozi's AI bots. It stores what the bot knows about each end-user — facts, preferences, episodes, emotional history, and relationship stage — and surfaces the right slice of that knowledge on every message.

CI is a backend Cloudflare Worker (logicspike-contact-intelligence). It has no UI of its own; the dashboard (Phase 6) will surface it to business owners.

Doc Index

File What it covers
vision.md Why CI exists, core principles, V1/V2 scope
api-spec.md All HTTP endpoints with request/response shapes
domain-model.md DB tables, column definitions, state machines
system-architecture.md Memory tiers (L1/L2/L3), data flow, integration points
contact-memory-spec.md How memories are extracted, scored, decayed, consolidated
proactive-outreach-spec.md Trigger types, delivery pipeline, anti-spam rules
user-journey.md End-to-end journeys across 7 actor types
backlog.md Known bugs, improvement areas, Phase 5/6 status

Reading Paths

  • New to CI → vision → system-architecture → api-spec
  • Debugging memory issues → contact-memory-spec → domain-model (supersededBy, decayRate columns)
  • Adding outreach → proactive-outreach-spec → api-spec (Outreach section) → domain-model
  • Planning Phase 5 (CE integration) → api-spec (context response shape) → system-architecture (integration points)

Codebase Quick Map

apps/contact-intelligence/
├── src/
│   ├── routes/         contacts, context, ingest, outreach
│   ├── lib/            extraction, entity-graph, consolidation, relationship, mood
│   ├── db/             schema.ts, client.ts, drizzle migrations (0001–0005)
│   └── index.ts        worker entry: fetch, scheduled (6h + weekly), queue consumer
├── test/               vitest suite — 86 tests across 6 files
└── wrangler.toml       CONSOLIDATION_QUEUE + CHAT_ENGINE_SERVICE bindings

4 Things Every Developer Must Know

1. Phase 5 is not built — CI feeds nothing yet. Chat Engine still calls the old GET /context/:id/mood endpoint (backward-compat stub). Until the CE orchestrator is updated, GET /context/:id (the new L1+L2 packet) is only consumed by tests and direct API calls.

2. session_core is null until first weekly consolidation. After a contact's session_count exceeds cold_start_used_until (default 5), the response switches from the generic cold-start string to contacts.core_summary. That column stays null until the Sunday 2am UTC cron runs consolidateContact() and writes an LLM-generated summary.

3. L2 semantic search is async-delayed for fresh contacts. Embeddings are generated via c.executionCtx.waitUntil() (fire-and-forget). The first GET /context/:id?message=... call after a new ingest will return message_relevance: null. Embeddings land in the DB a few seconds later.

4. Delete is permanent for memory data. DELETE /contacts/:id hard-deletes ci_contact_memory, ci_contact_entities, and ci_interaction_logs — no undo. The contact row itself is soft-deleted (sets deletedAt and scrubs PII). The cascade on ci_entities, ci_emotional_snapshots, ci_relationship_snapshots, and ci_contact_channels fires automatically because the FK has onDelete: "cascade".

Contact Intelligence