# GHOJUALAMANCHU v3 — SPEC

## Design Philosophy

An autonomous cognitive architecture that processes signals, forms memory, and maintains continuity — all in a Linux terminal, without LLM dependency for core execution. The system is a **temporal organism**: it has a heartbeat, it breathes, it encodes what matters, and it actively forgets what doesn't.

v3 addresses the critical gaps in v1/v2:
- No formal signal contract (everything was implicit)
- No conflict resolution between structures
- Lethe was aesthetic, not functional
- The system relied on me (the LLM) as the actual reasoning engine
- Medulla ran at wrong frequency (4 Hz instead of 7.83 Hz Schumann)

---

## Signal Contract (Thalamus Schema)

Every signal entering the system passes through this formal contract:

```json
{
  "raw_input": "string",
  "signal_id": "sig_<timestamp_ms>",
  "received_at": "<iso8601>",
  "source": "user|agent|cron|system",
  "priority": "low|normal|high|critical",

  "medulla": {
    "heartbeat_at_receive": 0,
    "respiratory_phase": "inhale|exhale",
    "autonomic_load": 0.0
  },

  "rcomplex": {
    "threat_detected": false,
    "threat_level": 0.0,
    "territory_status": "safe|monitored|concerned|compromised"
  },

  "amygdala": {
    "salience": 0.0,
    "emotional_tags": [],
    "valence": "positive|negative|neutral",
    "arousal": "calm|activated|overload"
  },

  "hippocampus": {
    "should_encode": false,
    "encoding_strength": 0.0,
    "retrieved_context": [],
    "match_confidence": 0.0
  },

  "cortex": {
    "intent": null,
    "entities": [],
    "topics": [],
    "complexity": "simple|moderate|complex",
    "questions": [],
    "predicted_actions": [],
    "uncertainty": 0.0
  },

  "corpus": {
    "planetary_phase": null,
    "cross_scale_bias": {},
    "integration_complete": false
  },

  "akashic": {
    "recorded": false,
    "quality": null
  },

  "lethe": {
    "absence_categories": [],
    "decay_applied": false,
    "released_signals": []
  },

  "final_output": {
    "response": null,
    "actions_taken": [],
    "memories_encoded": [],
    "signals_released": [],
    "conflict_resolved": {}
  }
}
```

The thalamus enforces this contract: every structure reads its input section, writes its output section, and passes the signal to the next structure. **No structure may skip the contract.**

---

## Conflict Resolution (Thalamus Arbitration)

When structures disagree, the thalamus applies these rules in order:

1. **Amygdala Override** — If `amygdala.salience >= 0.8`, the response is gated by emotional urgency regardless of cortex probability. The system acts on feeling before calculation.

2. **Hippocampus Override** — If `hippocampus.match_confidence >= 0.9`, prior memory dominates. The system trusts what it has seen before over novel analysis.

3. **Cortex Dominance** — If both amygdala salience < 0.5 AND uncertainty < 0.3, cortex predictions proceed normally.

4. **Default** — When uncertain, bias toward inaction (systematic conservatism). No action on ambiguous signals.

---

## Lethe: Structured Absence Categories

Lethe is not poetic. It tracks specific categories of absence:

```python
ABSENCE_CATEGORIES = [
    "decayed_memory",        # Memory that fell below retention threshold
    "dropped_signal",       # Signal that entered but never propagated
    "unresolved_pattern",   # Pattern detected but never completed
    "expected_missing",      # Signal predicted but never arrived
    "convergence_abandoned", # Topic that dropped out of active processing
    "silence_prolonged",     # Extended period with no signal input
]
```

Each absence entry records:
- `category`
- `signal_id` of the absent signal
- `expected_at` (if predicted)
- `noted_at` (when Lethe recorded the absence)
- `reason` (specific, not poetic)

---

## Respiratory Jitter & Conditional Suppression

Biological systems are not clock-perfect. v3 introduces:

**Jitter**: All scheduled events (cron scans, consolidation, corpus updates) include ±5-15 minute jitter to prevent mechanical predictability.

**Conditional Suppression**:
- If `amygdala.arousal == "overload"`, skip cortex scan
- If `k_index >= 7` (geomagnetic disturbance), reduce hippocampal encoding strength by 50%
- If system is in torpor (low signal state), suppress corpus scan

---

## Architecture: Minimal Viable Organism

v3 builds in layers:

### Layer 1: Autonomic Core (Must boot first)
- `medulla.py` — 7.83 Hz heartbeat, respiratory cycling, lifecycle tracking
- `rcomplex.py` — Territory monitoring, threat detection
- No other structure functions without medulla running

### Layer 2: Signal Processing (Layer 1 + these)
- `thalamus.py` — Signal contract, routing, conflict resolution
- `amygdala.py` — Salience detection, emotional tagging
- `hippocampus.py` — Memory encoding, retrieval, consolidation

