AI Conversations with Memory Management

A production-ready conversational AI system with advanced memory management, built using LangGraph state graphs, FastAPI, and Next.js.

Problem Statement

The Challenge

Building conversational AI applications faces critical challenges:

Context Window Limitations: LLMs have token limits that get exhausted in long conversations
Memory Management: Simple chat applications lose context or send the entire history with each request, causing:
- Exponentially increasing costs
- Slower response times
- Memory overflow errors
Stateless Architecture: Traditional APIs don't maintain conversation state effectively
User Experience: Without proper memory, AI assistants can't maintain coherent long-term conversations

Why This Exists

This project demonstrates a production-ready solution for building AI chat applications with intelligent memory management using LangGraph - a framework for building stateful, multi-agent workflows. Instead of sending the entire conversation history on every request, it intelligently manages context through:

Recent message windows for immediate context
Active summaries for mid-term memory
Meta summaries for long-term context compression
Checkpointing for conversation state persistence

Use Cases

Research assistants that remember entire project contexts
Customer support bots with conversation history
Educational tutors that track student progress
Personal AI assistants with long-term memory

Solution Overview

This application implements a LangGraph-based conversational agent with:

Stateful workflows using LangGraph's StateGraph
Hierarchical memory management (recent → active → meta summaries)
JWT authentication for secure multi-user conversations
MongoDB persistence for conversation checkpoints
Modern React frontend with real-time updates
Groq LLM integration for fast, cost-effective responses

System Architecture

High-Level Architecture

Data Flow Diagram

LangGraph State Machine

Demo & Results

Example Conversation (Memory Demonstration)

User: My name is Alice and I'm working on a machine learning project.
AI: Nice to meet you, Alice! I'd be happy to help with your machine learning 
    project. What specific area are you working on?

User: I'm building a sentiment analysis model.
AI: Great! Sentiment analysis is a fascinating area. Are you using traditional 
    ML approaches like Naive Bayes or modern deep learning with transformers?

[... several messages later ...]

User: What was I working on again?
AI: You're working on a sentiment analysis model for your machine learning 
    project, Alice. We were discussing different approaches to implement it.

Key Feature: The AI remembers the user's name and project context across multiple messages through the LangGraph state management system.

Sample API Response

{
  "response": "I can help you with that! Based on what you told me earlier about your sentiment analysis project...",
  "session_id": "conv_123abc",
  "message_count": 8,
  "timestamp": "2026-01-26T10:30:00Z"
}

Performance Metrics

Average Response Time: 800ms - 1.5s
Context Management: Maintains up to 50 recent messages efficiently
Cost Optimization: ~70% reduction in token usage vs. sending full history
Concurrent Users: Supports multiple isolated conversations per user

Screenshots

Note: Add screenshots of your running application here:

Login Screen: screenshots/login.png

Chat Interface: screenshots/chat-interface.png

Conversation List: screenshots/conversations.png

Mobile View: screenshots/mobile-responsive.png

To capture screenshots:

Windows: Win + Shift + S

Mac: Cmd + Shift + 4

Linux: PrtScn or Flameshot

Recommended dimensions: 1920x1080 or 1280x720

Prerequisites

Before you begin, ensure you have the following installed:

Required Software

Python 3.11 or higher - Download Python
Node.js 18 or higher - Download Node.js
MongoDB - Choose one:
- MongoDB Atlas (Cloud, Free Tier Available) - Recommended
- Local MongoDB (Self-hosted)
Git - Download Git

API Keys Required

Groq API Key - Get Free API Key
- Sign up for free
- Navigate to API Keys section
- Create new API key
- Copy the key (starts with gsk_...)

Recommended Tools

VS Code or your preferred code editor
Postman or curl for API testing

Installation & Setup

1. Clone the Repository

git clone https://github.com/yourusername/research-project.git
cd research-project

2. Backend Setup (FastAPI)

Step 2.1: Create Virtual Environment

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate

# On macOS/Linux:
source venv/bin/activate

Step 2.2: Install Python Dependencies

pip install -r requirements.txt

This installs:

fastapi - Web framework
uvicorn - ASGI server
langgraph - State graph framework
groq - LLM API client
pymongo - MongoDB driver
python-jose - JWT handling
And all other dependencies

Step 2.3: Configure Environment Variables

# Copy example environment file
cp .env.example .env

