🧠 Cortex Lab

Your Second Brain — Powered by Cutting-Edge AI Research, Running Entirely on Your Hardware

---

What is Cortex Lab?

Cortex Lab is a fully local, privacy-first personal AI that remembers everything you tell it — and reasons over your memories like a true cognitive partner. Unlike standard chatbots that forget after each session, Cortex Lab builds a persistent understanding of your life through conversations, tracks how your beliefs evolve, and answers complex causal questions about your past.

┌─────────────────────────────────────────────────────────────────┐
│  "I am not just a chatbot. I am your second brain."            │
│                                                                 │
│  • I remember every conversation we've had                      │
│  • I understand how your thinking evolved                       │
│  • I can explain WHY you made that decision in March            │
│  • I run entirely on your laptop — no cloud, no API fees        │
│  • I get smarter the more you use me                            │
└─────────────────────────────────────────────────────────────────┘

---

✨ Key Features

---

🏗️ Architecture

Cortex Lab implements a 9-layer Agentic RAG architecture synthesizing 25+ cutting-edge research techniques:

┌──────────────────────────────────────────────────────────────────────┐
│                   CORTEX LAB: 9-LAYER AGENTIC RAG                    │
├──────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  Layer 0  │  INPUT ACQUISITION       Text / Voice (Whisper) / Import │
│  Layer 1  │  MEMORY INGESTION        Classification + Contextual     │
│           │                          & Semantic Chunking             │
│  Layer 2  │  MULTI-REPRESENTATION    FAISS + DuckDB + GraphRAG +     │
│           │  STORAGE                 Propositions + RAPTOR Tree      │
│           │                          + Tiered HNSW/IVF-PQ Vectors   │
│  Layer 3  │  QUERY INTELLIGENCE      Multi-Query + HyDE + Step-Back  │
│           │                          + Adaptive Complexity Routing   │
│  Layer 4  │  AGENT ORCHESTRATION     5 Specialized Agents            │
│  Layer 5  │  HYBRID RETRIEVAL        5-Channel Async Parallel + RRF  │
│           │                          + Cross-Encoder Reranking       │
│  Layer 6  │  POST-RETRIEVAL          CRAG + Failure-Aware Refinement │
│  Layer 7  │  SELF-REFLECTIVE         Self-RAG + FLARE +              │
│           │  GENERATION              Chain-of-Retrieval              │
│  Layer 8  │  MEMORY UPDATE           Belief Evolution + Consolidation│
│  Layer 9  │  WEB INTERFACE           Next.js 15 + TailwindCSS        │
│           │                                                          │
│  Cross    │  PRODUCTION              Multi-Level Caching + Token     │
│  Cutting  │  OPTIMIZATIONS           Efficiency + Self-Improvement   │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

📖 Deep Reference: See RAG-Architecture.md — 3,400+ lines of detailed architecture, code implementations, and research citations for all 25+ techniques.

---

🧪 Techniques

Research Foundations (25+ Techniques from Top-Tier Venues)

📚 Indexing & Storage

Technique	Venue	Purpose
RAPTOR	ICLR 2024	Hierarchical tree-structured indexing (5 levels)
Proposition Retrieval	EMNLP 2024	Atomic fact-level decomposition
GraphRAG	Microsoft 2024	Entity-relationship knowledge graphs
Contextual Chunking	Anthropic 2024	Document-context-aware chunk enrichment
Semantic Chunking	2024	Embedding-similarity boundary detection

🔍 Retrieval Techniques

Technique	Venue	Purpose
BGE Embeddings	MTEB 2024	State-of-the-art dense retrieval (384d)
BM25 + SPLADE	—	Hybrid sparse retrieval with learned expansion
HyDE	ACL 2023	Hypothetical document embeddings
RAG-Fusion	2024	Multi-query generation + RRF fusion
Step-Back Prompting	Google DeepMind 2024	Abstract question for complex reasoning
Cross-Encoder Reranking	—	BGE-reranker-base for precision reranking
Vector Quantization	—	PQ/SQ8/HNSW for memory-efficient ANN

🤖 Agentic Components

Technique	Venue	Purpose
Self-RAG	ICLR 2024	Self-reflective generation with critique loops
CRAG	2024	Corrective retrieval quality evaluation
FLARE	EMNLP 2023	Forward-looking active retrieval mid-generation
Adaptive-RAG	NAACL 2024	Query complexity routing (simple/moderate/complex)
Chain-of-Retrieval	NeurIPS 2024	Step-by-step retrieval-reasoning chains
Failure-Aware Refinement	—	Systematic query refinement by failure type

⚡ Production & Optimization

Technique	Purpose
Multi-Level Caching	Exact + semantic + embedding caching (40%+ hit rate)
Async Pipeline	5-channel parallel retrieval via asyncio (71% latency reduction)
Hot/Cold Tiering	HNSW (recent) → IVF-SQ8 (warm) → IVF-PQ (archival)
Token Efficiency	Adaptive bypass, prompt batching, early termination
RAGChecker	NeurIPS 2024 fine-grained diagnostic evaluation
Retriever Fine-tuning	LoRA on BGE-small with user data (5-15% accuracy gain)
Continuous Self-Improvement	Automated feedback loop: failures → retraining → optimization

🧬 Memory & Evolution

Technique	Purpose
Belief Evolution Tracking	Multi-stage contradiction detection across time
Memory Consolidation	Hierarchical summarization with time decay (10x compression)
Entity Resolution	Coreference resolution + fuzzy matching (RapidFuzz)

---

⚙️ Hardware

Minimum (Target Configuration)

VRAM Budget

---

🚀 Quick Start

Prerequisites

