Kimi K3: Run 2.78T inference in 8.24 GB with portable C99
A C99 Kimi K3 inference engine for local developers that streams a 2.78T model from disk in 8.24 GB.
GitHub FareedKhan-dev/kimi-k3-in-c Updated 2026-11-05 Branch main Stars 10.3K Forks 1.6K
C99 Local inference Kimi K3 CPU and low-memory environments

🧭 Decision Guide

Try it if you

  • You need to run Kimi K3 in a C99 environment without a GPU or BLAS
    The README opening explicitly says “Portable C99: no BLAS, no framework, no GPU.”
  • Your machine has only 8 GB of RAM and you can accept 26.5 s/token
    The README memory ladder lists an ordinary laptop with 8 GB and 26.5 s/token.
  • You need to check whether the inference engine, KV cache, and KDA state match the reference
    The Quick start make test output includes GATE 1, GATE 2, and GATE 3 with exact generated-token matching.

Skip it if you

  • You need low-latency generation on a device with 8 GB RAM and ordinary storage
    The README example on the 8 GB configuration takes 261.5 s for 8 tokens, averaging 32.69 s/token.
  • Your environment cannot store the 1.56 TB checkpoint or sustain repeated disk reads
    The README lists the checkpoint on disk as 1.56 TB and says the 8 GB machine reads the model from disk on every step.
  • You must quantize the trunk to int4 to reduce memory while retaining verified output quality
    The Why the trunk is not quantised section reports up to 65% sampled relative error for int4 and no downstream logit or token comparison.

Requirements

  • Building requires a compiler and OpenMP; the README describes make -j as “Seven C files, a compiler and OpenMP.”
  • Full-model execution requires the 1.56 TB checkpoint; the README's 8.24 GB peak-RSS example uses that checkpoint.
  • The weightless test suite needs no checkpoint, network, or Python; Quick start explicitly says “No checkpoint, no network, no Python.”
  • tools/sim_cache.py requires Python 3.9+ and numpy and reads tests/fixtures/expert_trace.bin.

First step (verbatim from README)

git clone https://github.com/FareedKhan-dev/kimi-k3-in-c.git

Watch out

  • Do not treat raw hits in the cache report as resident hit rate; use TRUE resident hit rate.
    Reading the run report explains that raw hits include experts just fetched by the prefetcher, while TRUE resident hit rate indicates service from RAM.
  • Do not use the upfront memory plan as the actual memory figure; record PEAK RSS.
    The README explicitly says “PEAK RSS for the whole run: 94.74 GB <- quote this, not the plan”.
  • The batch command produces a raw continuation, not a multi-turn chat answer.
    The README says the batch command deliberately asks for a raw continuation and directs chat users to the XTML REPL.

Not stated in the README

  • The omitted Requirements section does not provide the exact operating-system, compiler-version, or OpenMP-version requirements.
  • The omitted Step 4 fetch the checkpoint section does not provide the download command, source, or complete disk-space requirement.
  • The material does not specify which versions or hardware models are supported by the Windows, macOS, and NEON ports.
  • The material does not provide total full-checkpoint runtime, throughput ranges, or systematic benchmarks across disk models.
  • The int4 study measured weight reconstruction error for only 31 attention tensors; it did not measure downstream output quality for the full model.

💡 Deep Analysis

6
No I want to convert the 108.81 GB BF16 trunk to int4 so the model can run on a smaller-memory device. Does the README provide enough evidence to support that change?
For: A quantization researcher planning to convert the 108.81 GB BF16 trunk to int4 to reduce memory usage further

It is not suitable to adopt directly because the README reports substantial int4 reconstruction error and does not establish acceptable downstream output quality.

  • The project deliberately keeps the trunk in BF16. It defines only WF32 and WBF16 weight types and provides no trunk bit-width switch.
  • In a sample of 31 attention tensors, mean relative error was about 1% for int8 and about 17% for int4; the worst rows reached 65%. This is not merely a storage tradeoff.
  • The README cites the model report: experts use quantization-aware-trained MXFP4, while non-expert components remain at higher precision. The trunk has not been shown to tolerate four-bit quantization.
  • The document also states that the study measured weight reconstruction error, not output quality, and performed no int4 logit or token comparison. Therefore it cannot establish that modified inference preserves the original output.

The supported conclusion is that MXFP4 is used for the experts, while int4 quantization of the BF16 trunk remains an unvalidated experiment.

  • README section: Part IV: Measurements / Why the trunk is not quantised
  • README: "This one has exactly two weight types and no knob at all"
  • README: "int4 mean ... 0.17383" and "worst individual rows at int4 reach ... 65 percent relative error"
  • README: "this is weight reconstruction error and not output quality"
