# Ra Cognitive CPU Bootstrap

This repository is a build-ready bootstrap for the **Ra Cognitive CPU** idea: a compact learned controller that operates over cognitive bytecode, a typed workspace, executable memory, a growing skill graph, and verifier-gated improvement loops.

The first version is deliberately **not** a giant neural training project. It is a verifiable local agent spine that proves the compounding loop before expensive model work begins.

## What this package gives Codex

- A concise `AGENTS.md` with repository rules, commands, non-goals, and done criteria.
- A `PLANS.md` protocol and `execplans/MVP_EXECPLAN.md` so Codex can implement milestone-by-milestone without drifting.
- Python scaffolding for bytecode, workspace, memory, skills, traces, verifiers, dream consolidation, evaluation, and an agent loop.
- Tests that define the first working boundary.
- Stop criteria that tell Codex exactly when to stop instead of expanding into open-ended AGI work.

## Core design improvement

The original concept points toward a large ambition: sparse recurrent Cognitive CPU, cognitive bytecode, executable memory, skill graph, verifier search, and dream mode. This bootstrap converts that into a safer and more buildable sequence:

1. Build the symbolic/typed runtime first.
2. Prove that traces, memory, skill reuse, and verifier results compound.
3. Only then add learned controllers, adapters, and recurrent/sparse neural components.
4. Never accept self-improvement unless a regression suite proves it improves the target metrics.

## Repository layout

```text
.
├── AGENTS.md                         # Codex operating rules
├── PLANS.md                          # ExecPlan protocol
├── STOPPING_CRITERIA.md              # Exact stop gates
├── TASK_BOARD.md                     # Ordered implementation tasks
├── docs/
│   ├── architecture_v0.md
│   ├── implementation_improvements.md
│   ├── evaluation_protocol.md
│   ├── mvp_definition.md
│   ├── safety_and_self_improvement.md
│   └── original_concept_user.md
├── execplans/
│   └── MVP_EXECPLAN.md
├── src/ra_cpu/
│   ├── bytecode.py
│   ├── workspace.py
│   ├── memory.py
│   ├── skills.py
│   ├── trace.py
│   ├── verifiers.py
│   ├── controller.py
│   ├── agent.py
│   ├── dream.py
│   ├── evaluation.py
│   └── cli.py
├── tests/
├── schemas/
├── examples/
└── pyproject.toml
```

## Setup

```bash
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install -e '.[dev]'
python -m pytest
```

The package uses only the Python standard library at runtime. `pytest` is only needed for tests.

## Run a demo

```bash
python -m ra_cpu.cli "Fix a failing Python test and remember the result" --max-steps 8
```

## Definition of done for the first Codex pass

Codex should stop after the MVP runtime passes:

```bash
python -m pytest
python -m ra_cpu.cli "debug a failing pytest import error" --max-steps 8
```

The first pass is complete when:

- All tests pass.
- The CLI creates a task workspace, executes bytecode operations, writes an episode trace, and returns a final answer.
- Memory can retrieve a previous episode.
- Skill graph can add, match, persist, and reload a skill.
- Dream consolidation can propose at least one candidate skill from repeated successful traces.
- No neural model training is introduced yet.

See `STOPPING_CRITERIA.md` for hard gates.
