xLSTM-metal: Instructions file for Codex

Agent and Developer Guide

This repo implements xLSTM for Apple Silicon using MLX with Metal Accelerated Dispatch (MAD). These guidelines ensure production-safe development.

Quick Reference

Primary Entry Point: generate.py - Production runner using MLX backend
Core Implementation: xlstm_metal/ - MAD wiring, blocks, and inference
Tests: run_pytest.py - Test suite runner
Documentation: docs/ - Technical documentation by component

CLAUDE Guidance (Read Me First)

This repo runs on Apple Silicon with MLX-first compiled backends. These rules are strict so your help stays production-safe and useful.

Zero-Mock Policy (Production Code)

• Don’t add mocks, stubs, or fake implementations to production paths. Use real implementations or leave TODOs in comments with precise next steps.
• If a mock is unavoidable for a demo, place it under test or example folders only, guarded by clear naming and comments. Never wire a mock into default execution.

Always Reuse Before Rebuilding

• Before implementing anything, search the repo for existing code:
  • rg -n "symbol|filename|keyword" to locate reuse targets.
  • Scan xlstm_metal/, scripts/, and docs/ for prior art and conventions.
• Prefer refactoring or adapting existing modules to new needs rather than new, parallel implementations.
• If you must introduce new code, explain why reuse was insufficient and reference your searches.

Lead With Vulnerability

• Be explicit about what you don’t know or what isn’t working yet.
• State assumptions and risks up front. Offer a short plan with checkpoints.
• After changes, verify and report limits (“what this didn’t solve”).

Respect the Shell and Filesystem

• Use OS tools for file ops; avoid dumping large files into the terminal:
  • Copy/rename: cp, mv (not read‑and‑reprint).
  • Search: rg (ripgrep) for speed and focus.
  • Inspect selectively: sed -n '1,200p' <file> (chunked views only).
• Don’t stream giant artifacts or model weights to stdout. If you need to show something, quote only the relevant lines.