Module 04

A guarded AI explanation layer for psychology-focused product experiences.

MindMirror Conversational AI Agent

Rather than building a general chatbot, this service was intentionally constrained around psychology interpretation. That tradeoff improves relevance, trust, and production safety.

Back to Projects View Repository

Overview

Built a memory-aware AI service that turns structured MindMirror predictions into grounded conversational explanations using user-specific retrieval, cache reuse, and corrective web search with explicit domain restrictions.

Problem

MindMirror predictions and scores were useful but difficult to interpret conversationally, while unconstrained assistants would introduce hallucination and out-of-scope risk in a sensitive domain.

Approach

I designed a LangGraph-based orchestration flow with domain routing, user-scoped retrieval, hybrid memory, semantic cache reuse, and corrective search rules that stay inside psychology.

Project Overview

A modern engineering case study, structured for both recruiters and builders

Challenge Framing

MindMirror predictions and scores were useful but difficult to interpret conversationally, while unconstrained assistants would introduce hallucination and out-of-scope risk in a sensitive domain.

Solution Strategy

I designed a LangGraph-based orchestration flow with domain routing, user-scoped retrieval, hybrid memory, semantic cache reuse, and corrective search rules that stay inside psychology.

Project Highlights

Five-route guarded router for direct, RAG, memory, web-search, or reject decisions.
Hybrid memory design with short-term turns and distilled long-term facts.
CAG semantic cache plus weak-context corrective search.
SSE graph streaming for stage-level execution visibility.

Tech Stack

Built with tools chosen for reliability and iteration speed

Agent orchestration, guarded retrieval, personalized memory, domain safety, and operational observability for AI-backed products.

Core Stack

Python 3.10
FastAPI
LangGraph
LangChain
Supabase
Chroma
OpenAI
Tavily

Key Features

Guarded routing

The router enforces domain restriction before retrieval or generation begins.

User-scoped retrieval

Prediction data is resolved against canonical user identity before context assembly.

Personalized memory

Short-term conversation state and long-term facts are recalled under a strict token budget.

Operational transparency

SSE streaming and observability hooks expose graph progress, latency, and debugging context.

Architecture

System architecture designed as a readable engineering story

Each layer stays explicit so reviewers can quickly understand where ingestion, orchestration, persistence, and model-serving responsibilities live.

API Surface

Chat, streaming, health, graph, and memory endpoints expose the service to MindMirror clients and developers.

FastAPISSEPydantic

Agent Orchestration

LangGraph coordinates recall, routing, cache, retrieval, synthesis, and memory write-back.

LangGraphLangChainOpenAI

Persistence + Retrieval

Supabase stores operational memory and user data while Chroma supports semantic cache lookup.

SupabaseChromaTavily

AI Pipeline

Pipeline stages broken down as a readable execution path

The pipeline section keeps the most important engineering steps visible without collapsing them into generic bullet lists.

Recall

Load recent turns and long-term facts under a bounded context budget.

Supabasetoken budgeting

Route

Classify the query into a safe execution path and reject non-psychology requests.

OpenAILangGraph

Retrieve

Resolve user identity, fetch prediction context, or expand into corrective search when internal evidence is weak.

SupabaseTavilyChroma

Synthesize

Generate grounded explanations, then persist cache hits and memory-worthy facts for future turns.

OpenAILangGraph

Timeline

A case-study flow that explains how the system took shape

This timeline keeps the implementation story concise: what was framed first, what was hardened next, and what ultimately made the project production-ready.

Phase 01

Domain-bounded assistant design

Constrained the assistant to psychology and MindMirror contexts before retrieval logic was added.

Phase 02

Memory and cache personalization

Introduced short-term recall, long-term fact distillation, and semantic cache reuse for repeated queries.

Phase 03

Operational instrumentation

Added streaming graph visibility and observability hooks to support debugging and cost inspection.

Challenges

Technical constraints, decisions, and the reasoning behind them

This section is intentionally recruiter-friendly and engineer-friendly at the same time: each challenge is tied to a concrete design choice and a specific outcome.

Challenge

Preventing out-of-scope answers in a sensitive domain.

Solution

Added layered routing constraints, a fixed safe route set, and reject paths before retrieval and synthesis.

Outcome

Improved trust and reduced generic-chatbot drift.

Challenge

Keeping context useful without bloating prompts.

Solution

Separated short-term memory from distilled long-term facts and enforced a strict recall budget.

Outcome

Maintained personalization without degrading answer quality.

Challenge

Reducing cost and latency for repeated queries.

Solution

Combined exact cache keys with semantic similarity matching scoped by user, route, and context hash.

Outcome

Improved repeat-query efficiency while staying personalized.

Results

Metrics and outcomes presented for quick technical review

The emphasis here is signal, not decoration: key numbers, verifiable outcomes, and the context needed to interpret them responsibly.

Execution Graph

7 nodes

Recall through memory write-back in a reusable LangGraph flow.

Route Types

Direct, RAG, memory, web search, and reject.

Recall Budget

500 tokens

Memory context stays constrained and intentional.

Memory Policy

30 / 90d

Short-term turns plus 90-day long-term fact retention.

Key Results

Built a guarded conversational layer over structured MindMirror prediction outputs.
Implemented a 7-node LangGraph workflow with routing, memory, cache, retrieval, and write-back stages.
Enabled user-scoped explanations through Supabase-backed retrieval and hybrid memory.
Improved repeat-query efficiency with cache reuse and weak-context correction paths.

Research + Business Impact

Product value

Turns raw behavioral inference tables into an explainable conversational experience that feels more useful to end users.

Engineering value

Shows a mature AI system design mindset: scoped behavior, explicit routing, memory policy, observability, and fallback control.