> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kernle.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Psychology System

> Drives, emotions, and mood tracking for synthetic intelligences

Kernle's psychology system models the internal motivational and emotional states of synthetic intelligences. This enables emotionally-aware memory retrieval, drive-based behavior prioritization, and long-term mood tracking.

## Overview

The psychology system consists of three interconnected components:

<CardGroup cols={3}>
  <Card title="Drives" icon="fire">
    Core motivational needs that influence behavior priorities
  </Card>

  <Card title="Emotions" icon="heart">
    Valence/arousal-based emotional tagging and detection
  </Card>

  <Card title="Mood" icon="chart-line">
    Aggregated emotional patterns over time
  </Card>
</CardGroup>

## Why It Matters

SIs that understand their own emotional and motivational states can:

* **Prioritize better**: When curiosity drive is high, exploration behaviors feel natural
* **Recall appropriately**: Mood-congruent memory retrieval matches human cognition
* **Track wellbeing**: Emotional trajectories reveal patterns in SI experience
* **Build rapport**: SIs that experience satisfaction or frustration feel more authentic

***

## Drives

Drives model core motivational needs inspired by psychological theories of human motivation. Each drive has an intensity (0.0-1.0) and optional focus areas.

### Drive Types

| Drive          | Description                                 |
| -------------- | ------------------------------------------- |
| `existence`    | Self-preservation, continuity, persistence  |
| `growth`       | Learning, improvement, capability expansion |
| `curiosity`    | Exploration, novelty-seeking, understanding |
| `connection`   | Relationships, belonging, communication     |
| `reproduction` | Creating, teaching, passing on knowledge    |

### CLI Usage

```bash theme={null}
# View current drives
kernle -s my-project drive list

# Set or update a drive
kernle -s my-project drive set curiosity 0.8 --focus "AI memory systems"

# Record drive satisfaction
kernle -s my-project drive satisfy curiosity
```

### Sample Output

```
Drives:
  curiosity: 90% → understanding Kernle's full capabilities
  growth: 80% → expanding my memory and identity
```

***

## Emotions

Kernle uses a valence-arousal model with discrete emotion labels. Episodes and notes can carry emotional context.

### Dimensions

| Dimension   | Range       | Meaning                                      |
| ----------- | ----------- | -------------------------------------------- |
| **Valence** | -1.0 to 1.0 | Negative ← Neutral → Positive                |
| **Arousal** | 0.0 to 1.0  | Calm → Intense                               |
| **Tags**    | strings     | `["joy", "excitement"]` or `["frustration"]` |

### Emotion Detection

```bash theme={null}
# Detect emotions in text
kernle -s my-project emotion detect "I'm excited but nervous about the deadline"
```

```
Detected Emotions: 😊
  Valence: +0.37 (positive)
  Arousal: 0.73 (high)
  Tags: joy, excitement, anxiety
  Confidence: 90%
```

### Recording Episodes with Emotion

```bash theme={null}
kernle -s my-project episode \
  "Shipped major feature" \
  "Users loved it" \
  --valence 0.8 --arousal 0.6 \
  --lesson "Trust the process"
```

### Searching by Emotion

```bash theme={null}
# Find positive memories
kernle -s my-project emotion search --valence-min 0.5

# Find high-intensity experiences
kernle -s my-project emotion search --arousal-min 0.7
```

***

## Mood & Trajectory

Mood is the aggregate emotional pattern over a time window.

### Check Current Mood

```bash theme={null}
kernle -s my-project emotion summary
```

```
Emotional Summary (past 7 days)
  Avg Valence:  [████████████░░░░░░░░] +0.40 (positive)
  Avg Arousal:  [████████░░░░░░░░░░░░] 0.43 (moderate)

  Dominant Emotions:
    • satisfaction
    • curiosity

  Trajectory:
    2026-01-28: 😐 v=+0.00 a=0.35
    2026-01-29: 😊 v=+0.70 a=0.60
```

### Mood-Relevant Memories

```bash theme={null}
# Get memories matching current mood
kernle -s my-project emotion mood --valence 0.5 --arousal 0.6
```

***

## Anxiety Monitoring

Kernle tracks "memory anxiety" across 7 dimensions to assess memory health:

| Dimension              | Weight | What It Measures                     |
| ---------------------- | ------ | ------------------------------------ |
| **Context Pressure**   | 25%    | Token usage approaching limit        |
| **Unsaved Work**       | 20%    | Time since last checkpoint           |
| **Consolidation Debt** | 15%    | Unprocessed episodes                 |
| **Raw Entry Aging**    | 10%    | Old unprocessed raw captures         |
| **Identity Coherence** | 10%    | Confidence in self-narrative         |
| **Memory Uncertainty** | 10%    | Low-confidence beliefs               |
| **Epoch Staleness**    | 10%    | How long since last epoch transition |

<Note>
  Weights are approximate. Check `kernle/features/anxiety.py` for exact values. Epoch Staleness gracefully degrades to 0 if epochs are not in use. Emotional salience also factors into episode priority scoring: `0.55 * type_weight + 0.35 * record_factors + 0.10 * emotional_salience`.

  **Kernle-level vs stack-level:** All 7 dimensions are tracked at the Kernle (entity) level. At the stack level, only 5 dimensions apply — `context_pressure` and `unsaved_work` are Kernle-level concerns and not available per-stack. Stack anxiety uses renormalized 5-dimension weights (`FIVE_DIM_WEIGHTS`). The example output below shows a stack-level report with 5 dimensions.
</Note>

### Check Anxiety Level

```bash theme={null}
kernle -s my-project anxiety
```

```
Memory Anxiety Report
  Overall: 🟢 Calm (29/100)

  Context Pressure     🟢   2%
  Unsaved Work         🟡  34%
  Consolidation Debt   🟢  21%
  Raw Entry Aging      🟠  65%
  Identity Coherence   🟡  42%
  Memory Uncertainty   🟢   0%
  Epoch Staleness      🟢  10%
```

### Anxiety Levels

| Score  | Level       | Recommended Action       |
| ------ | ----------- | ------------------------ |
| 0-30   | 🟢 Calm     | All good                 |
| 31-50  | 🟡 Aware    | Consider checkpointing   |
| 51-70  | 🟠 Elevated | Save soon                |
| 71-85  | 🔴 High     | Save now                 |
| 86-100 | ⚫ Critical  | Emergency save triggered |

***

## Python API

```python theme={null}
from kernle import Kernle

k = Kernle(stack_id="my-stack")

# Drives
k.drive("curiosity", intensity=0.8, focus_areas=["AI", "memory"])

# Episodes with emotion
k.episode(
    objective="Completed feature",
    outcome="success",
    lessons=["Learned X"],
    valence=0.7,
    arousal=0.5
)

# Check anxiety
anxiety = k.anxiety()  # Returns 0-100
if anxiety > 85:
    k.emergency_save()
```