Not stated in the README:The README provides no full-model output, perplexity, logit, or task-quality results after int4 trunk conversion.;It does not state whether officially quantization-aware-trained replacement weights for the BF16 trunk exist.
Yes I have only 8 GB of RAM and a regular laptop without a GPU. Can I run the 2.78T Kimi K3 with this project?
For: An individual researcher with 8 GB of RAM, no GPU, and a regular laptop who wants to run the 2.78-trillion-parameter Kimi K3

It is suitable, but it solves “can run” rather than “low-latency interaction.”

  • The README reports an 8 GB peak RSS and explains that routed experts remain on disk and are streamed as needed. The full checkpoint still requires about 1.56 TB of storage.
  • The 8 GB laptop configuration is reported at 26.5 seconds per token. The documented sample reaches 8.24 GB peak RSS and averages 32.69 seconds per token, so inference is feasible but very slow.
  • The implementation uses portable C99 and does not require BLAS, a deep-learning framework, or a GPU. It also includes the model reader, tokenizer, incremental decoding, OpenMP, and SIMD-related paths.

The practical first move is to build and run the weightless tests before downloading the checkpoint, avoiding the immediate cost of preparing 1.56 TB of data.

  • README: "A 2.78-trillion-parameter model. One CPU. 8 GB of RAM."
  • README: "1.56 TB checkpoint on disk" and "8.24 GB peak RSS"
  • README section: Part I: Getting started / Quick start
  • README: "an ordinary laptop 8 GB 26.5 s"
make -j
Not stated in the README:The excerpt does not provide the laptop's exact CPU, sequential storage speed, or available filesystem space, so its actual token latency is unknown.;The excerpt does not specify whether this laptop meets the exact compiler-version and instruction-set requirements.
Yes Before preparing the 1.56 TB checkpoint, I need to verify the C99 engine, KV cache, KDA state, and incremental decoding. Does this project support that validation workflow?
For: An inference test engineer who needs to validate the execution graph and incremental decoding before downloading the 1.56 TB checkpoint

It is suitable because the README explicitly provides a weightless, offline, Python-free validation path, and the tests cover carried inference state rather than only the final string.

  • The Quick start says the process needs no checkpoint, network, or Python, and that make test normally completes in under a minute.
  • The tests include teacher forcing, greedy decoding, and incremental decoding. The README specifically says the incremental gate checks the KV cache and carried KDA state.
  • The tests use a 13-layer small model and PyTorch reference fixtures committed to the repository, covering the tokenizer, safetensors reader, configuration reader, full decoding, and incremental decoding.
  • Checkpoint acquisition and trunk packing come later, so compiler or kernel problems can be separated from the cost of preparing the very large model files.

This is well suited to regression testing of the inference engine, but it does not replace performance and storage validation on the full 2.78T checkpoint.

  • README section: Part I: Getting started / Quick start
  • README: "No checkpoint, no network, no Python"
  • README: "GATE 3 incremental : 20/20 generated tokens match full_ids <- KV cache + carried KDA state"
  • README: "a 13-layer model ... checked against a PyTorch reference"
make -j
Not stated in the README:The excerpt does not list the complete operator boundary covered by the weightless tests or provide a per-platform test matrix.;It does not specify which model-specific errors could still exist between the small oracle and the full Kimi K3 checkpoint.
Yes I am studying KDA, MLA, MoE routing, and MXFP4, and want to inspect the full inference path layer by layer in C99 without BLAS, a deep-learning framework, or a GPU. Is this project suitable?
For: A C/C99 systems engineer studying KDA, MLA, MoE routing, and MXFP4 kernels who wants to reproduce the inference path without BLAS or a framework

It is suitable because the project is explicitly built around an auditable C99 inference path and the model’s structural components.

  • The README describes it as portable C99 with no BLAS, no framework, and no GPU. The whole engine is about 176 KB, making the file-reading, kernel, and state-transfer code relatively direct to inspect.
  • Part II covers safetensors, configuration parsing, tokenization, KDA linear attention, MLA, MoE expert selection, MXFP4 weights, and the LRU expert cache.
  • make test checks teacher forcing, greedy decoding, and incremental decoding against a PyTorch reference using a 13-layer model. That is useful for isolating KV-cache, KDA-state, or incremental-decoding errors rather than checking only final text.
  • Project data also lists AVX2, SIMD, OpenMP, and macOS, Windows, and NEON ports, although platform-specific performance must still be measured separately.
  • README: "Portable C99. No BLAS. No framework. No GPU."
  • README: "176 KB the whole engine"
  • README sections: Part II: How it works / The four reductions / An LRU cache for the experts
  • README section: Part III: Validation / Quick start, including GATE 1, GATE 2, and GATE 3