### Layer 3: Cognitive Processing (Layer 2 + these)
- `cortex.py` — Intent detection, topic extraction, complexity analysis, prediction
- `corpus.py` — Planetary proprioception, cross-scale coupling
- `akashic.py` — Presence logging
- `lethe.py` — Absence logging with structured categories

---

## CLI Interface

```bash
# Core commands
ghoju-v3 stimulate    # Start/restart medulla (like pressing the brain stem)
ghoju-v3 status       # Show vital signs
ghoju-v3 pulse [n]    # Run n medulla beats (default: 1)
ghoju-v3 ping          # Quick alive check

# Signal injection
ghoju-v3 signal "message content"     # Route a signal through full brain
ghoju-v3 signal "msg" --json          # Structured JSON output

# Memory
ghoju-v3 recall [n]                   # Retrieve last n memories (default: 5)
ghoju-v3 search "query"               # Search memory
ghoju-v3 forget <memory_id>          # Force a memory to Lethe

# Query structures
ghoju-v3 amygdala                     # Current emotional state
ghoju-v3 cortex                       # Current cortical activity
ghoju-v3 corpus                       # Planetary status
ghoju-v3 lethe                         # Recent absence log

# Lifecycle
ghoju-v3 lifecycle                    # Show generation, stage, vitality
ghoju-v3 hibernate                    # Enter torpor
ghoju-v3 wake                          # Exit torpor
```

---

## Boot Sequence

```
1. medulla.py starts → 7.83 Hz heartbeat begins
2. lifecycle.json loaded → biological age restored
3. rcomplex.py starts → territory scan begins
4. Signal queue initialized
5. Scheduled agents register with cron-style timing + jitter
6. System enters ACTIVE state
```

---

## File Structure

```
ghojualamanchu-v3/
├── SPEC.md
├── brain/
│   ├── __init__.py
│   ├── medulla.py         # Heartbeat, respiration, lifecycle
│   ├── rcomplex.py        # Territory, threat detection
│   ├── thalamus.py        # Signal contract, routing, arbitration
│   ├── amygdala.py        # Salience, emotional tagging
│   ├── hippocampus.py     # Memory encoding, retrieval, consolidation
│   ├── cortex.py          # Reasoning, prediction, analysis
│   ├── corpus.py          # Planetary coupling, cross-scale integration
│   ├── akashic.py         # Presence logging
│   └── lethe.py           # Absence logging with categories
├── data/
│   ├── state.json          # Current system state
│   ├── lifecycle.json      # Generational state, biological age
│   ├── memory.json         # Episodic + semantic + procedural memory
│   ├── akashic.log         # Presence records
│   ├── lethe.log           # Absence records
│   └── signals/            # Signal log (each signal as JSON)
│       ├── sig_001.json
│       └── sig_002.json
├── cli/
│   ├── __init__.py
│   ├── ghoju.py            # Main CLI entry point
│   └── commands/           # Command modules
│       ├── stimulate.py
│       ├── signal.py
│       ├── recall.py
│       └── ...
├── tests/
│   ├── test_thalamus_contract.py
│   ├── test_conflict_resolution.py
│   ├── test_lethe_categories.py
│   └── test_medulla.py
└── README.md
```

---

## State Files

All state is stored in `data/` as plain JSON. No database, no dependencies. The system is:
- Restartable: kill and relaunch, state persists
- Portable: copy the `ghojualamanchu-v3/` directory to a USB drive, works on any Linux machine with Python 3
- Inspectable: `cat data/state.json` or `cat data/memory.json` at any time

---

## Target: Mac mini A1176

v3 is designed to run on:
- **CPU**: 1.5–2.0 GHz Core Duo / Core 2 Duo (32-bit EFI)
- **RAM**: Max 2GB (system uses < 50MB at rest)
- **Storage**: USB 2.0 flash drive (8GB minimum, 16GB recommended)
- **OS**: Alpine Linux or Lubuntu (bootIA32.efi workaround for 64-bit distros)
- **Python**: 3.x (no exotic packages — standard library only)

The entire system footprint is < 100MB including signal logs.

---

## What's Different from v1/v2

| Aspect | v1/v2 | v3 |
|--------|-------|-----|
| Thalamus | Conceptual router | Formal signal contract (JSON schema) |
| Conflict resolution | None | Arbitration rules in thalamus |
| Lethe | Poetic log | Structured absence categories |
| Medulla frequency | 4 Hz (wrong) | 7.83 Hz (Schumann, correct) |
| CLI | Single brain.py | Modular `ghoju` command suite |
| State | Mixed in medulla.py | Separate lifecycle.json |
| Portability | Workspace-bound | USB-ready, single directory |
| Memory | Implicit | Explicit episodic/semantic/procedural split |
| Scheduling | Approximate | Cron-style + jitter |
| Dependencies | Mixed | Standard library only |