• Python 3.10+
• Node.js 18+
• NVIDIA GPU with CUDA 11.8+ (or CPU-only mode)
• Ollama installed

Installation

# 1. Clone the repository
git clone https://github.com/Suraj-creation/Cortex-Lab.git
cd Cortex-Lab

# 2. Create virtual environment
python -m venv venv
source venv/bin/activate        # Linux/Mac
# venv\Scripts\activate         # Windows

# 3. Install Python dependencies
pip install -r requirements.txt

# 4. Download and quantize model
python setup_model.py --4bit    # 4-bit quantized (recommended for RTX 4000 Ada Generation)

# 5. Start the backend
cd backend
python server.py

# 6. Start the frontend (new terminal)
cd frontend
npm install
npm run dev

# 7. Open in browser → http://localhost:3000

First Memory

Open http://localhost:3000
Type: "Today I learned about retrieval-augmented generation. It's fascinating 
       how you can combine retrieval with generation for better AI responses."
Click "Add Memory"

→ Cortex Lab automatically:
  • Classifies as SEMANTIC memory (SetFit, ~20ms)
  • Extracts entities [RAG, AI] via NER
  • Detects positive emotion (DistilBERT, ~30ms)
  • Creates contextual chunk with session context (Anthropic 2024)
  • Indexes across vector store + knowledge graph + proposition index

First Query

Ask: "What have I learned about AI recently?"

→ Cortex Lab pipeline:
  1. Intent: FACTUAL  │  Complexity: 0.3 (moderate)
  2. Multi-Query: generates 4 variants (RAG-Fusion)
  3. 5-channel async retrieval → RRF fusion → cross-encoder reranking
  4. Self-RAG: generate → critique → verify faithfulness
  5. Response: answer + evidence cards + confidence score + reasoning trace

---

☁️ Deploy on Render

Cortex Lab includes a free-tier-friendly Render Blueprint that provisions frontend + backend without paid resources by default (ephemeral cloud storage).

• Blueprint file: render.yaml
• Full deployment runbook: docs/render-deployment.md
• Render backend dependency set: backend/requirements.render.txt

---

📋 Performance Targets

---

🗂️ Project Structure

Cortex-Lab/
├── README.md                           # This file
├── Vision-Plan.md                      # Vision, roadmap, and implementation plan
├── RAG-Architecture.md                 # 📖 Full technical architecture (3,400+ lines)
│                                       #    → 13 sections with code implementations
│                                       #    → 25+ research techniques with citations
│                                       #    → Architecture diagrams for all 9 layers
│
├── Advanced_RAG_Architecture_Guide.md  # Supplementary research reference
├── RAG-DL-ResearchPage.md             # Deep learning research analysis
├── RAG_Literature_Survey.md           # 100+ paper survey with reading paths
├── QUICK_REFERENCE.md                  # Quick command reference
├── USAGE_GUIDE.sh                      # Usage examples
│
├── setup_model.py                      # Model download & quantization
├── train_model.py                      # LoRA fine-tuning pipeline
├── inference.py                        # Direct model inference
├── requirements.txt                    # Python dependencies
│
├── backend/
│   ├── server.py                       # FastAPI backend (REST + WebSocket)
│   └── requirements.txt               # Backend-specific dependencies
│
└── frontend/
    ├── package.json                    # Node.js dependencies
    ├── next.config.js                  # Next.js 15 configuration
    ├── tailwind.config.js              # TailwindCSS theme
    └── src/
        ├── app/
        │   ├── layout.tsx              # Root layout
        │   ├── page.tsx                # Main page
        │   └── globals.css             # Global styles
        ├── components/
        │   ├── ChatPanel.tsx           # Chat interface with thinking visualization
        │   ├── EmptyState.tsx          # Onboarding empty state
        │   ├── Header.tsx              # Navigation header
        │   ├── MessageBubble.tsx       # Message display with evidence cards
        │   ├── SettingsPanel.tsx       # System configuration UI
        │   └── Sidebar.tsx             # Navigation sidebar
        └── lib/
            ├── api.ts                  # API client utilities
            └── types.ts               # TypeScript type definitions

---

📊 How It Compares

---

📚 Documentation

---

🗺️ Roadmap

📖 Detailed week-by-week tasks in Vision-Plan.md and RAG-Architecture.md § Section 10.

---

🤝 Contributing

Cortex Lab is open-source and welcomes contributions:

• 🐛 Bug Reports — Open issues with detailed reproduction steps
• 💡 Feature Requests — Discuss in GitHub Discussions
• 🔧 Code Contributions — Submit PRs with tests
• 📖 Documentation — Improve guides, examples, and research notes
• 🧪 Research — Implement additional techniques from the literature survey

---

📄 License

MIT License — See LICENSE for details.

---

🙏 Acknowledgments

• DeepSeek Team — For the exceptional R1-1.5B reasoning model
• Research Community — RAPTOR (ICLR 2024), Self-RAG (ICLR 2024), CRAG, FLARE (EMNLP 2023), Adaptive-RAG (NAACL 2024), Chain-of-Retrieval (NeurIPS 2024), RAGChecker (NeurIPS 2024), GraphRAG (Microsoft 2024), Contextual Retrieval (Anthropic 2024), Step-Back Prompting (Google DeepMind 2024)
• HuggingFace — Transformers library and model hosting
• FAISS Team — Efficient vector search with quantization
• DuckDB Team — Blazing-fast analytical database
• Open-Source Community — For countless libraries and tools

---

Built with ❤️ for the future of personal AI
Cortex Lab — Your Second Brain, 25+ Research Techniques, 9-Layer Architecture, Locally Powered 🧠🚀