# Cortex 🧠

Intelligence layer for [OpenClaw](https://github.com/moltbot/moltbot). The higher-order thinking above the nervous system.

## Modules

| Module | Command | What it does |
|--------|---------|-------------|
| **Triage** | `cortex triage score "text"` | Priority scoring (urgency × importance × effort × readiness) |
| **Health Scanner** | `cortex health [--json]` | Proactive system health checks |
| **Feedback Loop** | `cortex feedback --since 6h` | Extract lessons from session transcripts |
| **Memory Hygiene** | `cortex hygiene stats\|stale\|duplicates\|orphans\|archive` | Keep memory clean |
| **Roadmap** | `cortex roadmap list\|add\|overdue\|report` | Task tracking with deadlines & dependencies |
| **Validate** | `cortex validate --transcript <path>` | Sub-agent output validation |
| **Enhanced Search** | `cortex search "query"` | Multi-strategy memory search |
| **Auto Handoff** | `cortex handoff <file>` | Generate session handoff documents |

## Install

```bash
pip install -e .
```

## Configuration

Cortex uses environment variables for path configuration. All paths have sensible defaults (`~/.cortex/`).

| Variable | Default | Description |
|----------|---------|-------------|
| `CORTEX_HOME` | `~/.cortex` | Base directory |
| `CORTEX_MEMORY_DIR` | `$CORTEX_HOME/memory` | Memory files |
| `CORTEX_CONFIG` | `$CORTEX_HOME/config.json` | Config file |
| `CORTEX_GROWTH_LOG` | `$CORTEX_MEMORY_DIR/growth-log.md` | Feedback loop output |
| `CORTEX_ROADMAP` | `$CORTEX_MEMORY_DIR/roadmap.json` | Roadmap data |

Optional `config.json` for customization:
```json
{
  "permanent_files": ["MEMORY.md", "WORKING.md", "README.md"],
  "sessions_dir": "~/.openclaw/agents/main/sessions"
}
```

## Docker

```bash
docker build -t cortex .
docker run cortex triage score "production down"
```

## Tests

```bash
python -m pytest tests/ -v
```

## Architecture

Cortex is a standalone Python package that OpenClaw calls via CLI. No tight coupling, no plugin system — just clean Unix-style commands.

```
OpenClaw (Node/TS)
    │
    ├── cortex triage score "..."    ← CLI calls
    ├── cortex health --json
    ├── cortex feedback --since 6h
    └── cortex hygiene stats
         │
         └── Cortex (Python)
              ├── triage.py
              ├── health_scanner.py
              ├── feedback_loop.py
              ├── memory_hygiene.py
              ├── roadmap.py
              ├── validate_output.py
              ├── enhanced_search.py
              └── auto_handoff.py
```

## License

MIT