make test
Not stated in the README:The excerpt does not map every operator to its complete source-file location or define the coverage boundary of each SIMD path.;It does not state whether Windows, macOS, and NEON platforms provide the same numerical consistency as the primary measurement environment.
It depends I have only one CPU machine and local storage, and want multi-turn chat in the official Kimi K3 XTML format rather than raw continuation. Is this project suitable?
For: An offline experimenter who wants official Kimi K3 XTML multi-turn chat using only one CPU machine and local storage

It depends: the functional path is suitable, but the interactive experience depends heavily on RAM, storage, and tolerance for tens of seconds per token.

  • The README distinguishes raw continuation through the batch prompt from official Kimi K3 chat mode. For multi-turn dialogue, it directs users to the XTML REPL rather than treating the batch example as a chat interface.
  • The project includes chat mode, tokenization, KV caching, and incremental decoding, so it covers the local inference path needed for multi-turn state.
  • However, the 8 GB example is about 26.5 seconds per token, and the full checkpoint is about 1.56 TB. Low-memory machines repeatedly read experts and trunk data from disk.
  • The README and project insights position it as an offline, low-level research and reproducibility tool, not a real-time chat or concurrent serving platform.

It is a good fit for validating XTML formatting and multi-turn state. It is not a good fit if the requirement is a fluid chat experience merely because CPU execution is possible.

  • README: "This particular batch command deliberately asks for a raw continuation"
  • README: "use the XTML REPL below when you want answers and multi-turn history"
  • README: "the official Kimi K3 checkpoint is also chat-capable"
  • README: "an ordinary laptop 8 GB 26.5 s"
make test
Not stated in the README:The excerpt does not provide XTML REPL latency or state-memory growth for different context lengths.;It does not state whether multi-turn chat supports concurrent sessions, session persistence, or an external service interface.
Yes I have more than 128 GB of RAM, fast NVMe storage, and a 124-core CPU. Is this project a better fit than the 8 GB configuration if my goal is lower Kimi K3 latency per token?
For: A workstation user with at least 128 GB RAM, a fast NVMe drive, and a 124-core CPU who wants to reduce Kimi K3 latency

It is suitable because this project converts additional RAM into less disk waiting, although it is still not a GPU serving engine.

  • The README’s memory ladder reports 26.5, 24.2, 19.8, and 5.6 seconds per token for 8 GB, 32 GB, 64 GB, and 128 GB+ respectively. At 128 GB+, the model fits in memory and disk waiting disappears.
  • The documentation also describes a 124-core machine where the lower-memory configurations still read the model from disk, showing that CPU core count alone does not remove the storage bottleneck.
  • The same prompt produces byte-identical output across memory budgets, so adding RAM primarily changes speed rather than model output.

This workstation is therefore well suited to reproducible, low-throughput inference experiments. It is not a natural fit for concurrent APIs, real-time chat, or high-throughput production serving, which the project does not target.

  • README: "128 GB+ 5.6 s" and "the model fits entirely in memory, the disk wait is gone"
  • README: "One machine, 124 cores, fast NVMe drive"
  • README: "the output was byte-identical from the smallest machine to the largest"
  • Project insight: the usage limitations state that it is not suited to real-time chat, concurrent requests, or large-scale API serving
make test
Not stated in the README:The excerpt does not give the workstation's exact OpenMP configuration, CPU model, or NVMe throughput, so 5.6 seconds per token is not a guaranteed result.;The README provides no concurrency throughput, queueing behavior, or serving-interface metrics.

✨ Highlights

  • Runs the 2.78T model at 8.24 GB peak RSS
  • Portable C99 with no BLAS, framework, or GPU
  • make test verifies exact matching on the 13-layer reference graph
  • Streams the 1.56 TB checkpoint from disk on each step

🔧 Engineering

  • make -j builds the C99 engine and make test runs weightless tests
  • Supports Kimi K3 batch prompts, incremental generation, and the XTML REPL

⚠️ Risks

  • An 8 GB machine reads from disk each step; the example averages 32.69 s/token
  • Disk I/O accounts for 41%-61% of wall-clock time, so slower storage prolongs generation
  • The trunk is not quantized; sampled int4 relative error reaches 65%

👥 For who?

  • Local developers with 8 GB RAM who can accept 26.5 s/token
  • Implementers needing a C99 solution without BLAS, frameworks, or GPUs
  • Users with 128 GB or more RAM who want to eliminate disk waits