Skip to main content
Reflections is a voice-first AI agent backed by a personal knowledge graph. Users talk to their “reflection” — an LLM that retrieves and reasons over chunked documents, entities, and temporal facts ingested from uploaded sources.

​
What the platform does

When a user speaks, the platform:
  1. Bootstraps a voice session through a managed provider (ElevenLabs Conversations API).
  2. Retrieves relevant facts, entities, and document chunks from the knowledge graph during the conversation via server-tool callbacks.
  3. Ingests new sources in the background — extracting facts, evaluating them, and promoting approved knowledge into the graph.
The result is a continuously learning agent that remembers what you tell it, with safety gates that prevent unvetted information from entering active truth.

​
Tech stack

LayerTechnology
Monorepopnpm 10.15+ with Turborepo
RuntimeNode.js >= 22, ESM throughout
LanguageTypeScript in strict mode, tsup builds
DatabaseSupabase Postgres with pgvector for embeddings
Background jobsInngest for durable step functions
VoiceElevenLabs Conversations API
AuthClerk JWT (frontend) + bearer tokens (service-to-service)
FrontendNext.js (web), native Swift (iOS)
ValidationZod schemas shared across all layers

​
Two execution planes

The system separates work into two execution planes with different latency and safety requirements.

Realtime plane

Voice session bootstrap, server-tool callbacks, and knowledge retrieval. Read-only against truth tables (facts, entities, chunks, sources). Optimized for low latency.

Background plane

Source ingestion, fact extraction, evaluation, and patch application. Facts enter as candidates and become active only after passing the eval gate.
This separation ensures that write-side failures in the background pipeline never impact user-facing voice response times. See Two-plane architecture for a full explanation.

​
DB query segregation

The @reflection/db package exposes three entrypoints that enforce access boundaries at the import level:
  • ./queries/read — used by the realtime plane for retrieval queries.
  • ./queries/write — used for mutations like conversation logging.
  • ./queries/admin — used exclusively by background workers for ingestion, patch application, and evaluation writes.
ESLint rules block admin imports from the realtime and API planes. File-scan tests provide an additional enforcement layer that cannot be disabled with inline comments.

​
Dependency direction

Packages never depend on apps. Apps consume packages only through published entrypoints. 
apps/api  ─────┐
apps/workers ──┤
apps/web  ─────┼──▶  packages/brain-core
apps/ios  ─────┘     packages/db
                     packages/schemas
                     packages/vendors
                     packages/shared
                     packages/eval
                     packages/api-client
This rule is enforced by the monorepo structure, ESLint configuration, and architecture guard scripts. See Package map for the full breakdown.

​
Learn more

Two-plane architecture

Why the system separates realtime inference from background learning.

Boundary matrix

What each plane is allowed and forbidden to do.

System invariants

Non-negotiable rules, complexity budgets, and release blockers.

Package map

Every app and package in the monorepo with its purpose and dependencies.

Knowledge graph

Temporal facts, the patch lifecycle, and the aspect taxonomy.

Decision records

25 ADRs documenting core architectural choices.