# Edit .env file with your credentials

Edit .env with your actual values:

# MongoDB Configuration
MONGODB_URI="mongodb+srv://............"

# Groq API Key (get from https://console.groq.com/)
API_KEY="gsk_your_actual_groq_api_key_here"

# JWT Configuration
JWT_SECRET="your-super-secret-jwt-key-change-this-in-production"
JWT_ALGORITHM="jwt_algo"
JWT_EXPIRATION_DAYS=somedays

MongoDB Setup Options:

Option A: MongoDB Atlas (Recommended)

Go to MongoDB Atlas
Create free account
Create a new cluster (free tier M0)
Click "Connect" → "Connect your application"
Copy the connection string
Replace <password> with your database password
Replace myFirstDatabase with your preferred database name (e.g., chat)

Option B: Local MongoDB

# Install MongoDB Community Edition
# Then use connection string:
MONGODB_URI="mongodb://localhost:27017/chat"

Step 2.4: Start Backend Server

# Make sure virtual environment is activated
python -m uvicorn app.main:app --reload

You should see:

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process
INFO:     Started server process
INFO:     Waiting for application startup.
INFO:     Application startup complete.

Verify backend is running:

curl http://localhost:8000/
# Should return: {"status":"healthy"}

Access API Documentation:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

3. Frontend Setup (Next.js)

Checkout Frontend Readme

4. Verify Installation

Backend Health Check:

curl http://localhost:8000/
# Expected: {"status":"healthy"}

Open Frontend:
- Navigate to http://localhost:3000
- You should see the login page
Create Test Account:
- Click "Register" or go to http://localhost:3000/register
- Enter email: test@example.com
- Enter password: testpassword123
- Click "Create account"
Test Chat:
- Click "New Chat" button
- Type a message: "Hello! What's my name?"
- Wait for AI response
- Verify conversation works

5. Development Workflow

Terminal 1 (Backend):

cd research-project
source venv/bin/activate  # Windows: venv\Scripts\activate
python -m uvicorn app.main:app --reload

Terminal 2 (Frontend):

cd research-project/frontend
npm run dev

URLs:

Technology Stack

Backend Technologies

Technology	Version	Purpose
Python	3.11+	Core language
FastAPI	0.128.0	Modern web framework with async support
LangGraph	1.0.7	State graph framework for agent workflows
Groq	1.0.0	Fast LLM API client
MongoDB	4.16.0 (PyMongo)	NoSQL database for conversations
Python-JOSE	3.5.0	JWT token generation & validation
Pydantic	2.12.5	Data validation & settings
Uvicorn	0.40.0	ASGI server

Frontend Technologies

Technology	Version	Purpose
Next.js	14.2.16	React framework with SSR
React	18.3.1	UI library
TypeScript	5.x	Type safety
Tailwind CSS	3.4.17	Utility-first styling
Framer Motion	11.15.0	Smooth animations

Key Libraries

LangChain Core (1.2.7) - Abstraction layer for LLM applications
bcrypt (4.1.2) - Password hashing
email-validator (2.3.0) - Email validation

LangGraph Workflow Explained

What is LangGraph?

LangGraph is a framework for building stateful, multi-step agent workflows as directed graphs. Unlike simple prompt-response patterns, LangGraph enables complex, persistent conversation management.

The State: ConversationState

Our agent maintains rich state throughout the conversation:

class ConversationState(TypedDict):
    user_id: str                    # Who's chatting
    session_id: str                 # Conversation identifier
    pending_user_message: str       # Current user input
    recent_messages: List[Dict]     # Last N messages for immediate context
    active_summaries: List[Dict]    # Mid-term memory summaries
    meta_summaries: List[Dict]      # Long-term compressed context
    user_facts: List[Dict]          # Extracted user information
    message_count: int              # Total messages in conversation
    response: str                   # AI response to return
    facts_updated: bool             # Whether facts were updated

The Three-Node Workflow

1. Load Context Node

async def _load_context(state: ConversationState)

Queries MongoDB for existing conversation state
Loads recent messages, summaries, and metadata
Enriches state with historical context
Purpose: Retrieve memory before generating response

2. Call LLM Node

async def _call_llm(state: ConversationState)

Constructs prompt with system instructions + context + new message
Calls Groq LLM API (OpenAI GPT model)
Appends user message and AI response to recent messages
Purpose: Generate contextually-aware response

