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.
C avx2c99cpu-inferencedeep-learningfrom-scratchinference-enginekimi-k3linear-attentionllmllm-inferencemachine-learningmemory-efficientmixture-of-expertsmoemxfp4quantizationsimdsystems-programmingtransformerzero-dependencies
/* k3_state.h - the conversation state file behind --save-state / --load-state.
*
* Everything the engine carries between tokens, on disk. The point is turn two of a
* conversation: without this, resuming re-reads the whole prompt through all 93 layers,
* which on a streamed trunk costs minutes; with it, a resumed session pays only for the
* tokens actually new.
*
* Three things are carried, and only three: the KDA recurrent matrices plus ShortConv
* history (fixed size, independent of context), the MLA KV cache, and the shared rope
* rows. The AttnRes block buffer is NOT carried because forward() clears it on entry and
* rebuilds it from the layer outputs every pass; saving it would be saving scratch.
*
* The KV cache is stored position-major inside each MLA layer's slice, so only the
* OCCUPIED positions are written and a resumed run may size its cache differently. The
* header carries a config fingerprint: restoring state built by a different architecture
* would produce fluent, wrong output with nothing to indicate it, which is the one
* failure mode this engine refuses to have.
*
* This lives outside k3_run.c so the format has a test that needs no checkpoint
* (tests/unit/test_state.c): the arrays are just floats and ints of the sizes the header
* declares, and every refusal below is reachable with synthetic ones. */
#ifndef K3_STATE_H
#define K3_STATE_H
#include <stddef.h>
#include <stdint.h>
#include "k3.h"
#define K3_STATE_MAGIC "K3ST"
/* Version 2 adds payload_hash. A version 1 file is refused rather than read with a
* guessed layout; state files are session artifacts, written and read by the same
* binary within one conversation, not a long-lived format. */
#define K3_STATE_VER 2
typedef struct {
char magic[4];
int32_t version;
int32_t fp[12]; /* config fingerprint */
int32_t n_bound, n_mla, cached, nseq;
int64_t kper; /* KDA+conv floats per layer */
int64_t kvpp, ropepp; /* KV / rope floats per position, per MLA layer */
/* k3_state_hash over the payload bytes in file order: seq, ks, then the KV and
* rope slices. Checked on load; a file whose every fread comes back full can still
* hold a damaged matrix, and this is the only check that sees it. */
uint64_t payload_hash;
} K3StateHdr;
#define K3_STATE_HASH_INIT 0xcbf29ce484222325ULL /* FNV-1a offset basis */
uint64_t k3_state_hash(uint64_t h, const void *p, size_t n);
void k3_state_fp(const K3Cfg *c, int32_t *fp);
/* Reads only the header, so the caller can size buffers before committing to a load.
* Returns 0, or -1 after printing why the file was refused. */
int k3_state_peek(const char *path, K3StateHdr *hd);
/* Restores the payload described by a header k3_state_peek accepted. seq must hold
* hd->nseq ints, ks hd->kper * n_bound floats, kvc and ropec n_mla slices of kv_cap
* positions each. Returns 0, or -1 after printing why; on -1 the arrays are not to be
* trusted. */
int k3_state_load(const char *path, const K3Cfg *c, const K3StateHdr *hd,
int *seq, float *ks, float *kvc, float *ropec,
int n_bound, int n_mla, int kv_cap);
int k3_state_save(const char *path, const K3Cfg *c, const int *seq, int nseq,
const float *ks, const float *kvc, const float *ropec,
int n_bound, int n_mla, int kv_cap, int cached,
int64_t kper, int64_t kvpp, int64_t ropepp);
#endif /* K3_STATE_H */