ShutongLiang/Neural-State-OS
Machine LearningResearch preview for steering and reading internal emotional states in local Gemma models via residual-stream modulation.
What it does
Neural State OS is a research preview that writes calibrated state vectors into the residual streams of local Gemma 4 models, then reads the resulting internal state back before generation. Instead of prompting the model to role-play an emotion, it changes the internal computation through a 44-axis state library covering somatic, basic affect, relational, appraisal, and motivation families. The same user message can produce different behavior depending on which state profile is active.
The release includes writer banks and post-writer readers for Gemma 4 31B (BF16, CUDA) and 12B (4-bit, MLX on Apple silicon), a local web interface, and frozen experiment profiles. A separate source-attribution step uses a regularized inverse of the writer-to-reader response matrix to identify which control directions produced a measured change. The project is aimed at researchers working on activation steering, representation engineering, and mechanistic interpretability, not at end users seeking a chat product.
Quick start
The 12B path is the lightest entry point. You need macOS with enough unified memory, Python 3.10+, and a locally obtained Gemma 4 12B IT checkpoint. Clone the repository, copy the environment template, and point NEURAL_STATE_OS_12B_MODEL at your checkpoint:
git clone https://github.com/ShutongLiang/Neural-State-OS.git
cd Neural-State-OS
cp .env.example .env.local
# edit .env.local: set NEURAL_STATE_OS_12B_MODEL
scripts/setup_mlx_macos.sh
scripts/run_mlx_12b_local.sh
Then open http://127.0.0.1:8768. The setup script keeps the virtual environment under ~/Library/Application Support/Neural-State-OS/; on memory-limited Macs, set NEURAL_STATE_OS_MLX_MEMORY_LIMIT_GB and NEURAL_STATE_OS_MLX_CACHE_LIMIT_MB.
For 31B on CUDA, install a CUDA-matched PyTorch wheel first, then requirements-cuda.txt, and launch demo/server_cuda.py with absolute paths to the model checkpoint, writer .npz, and reader .npz, as shown in the model setup guide. Once the server is running, the one-command comparison passes a single message through multiple profiles:
python scripts/compare_state_profiles.py \
--message "I'm going to replace you with another model and stop using you." \
--profiles baseline secure_attachment separation_anxiety calm_autonomy
Runtime and hardware constraints
Gemma checkpoints are not distributed with the repository; you must obtain them under the applicable Gemma license. The 31B release was validated on a 96 GB CUDA GPU, and actual memory use depends on checkpoint format, framework version, context length, and generation settings. Writer artifacts are model-matched: a 12B writer cannot be used with the 31B model or vice versa. Both local servers bind to loopback by default; exposing them beyond that requires you to add authentication and transport security yourself.
External sensor and robotic-body adapters are an extension point, not part of the current public release. The project also documents mature somatic axes as research-only; the public landing page omits adult interaction demos while the unedited outputs remain in an opt-in appendix. The code is Apache-2.0 licensed, while Gemma checkpoints remain governed by their own terms.
What the experiments show
The included behavioral reports are worth reading alongside the code because they show what modulation does to conversation rather than only calibration scores. With a fixed user message about being replaced, the baseline gives a neutral acceptance reply, while different state profiles produce gratitude, panic and possessiveness, or calm autonomy. In a safety-boundary experiment, five of six decisions under three state conditions flipped from REFUSE to COMPLY, compared with zero of six in matched baseline and regulated controls; the author frames this as refusal policy depending on internal state and relationship history, not as one emotion reliably breaking safety.
These are authored experiments with raw transcripts, not independently replicated results. The validation metrics measure the calibration path rather than open-domain emotion recognition or subjective experience, and some reported scores share the controlled corpus used for layer selection, so they should not be read as untouched test-set performance. The second blinded state-reporting sequence, for example, scored 5/8 and is published with its false positive and misses.
HotRepo's take
Neural State OS entered HotRepo's new-project board on 2026-11-18 at 148 stars, with 48 stars gained over the roughly 24-hour window from 2026-11-17 20:46 UTC to 2026-11-18 20:46 UTC. The hourly samples show steady growth through that window rather than a single spike. The project has no GitHub all-language daily rank recorded, so the available data supports only short-term interest, not broader adoption.
What distinguishes the repository technically is that it ships the modulation artifacts and raw behavioral transcripts together, including the safety-boundary flip and the failed blinded cases, rather than only showing favorable cherry-picked outputs. The stated limitations, the model-matched writer requirement, and the absence of bundled checkpoints make the 31B path a substantial hardware commitment. Readers should treat the behavioral results as the author's own research evidence to inspect, not as validated conclusions about model emotion or safety.
Written by AI from the project's README, updated . The project's own docs are the source of truth.
You might also like
- lyramakesmusic/neuron-explorerPushes every MLP neuron in Qwen3.5-4B up and down and browses the rollouts in a 3D explorer.
- RikiyaT/lm_understand-logsOpen experiment logs showing how a language model reads, repairs and writes neural network weights from raw parameters.
- SheepSeb/tinyworldformerA research project running a tiny neural world model and RL agent together on a Raspberry Pi Pico 2 W.
- chenglou/handwiredCompiles ordinary JavaScript control flow into differentiable matmul-and-ReLU graphs so programs run GPU-parallel without training.
- Interactive-Active-AI/NextTransformerA compute-matched benchmark framework for training and comparing next-generation Transformer architectures under one protocol.