Skip to content

Home

Jump to bottom
Raul Cardenas Montoya edited this page Sep 19, 2026 · 5 revisions

engram-parser

DeepWiki

Wiki hero

Pure-Rust, zero-dependency GGUF deserializer and MoE per-expert weight extractor.

Version: 0.2.0 | Edition: 2024 | MSRV: 1.97.1 | License: MIT OR Apache-2.0

An engram is a physical trace of memory. This crate rips frozen weights (memories) out of MoE GGUF checkpoints so live systems can consume raw byte buffers with shape/dtype metadata — no neural-network math.

Default builds are GGUF-only and zero-dependency (fs::read into Vec<u8>). Two optional cargo features extend it:

  • safetensors (off by default): in-crate Safetensors header / manifest / MoE-discovery support — no separate crate, no extra crates
  • mmap (off by default): load_gguf_mmap via memmap2 instead of reading the whole file

What It Does

  • Parse GGUF v3 (magic, header, KV metadata, tensor directory) → GgufLayout
  • Enumerate MoE experts: list_experts
  • Extract one expert's gate / up / down raw bytes: extract_expert
  • Support stacked (ffn_*_exps.weight) and per-expert (ffn_*.E.weight) layouts
  • Packed dequant to f32 for Q8_0, Q5_K, Q6_K, IQ3_M block layout (dequantize_packed and friends)
  • Safetensors checkpoint inspection behind the safetensors feature: inspect_safetensors_checkpoint → deterministic SafetensorsManifest

What It Does Not Do

  • No matmul, forward, routing, softmax
  • No CUDA / GPU / SIMD
  • Zero crate dependencies on the default path ([dependencies] is empty; only optional memmap2 under --features mmap)
  • No tokenization or SNN dynamics
  • No full model-family routing policy (see cortex-tensor)
  • No Safetensors payload mmap/tensor extraction or Hugging Face config.json policy — the safetensors feature is header/manifest/discovery only

Start Here

Page Description
Getting Started Install, load, extract
Project Structure Modules and tree
Architecture Ownership and non-goals
GGUF Parsing load_gguf, layout, cursor, dequant
Tensor and DType Directory entries and types
MoE Extraction stacked vs per-expert
Safetensors Feature-gated safetensors support (reverses #10)
Errors ParserError
Public API Crate surface
Overview Wiki map
Testing Smoke + pilot tests
CI and Quality GHA, security, Docker
MSRV 1.97.1 policy
Ecosystem cortex-tensor, corinth-canal
Glossary Terms

Quick Commands

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo build --all-features
cargo test --all-features

License

Dual-licensed under MIT or Apache-2.0 at your option.

Last updated: September 16, 2026 Updated by: KAI Package tip reference: 3dea2c3 (main)

Clone this wiki locally