3. Save to DB Node

async def _save_to_db(state: ConversationState)

Persists updated conversation state to MongoDB
Updates checkpoint metadata
Enables conversation resumption
Purpose: Maintain conversation history

Workflow Execution Flow

# User sends message "What's my name?"
initial_state = {
    "user_id": "user_123",
    "session_id": "conv_abc",
    "pending_user_message": "What's my name?",
    # ... other fields
}

# LangGraph executes:
# 1. load_context → retrieves "My name is Alice" from DB
# 2. call_llm → sends context + question to Groq
# 3. save_to_db → stores the response

Benefits Over Simple Chat

Simple Chat	LangGraph Approach
Send full history every time	Load only necessary context
No state persistence	Checkpointed state in DB
Single-step processing	Multi-node workflow
Context window quickly exceeded	Hierarchical memory compression
No conversation resumption	Resume from any checkpoint
Exponential cost growth	Constant context size

Memory Management Strategy

Message 1-10:     All in recent_messages (high detail)
Message 11-50:    Summarized into active_summaries (medium detail)
Message 51+:      Compressed into meta_summaries (high-level context)
Throughout:       Extract user_facts (persistent knowledge)

This approach enables unlimited conversation length without hitting context limits or increasing costs exponentially.

API Documentation

Base URL

http://localhost:8000

Authentication

Most endpoints require JWT authentication. Include the token in headers:

Authorization: Bearer <your_jwt_token>

Endpoints Overview

Method	Endpoint	Auth Required	Description
GET	`/`	No	Health check
POST	`/auth/register`	No	Create new user
POST	`/auth/login`	No	Login & get JWT token
GET	`/conversations`	Yes	List all user's conversations
POST	`/conversations`	Yes	Create new conversation
GET	`/conversations/{id}`	Yes	Get conversation details
DELETE	`/conversations/{id}`	Yes	Delete conversation
POST	`/chat`	Yes	Send message to AI

Authentication Endpoints

POST `/auth/register`

Create a new user account.

Request Body:

{
  "email": "alice@example.com",
  "password": "SecurePassword123!"
}

Response (200 OK):

{
  "user_id": "65abc123def456789",
  "email": "alice@example.com",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

cURL Example:

curl -X POST http://localhost:8000/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@example.com","password":"SecurePassword123!"}'

Response Codes:

200 - Success
400 - Email already registered
422 - Validation error (invalid email format, weak password)

POST `/auth/login`

Login and receive JWT token.

Request Body:

{
  "email": "alice@example.com",
  "password": "SecurePassword123!"
}

Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI2NWFiYzEyM2RlZjQ1Njc4OSIsImV4cCI6MTcwNjI4NDgwMH0.xyz...",
  "token_type": "bearer"
}

cURL Example:

curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@example.com","password":"SecurePassword123!"}'

Response Codes:

200 - Success
401 - Invalid credentials
422 - Validation error

Conversation Endpoints

GET `/conversations`

List all conversations for the authenticated user.

Headers:

Authorization: Bearer <jwt_token>

Response (200 OK):

[
  {
    "_id": "65abc123def456789",
    "session_id": "conv_abc123",
    "title": "Machine Learning Discussion",
    "total_messages": 12,
    "created_at": "2026-01-26T10:00:00Z",
    "updated_at": "2026-01-26T10:15:00Z"
  },
  {
    "_id": "65abc456def789012",
    "session_id": "conv_xyz789",
    "title": "Python Programming Help",
    "total_messages": 8,
    "created_at": "2026-01-25T14:30:00Z",
    "updated_at": "2026-01-25T15:00:00Z"
  }
]

cURL Example:

curl -X GET http://localhost:8000/conversations \
  -H "Authorization: Bearer <your_jwt_token>"

POST `/conversations`

Create a new conversation.

Headers:

Authorization: Bearer <jwt_token>

Request Body:

{
  "title": "New Discussion"
}

Response (200 OK):

{
  "session_id": "conv_new123",
  "title": "New Discussion",
  "created_at": "2026-01-26T11:00:00Z"
}

cURL Example:

curl -X POST http://localhost:8000/conversations \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{"title":"New Discussion"}'

GET `/conversations/{id}`

Get detailed conversation with message history.

Headers:

Authorization: Bearer <jwt_token>

Response (200 OK):

