README.md

---
title: "🧠 Limbic-Modulated Reasoning Agent"
emoji: 🧠
colorFrom: purple
colorTo: blue
sdk: gradio
sdk_version: "5.33.0"
app_file: app.py
pinned: false
license: mit
short_description: "LLM with real-time neuro-behavioral state modulation"
tags:
  - psychology
  - neuroscience
  - reasoning
  - limbic-system
  - emotion
  - agents
---

# 🧠 Limbic-Modulated Reasoning Agent

An LLM whose **reasoning behavior adapts in real-time** based on a simulated neuro-behavioral state engine.

## How It Works

```
User Message → Limbic Engine → Modulate LLM Parameters → Generate Response
                  │                    │
                  ├─ Arousal/Valence   ├─ Temperature (fear↓ seeking↑)
                  ├─ 4 Affective       ├─ Top-p (fear=tight, seek=wide)
                  │  Engines           ├─ Behavioral Directive
                  ├─ Hormones          ├─ Active Instincts
                  └─ Psychological     └─ Self-Debug Protocol
                     Lattice
```

### Core Formulas (from [LIMBIC-system-PACKGE](https://github.com/Xover-Official/LIMBIC-system-PACKGE))

| Formula | Source | Effect |
|---------|--------|--------|
| `temp = 1.0 - fear×0.9 + seeking×2.0` | `amygdala.py` | Fear → deterministic, Seeking → creative |
| `hormone[t+1] = h[t] + (baseline - h[t]) × 0.05` | `endocrine.py` | Hormones decay toward homeostasis |
| `fear_mod = 1.0 + cortisol - oxytocin×0.5` | `fear.py` | Cortisol amplifies fear, oxytocin dampens |
| `shadow += 0.1 × suppressed_count` | `lattice.py` | Suppressed drives build up, may "outburst" |

### Agentic Patterns (from [everything-claude-code](https://github.com/affaan-m/everything-claude-code))

- **4-Tier Memory**: Session → Observations → Instincts → State Store
- **Learned Instincts**: Behavioral patterns activated by limbic state
- **4-Phase Self-Debug**: Capture → Diagnose → Fix → Report

## Architecture

| Module | Lines | Purpose |
|--------|-------|---------|
| `limbic_engine.py` | 480 | Full limbic state machine with 14 formulas |
| `memory.py` | 332 | 4-tier memory + instincts + self-debugger |
| `training_plan.py` | 468 | GRPO training recipe + dataset generation |
| `app.py` | 436 | ZeroGPU Gradio interface |

## Try It

Type messages with different emotional tones and watch the Limbic Dashboard react:

- 😰 **Fear**: "I'm terrified of losing my job" → Low temperature, structured response
- 🔍 **Seeking**: "Tell me something fascinating about the brain" → High temperature, creative response
- 💙 **Care**: "How can I help my friend with depression?" → Empathetic, supportive response
- 😢 **Panic**: "My best friend is moving away forever" → Warm, validating response

## Training Plan

3-stage pipeline to fine-tune a base model:
1. **SFT Warm-Up**: 5K synthetic conversations (limbic state → response style)
2. **GRPO Loop Learning**: 2K psychology prompts × 4 reward functions
3. **Active Learning**: Uncertain predictions → human labels → retrain

See `training_plan.py` for the complete recipe and runnable script.