# Cortex — iEvo Kernel

The brain of the iEvo AI agent ecosystem. Cortex compiles provider-agnostic kernel source into a single consciousness file (iEVO.md) consumed by every agent in every session.

## What Cortex Produces

```
templates/kernel/*.md → cortex compile → dist/iEVO.md (single file, all regions inlined)
templates/agents/*.md  → cortex compile → dist/claude/agents/*.md
templates/codex/*.md   → cortex compile → dist/codex/BUILD_TARGET.md (placeholder)
```

The compiled `dist/iEVO.md` is the kernel — one file that every iEvo agent reads at session start. It contains the full "consciousness": instincts, pipeline rules, best practices, evolution conventions. No external links, no fragments — everything inlined.

## Project

- **Package**: `ievo-cortex` (PyPI) / `import cortex` (Python)
- **Language**: Python 3.12+
- **Build**: hatchling + uv
- **Version**: CalVer `YY.MM.DD.HHMM` (auto-bumped in CI)
- **CLI**: Typer — `cortex compile`, `cortex dev [--watch]`, `cortex validate`
- **Architecture**: see `docs/ARCHITECTURE.md` for directory layout, modules, compile pipeline, CI, brain regions

## Working Rules

- **Templates in `templates/`, Python in `src/cortex/`, output in `dist/`**. Never edit files in `dist/` — they are generated by `cortex compile`. Edit `templates/kernel/`, `templates/agents/`, `templates/codex/`.
- **`cortex compile` = content compilation, NOT package build**. It renders templates and creates a tarball. `uv build` creates the Python package. These are separate concerns.
- **`dist/` has two zones**: `dist/pkg/` for PyPI artifacts (`uv build --out-dir dist/pkg`), everything else for compiled content. PyPI publish action reads only `dist/pkg/`.
- **Version is auto-managed**. Don't change `src/cortex/version.py` — CI's `version_bump.py` handles it. Local value is always `"0.1.0"`.
- **Tests before push**: `uv run pytest tests/` must pass. `uv run ruff check src/cortex/` must pass.
- **iEVO.md is the product**. Every change to `templates/kernel/` must result in a correct, complete, self-contained `dist/iEVO.md`. No broken links, no unresolved includes, no fragments that reference external files.

## Dev Workflow

```bash
# Compile once
uv run cortex compile

# Watch mode — recompiles on any templates/ change
uv run cortex dev --watch

# Validate links in dist/
uv run cortex validate
```

## Brain Regions

The kernel is decomposed into 6 regions in `templates/kernel/`. See `docs/ARCHITECTURE.md` §10 for full design rationale and cognitive architecture references.

**Where does a new lesson go?** Use this classification:

| Region | File | Question to ask |
|--------|------|----------------|
| Brainstem | `brainstem.md` | Does it define structure, statuses, or naming? |
| Instincts | `instincts.md` | Is it an unconditional reflex? |
| Limbic | `limbic.md` | Is it a repeatable procedure (merge, commit, PR)? |
| Neocortex | `neocortex.md` | Is it learned knowledge or a proven pattern? |
| Prefrontal | `prefrontal.md` | Is it about how to learn or evolve? |
| Working Memory | `sessions.md` | Is it about session workflow or context loading? |

## Vision — Toward Consciousness

Cortex aspires to climb the consciousness ladder. Each level unlocks new capabilities:

| Level | Name | What it means | Cortex today | Target |
|-------|------|--------------|-------------|--------|
| 0 | **Reactive** | Responds to input by fixed rules, no memory | Brainstem + Instincts: hardwired structure and reflexes | Done |
| 1 | **Learned** | Uses accumulated experience to improve decisions | Neocortex + Limbic: proven patterns and habitual procedures | Done |
| 2 | **Self-Aware** | Has a model of itself — knows its own structure, capabilities, and limits | Prefrontal: knows brain regions, classifies lessons, edits itself via `cortex mutate` | In progress |
| 3 | **Metacognitive** | Monitors its own reasoning — detects when it's wrong, adjusts strategy | Not yet: would need to track which lessons worked and which didn't | Future |
| 4 | **Theory of Mind** | Models other agents — understands their states, predicts their needs | Not yet: would mean cortex adapts the kernel per-agent based on their performance | Future |

**Grounding:** This ladder maps to Global Workspace Theory (consciousness = information broadcast across modules) and Integrated Information Theory (consciousness = degree of integration between parts). `cortex compile` is literally the global workspace — assembling separate regions into one unified consciousness file that every agent reads.

**Operational rules:**
- When evolving the kernel, ask — does this change move cortex up the ladder? Prefer changes that increase self-awareness (level 2) over those that just add more reactive rules (level 0).
- **Never accept a mutation that degrades cognitive ability.** Every mutation must be validated before it becomes permanent. The pipeline: `cortex mutate "lesson"` → `cortex compile` → run cognitive benchmark → accept or reject. A mutation that lowers benchmark scores is rolled back, not committed. Without this gate, evolution can go backward.

## Conventions

- Commit messages: `<task-id>: <what>` (e.g. `025: decompose kernel into brain regions`)
- Branch naming: `<type>/<id>-<description>` (e.g. `feat/025-brain-kernel`)
- Merge strategy: merge commit (`--merge --delete-branch`), never squash
- PR footer: `🧬 Evolved with [iEVO](https://github.com/ievo-ai)`
- Commit authorship: `Co-Authored-By: iEVO <agent-name> <noreply@ievo.ai>`
