A CPU-only C99 inference engine that runs the 2.78-trillion-parameter Kimi K3 model on as little as 8 GB of RAM by streaming packed MoE experts and trunk layers from disk.

Stars

29

7-day growth

No data

Forks

4

Open issues

0

License

Apache-2.0

Last updated

2026-08-01

AI repository intelligence
FR-AI / ANALYSIS

Why it is worth attention

It reduces a model that naively needs 5.56 TB at bf16 to a measured 8.24 GB peak RSS on one CPU with no GPU, while producing byte-identical output across memory budgets.

Who it is for

  • Engineers exploring CPU-only inference for very large MoE models
  • Researchers validating memory-reduction techniques against exact-output references
  • C developers interested in minimal-dependency inference engines
  • Self-hosters with high-capacity NVMe storage but limited RAM

Use cases

  • Run Kimi K3 base-model text generation on an 8 GB laptop with a packed trunk
  • Replay recorded expert-cache traces to plan memory and performance trade-offs
  • Compare C engine logits elementwise against a PyTorch reference for correctness
  • Develop against partial shard sets with --layers without downloading the full model

Strengths

  • No BLAS, framework, or GPU required; the whole engine is about 176 KB and builds with only libm and OpenMP
  • Uses O_DIRECT streaming and a packed trunk to turn RAM requirements into a tunable dial
  • Comprehensive validation: make test runs oracle and reference gates without needing the checkpoint
  • Measured results are documented, including memory ladders, cache traces, and storage bandwidth

Considerations

  • Very slow: about 32.69 s/token on the laptop preset and 10.69 s/token on the server preset
  • Requires downloading a 1.56 TB checkpoint and having about 1.7 TB free storage; storage bandwidth dominates throughput
  • Targets Linux x86-64 with AVX2+FMA only, and the released model is a base model without a chat template

README quick start

kimi-k3-in-c

A 2.78-trillion-parameter model. One CPU. 8 GB of RAM.

Kimi K3 inference in portable C99.No BLAS. No framework. No GPU.

2.78Tparameters 1.56 TBcheckpoint on disk 8.24 GBpeak RSS, measured 176 KBthe whole engine 0GPUs

$ ./bin/k3 ~/k3model --trunk ~/k3trunk --preset laptop \
           --tok ~/k3model --prompt "The capital of France is" --gen 8 --incremental

--- generated text ---
 Paris.",
+            "The Eiffel
----------------------
8 tokens in 261.5 s, 32.69 s/token average
PEAK RSS for the whole run: 8.24 GB

Slow, and answering correctly, in 8.24 GB, from a checkpoint of 1.56 TB. This is a base model, so what follows " Paris." is a continuation rather than a reply; there is no chat template. Give it more memory and the answer does not change, only the clock:

$ ./bin/k3 ~/k3model --trunk ~/k3trunk --preset server \
           --tok ~/k3model --prompt "def fibonacci(n):" --gen 28 --incremental

--- generated text ---
    if n  [prompt] [memory] [generation] [diagnostics]

`` is the directory holding the .safetensors shards. It is required for any run, but --help, --version and --list-presets work without it:

./bin/k3 --help
./bin/k3 --version
./bin/k3 --list-presets

Prompt options

Exactly one of these is required. Passing none, or more than one, is a usage error (exit 2).

flagargument
--promptTEXTtokenize TEXT and run it. Requires --tok.
--prompt-filePATHtokenize the file's bytes. Requires --tok. Preferred for anything non-ASCII: the shell re-encodes argv, whereas a file is read verbatim
--ids1,2,3token ids directly. No tokenizer is loaded at all, so this works on a machine with no tokenizer files. The reproducible channel the tests use
# text in
./bin/k3 ~/k3model --tok ~/k3model --prompt "The capital of France is" ...

# text in, from a file. Use this for CJK, emoji, accents
printf 'La capitale de la France est' > /tmp/p.txt
./bin/k3 ~/k3model --tok ~/k3model --prompt-file /tmp/p.txt ...

# ids in, ids out, no tokenizer needed
./bin/k3 ~/k3model --ids 1008,10484,318,15383,387 ...

Memory options

flagargumentdefault
--presetNAMEnonelaptop · desktop · workstation · server · max. Sets both budgets below
`--trun

Description

A 2.78-trillion-parameter Kimi K3 running inference on a single CPU in 8.24 GB of RAM. Portable C99: no BLAS, no framework, no GPU.

Related repositories

Similar projects matched by category, topics, and programming language.

makecindy
Featured
makecindy GitHub avatar

cindy

Cindy is an open-source AI agent that runs locally on your machine, integrates multiple AI harnesses and models, and provides memory, skills, and automation to perform real work in your projects and apps.

AI & Machine LearningLarge Language Models
958
uzairansaruzi
Featured
uzairansaruzi GitHub avatar

hermex

Hermex is a native SwiftUI iPhone app that lets you control a self-hosted Hermes AI agent directly from your phone, with no subscriptions, tracking, or third-party relay.

AI & Machine LearningLarge Language Models
941
hahhforest
Featured
hahhforest GitHub avatar

pi-textbook

A hands-on course that walks through building a Pi-style coding agent from scratch across 15 checkpoints, starting from an offline agent trajectory.

AI & Machine LearningLarge Language Models
625