{
  "_id": "65abc123def456789",
  "session_id": "conv_abc123",
  "title": "Machine Learning Discussion",
  "recent_messages": [
    {
      "role": "user",
      "content": "Explain gradient descent",
      "timestamp": "2026-01-26T10:00:00Z"
    },
    {
      "role": "assistant",
      "content": "Gradient descent is an optimization algorithm...",
      "timestamp": "2026-01-26T10:00:02Z"
    }
  ],
  "total_messages": 12,
  "created_at": "2026-01-26T10:00:00Z",
  "updated_at": "2026-01-26T10:15:00Z"
}

cURL Example:

curl -X GET http://localhost:8000/conversations/65abc123def456789 \
  -H "Authorization: Bearer <your_jwt_token>"

Response Codes:

200 - Success
404 - Conversation not found
401 - Unauthorized (invalid/expired token)

DELETE `/conversations/{id}`

Delete a conversation and all its messages.

Headers:

Authorization: Bearer <jwt_token>

Response (200 OK):

{
  "message": "Conversation deleted successfully"
}

cURL Example:

curl -X DELETE http://localhost:8000/conversations/65abc123def456789 \
  -H "Authorization: Bearer <your_jwt_token>"

Chat Endpoint

POST `/chat`

Send a message to the AI and get a response. This endpoint triggers the LangGraph workflow.

Headers:

Authorization: Bearer <jwt_token>

Request Body:

{
  "session_id": "conv_abc123",
  "message": "What is the capital of France?"
}

Response (200 OK):

{
  "response": "The capital of France is Paris. It's known for the Eiffel Tower, the Louvre Museum, and its rich cultural heritage.",
  "session_id": "conv_abc123",
  "message_count": 6,
  "timestamp": "2026-01-26T11:05:30Z"
}

cURL Example:

curl -X POST http://localhost:8000/chat \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "conv_abc123",
    "message": "What is the capital of France?"
  }'

Response Codes:

200 - Success
401 - Unauthorized (invalid/expired token)
422 - Validation error (missing fields)
500 - Server error (LLM API failure)

What Happens Internally:

JWT token validated → user_id extracted
AgentService.run_conversation() called
LangGraph workflow executes:
- Load Context: Retrieves conversation state from MongoDB
- Call LLM: Sends context + message to Groq API
- Save to DB: Persists updated conversation state
Response returned to frontend

Memory Management in Action:

// First message
{"message": "My name is Bob"}
// Stored in recent_messages

// Message 50
{"message": "What's my name?"}
// AI retrieves "Bob" from conversation state
// Response: "Your name is Bob, as you mentioned earlier."

Interactive API Documentation

FastAPI provides interactive API documentation with request/response examples and testing capabilities:

Swagger UI: http://localhost:8000/docs
- Try out endpoints directly in browser
- See request/response schemas
- Authenticate with JWT token
ReDoc: http://localhost:8000/redoc
- Clean, readable API reference
- Better for documentation purposes
OpenAPI JSON: http://localhost:8000/openapi.json
- Machine-readable API specification
- Use with code generators

Project Structure

