altrux

Research code for continual learning and dream-based consolidation in Mamba2 models.

Layout

altrux/
├── models/          # Model definitions — one folder per model (package + README.md)
│   ├── mamba2_2_7b/              # Active plain 2.7B substrate
│   └── mamba2_2_7b_memory/       # Memory-augmented 2.7B model
├── backend/         # FastAPI inference server
├── frontend/        # React Router v7 chat UI
├── sft/             # Training and continual-learning experiments
└── scripts/         # Standalone helper scripts (e.g. Lambda Cloud instance termination)

Protected paths — the person commits

PROTECTED_PATHS lists the files that decide the science (the LAMA-CKL protocol: dreams, distillation, baselines, scorer, split, runner). Agents may edit them but never commit them: a Claude Code hook refuses any git commit that carries one, the agent reports every protected change under a PROTECTED EDIT heading with each ledger row mapped to file:line, and the person reviews the diff and commits it. See AGENTS.md.

Adding a new model

1. Create a models/my_model/ package — see models/mamba2_2_7b/ for the required interface (MODEL_ID, TOKENIZER_ID, TARGET_LORA_MODULES, USER_OPEN, ASST_OPEN, SPECIAL_TOKENS, Model, load_base, load_inference) and add a README.md following models/CLAUDE.md
2. Set MODEL_NAME=my_model in backend/.env and/or sft/.env
3. Start the backend or run sft — no other code changes needed

The frontend fetches USER_OPEN/ASST_OPEN automatically from GET /config at startup.

Quickstart

# Backend
cd backend && make sync && make dev

# Frontend (separate terminal)
cd frontend && npm install && npm run dev

# Fine-tune
cd sft && make sync && make data && make train

See backend/README.md, frontend/README.md, and sft/README.md for full setup details.

On a rented Lambda Cloud GPU, chain scripts/lambda_terminate.sh after a training run so a crash doesn't leave the instance billing — see scripts/README.md.