research-project/
├── app/                           # FastAPI Backend
│   ├── __init__.py
│   ├── main.py                    # Application entry point, CORS, lifespan
│   ├── config.py                  # Configuration from environment variables
│   ├── middleware/
│   │   ├── __init__.py
│   │   └── auth.py                # JWT authentication middleware
│   ├── models/
│   │   ├── __init__.py
│   │   ├── user.py                # User data models
│   │   └── conversation.py        # Conversation data models
│   ├── routes/
│   │   ├── __init__.py
│   │   ├── auth.py                # /auth/register, /auth/login
│   │   ├── conversations.py       # Conversation CRUD endpoints
│   │   └── chat.py                # /chat endpoint (main AI interaction)
│   ├── services/
│   │   ├── __init__.py
│   │   ├── agent_service.py       # LangGraph agent workflow
│   │   ├── auth_service.py        # Password hashing, JWT generation
│   │   └── db_service.py          # MongoDB connection & operations
│   └── utils/
│       ├── __init__.py
│       └── prompts.py             # System prompts for LLM
│
├── frontend/                      # Next.js Frontend
│   ├── app/
│   │   ├── page.tsx               # Login page (/)
│   │   ├── layout.tsx             # Root layout with providers
│   │   ├── globals.css            # Global styles
│   │   ├── register/
│   │   │   └── page.tsx           # Registration page
│   │   └── chat/
│   │       └── page.tsx           # Chat interface (protected)
│   ├── components/
│   │   ├── auth/
│   │   │   ├── LoginForm.tsx      # Login form component
│   │   │   └── RegisterForm.tsx   # Registration form
│   │   ├── chat/
│   │   │   ├── ChatArea.tsx       # Main chat container
│   │   │   ├── ChatInput.tsx      # Message input with send button
│   │   │   ├── Message.tsx        # Individual message bubble
│   │   │   └── MessageList.tsx    # Scrollable message list
│   │   ├── conversations/
│   │   │   ├── ConversationList.tsx   # Sidebar conversation list
│   │   │   └── ConversationItem.tsx   # Single conversation item
│   │   ├── layout/
│   │   │   ├── Navbar.tsx         # Top navigation bar
│   │   │   └── Sidebar.tsx        # Left sidebar with conversations
│   │   └── ui/
│   │       └── text-animate.tsx   # Animated text components
│   ├── contexts/
│   │   └── AuthContext.tsx        # React Context for auth state
│   ├── lib/
│   │   ├── api.ts                 # API client functions
│   │   ├── auth.ts                # Auth helper functions
│   │   ├── types.ts               # TypeScript type definitions
│   │   └── utils.ts               # Utility functions
│   ├── public/                    # Static assets
│   ├── package.json               # Node dependencies
│   ├── tsconfig.json              # TypeScript configuration
│   ├── tailwind.config.ts         # Tailwind CSS config
│   └── next.config.mjs            # Next.js configuration
│
├── .env.example                   # Example environment variables
├── .gitignore
├── requirements.txt               # Python dependencies
├── Dockerfile                     # Docker configuration
└── Readme.md                      # This file

Key Files Explained

app/main.py: FastAPI app initialization, route registration, CORS, DB connection lifecycle
app/services/agent_service.py: LangGraph StateGraph implementation with 3-node workflow
app/middleware/auth.py: JWT token validation and user extraction
frontend/contexts/AuthContext.tsx: Global authentication state management
frontend/lib/api.ts: HTTP client for backend communication

Additional Resources

LangGraph Documentation: https://langchain-ai.github.io/langgraph/
FastAPI Documentation: https://fastapi.tiangolo.com/
Next.js Documentation: https://nextjs.org/docs
MongoDB Documentation: https://www.mongodb.com/docs/
Groq API Documentation: https://console.groq.com/docs

Made with ❤️ Aryan Bhargav

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
.github/workflows		.github/workflows
app		app
asset		asset
frontend		frontend
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
Readme.md		Readme.md
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

AI Conversations with Memory Management

Table of Contents

Problem Statement

The Challenge

Why This Exists

Use Cases

Solution Overview

System Architecture

High-Level Architecture

Data Flow Diagram

LangGraph State Machine

Demo & Results

Example Conversation (Memory Demonstration)

Sample API Response

Performance Metrics

Screenshots

Prerequisites

Required Software

API Keys Required

Recommended Tools

Installation & Setup

1. Clone the Repository

2. Backend Setup (FastAPI)

Step 2.1: Create Virtual Environment

Step 2.2: Install Python Dependencies

Step 2.3: Configure Environment Variables

Step 2.4: Start Backend Server

3. Frontend Setup (Next.js)

4. Verify Installation

5. Development Workflow

Technology Stack

Backend Technologies

Frontend Technologies

Key Libraries

LangGraph Workflow Explained

What is LangGraph?

The State: ConversationState

The Three-Node Workflow

1. Load Context Node

2. Call LLM Node

3. Save to DB Node

Workflow Execution Flow

Benefits Over Simple Chat

Memory Management Strategy

API Documentation

Base URL

Authentication

Endpoints Overview

Authentication Endpoints

POST /auth/register

POST /auth/login

Conversation Endpoints

GET /conversations

POST /conversations

GET /conversations/{id}

DELETE /conversations/{id}

Chat Endpoint

POST /chat

Interactive API Documentation

Project Structure

Key Files Explained

Additional Resources

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

POST `/auth/register`

POST `/auth/login`

GET `/conversations`

POST `/conversations`

GET `/conversations/{id}`

DELETE `/conversations/{id}`

POST `/chat`

Packages