| --- |
| license: agpl-3.0 |
| tags: |
| - snapkitty |
| - agents |
| - python |
| --- |
| |
| > Source: [github.com/SNAPKITTYWEST/nekomata](https://github.com/SNAPKITTYWEST/nekomata) |
|
|
| <p align="center"> |
| <img src="assets/nekomata-avatar.png" alt="Nekomata" width="320"/> |
| </p> |
|
|
| <h1 align="center">NEKOMATA η«ε</h1> |
| <h3 align="center">The Autonomous Container Engine</h3> |
|
|
| <p align="center"> |
| <img src="https://img.shields.io/badge/language-Common_Lisp-blueviolet?style=flat-square"/> |
| <img src="https://img.shields.io/badge/engine-nekod-ff69b4?style=flat-square"/> |
| <img src="https://img.shields.io/badge/MoE-6_experts-orange?style=flat-square"/> |
| <img src="https://img.shields.io/badge/codegen-x86--64_%2B_ARM64-green?style=flat-square"/> |
| <img src="https://img.shields.io/badge/license-AGPL--3.0-red?style=flat-square"/> |
| <img src="https://img.shields.io/badge/status-PRODUCTION-brightgreen?style=flat-square"/> |
| <img src="https://img.shields.io/badge/self--mod-genetic_evolution-gold?style=flat-square"/> |
| <img src="https://img.shields.io/badge/WORM-sealed-black?style=flat-square"/> |
| </p> |
|
|
| <p align="center"><b>Infrastructure that rewrites itself.</b></p> |
|
|
| --- |
|
|
| ``` |
| ββββ ββββββββββββββ βββ βββββββ ββββ ββββ ββββββ βββββββββ ββββββ |
| βββββ ββββββββββββββ ββββββββββββββββββ ββββββββββββββββββββββββββββββ |
| ββββββ βββββββββ βββββββ βββ ββββββββββββββββββββββ βββ ββββββββ |
| ββββββββββββββββ βββββββ βββ ββββββββββββββββββββββ βββ ββββββββ |
| βββ βββββββββββββββββ βββββββββββββββ βββ ββββββ βββ βββ βββ βββ |
| βββ ββββββββββββββββ βββ βββββββ βββ ββββββ βββ βββ βββ βββ |
| |
| Infrastructure is code. |
| Code is data. |
| Data is alive. |
| ``` |
|
|
| --- |
|
|
| ## What Is This? |
|
|
| Nekomata is the **first AI-native container engine** built from first principles in Common Lisp. Not a Kubernetes alternative. A Kubernetes **replacement**. |
|
|
| The Nekomata (η«ε) is a supernatural cat with two tails: **code** and **data**. In Common Lisp, these are the same thing. Infrastructure is s-expressions. Containers evaluate. They transform. They **rewrite themselves**. |
|
|
| ``` |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| β β |
| β Kubernetes: 50B of YAML debt on a distributed key-value store β |
| β Nekomata: s-expressions that evaluate their own infrastructure β |
| β β |
| β Kubernetes: Reactive watch loops waiting for state drift β |
| β Nekomata: Predictive LLMβASM compilation of intent β |
| β β |
| β Kubernetes: Monolithic control plane (etcd + api-server + ...) β |
| β Nekomata: Sparse Mixture of Experts β 6 specialists, Top-K=2 β |
| β β |
| β Kubernetes: Immutable containers, no runtime modification β |
| β Nekomata: Live REPL injection + genetic self-modification β |
| β β |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| ``` |
|
|
| --- |
|
|
| ## Setup |
|
|
| ```bash |
| # One command β installs Docker + SBCL + Quicklisp |
| bash setup.sh |
| ``` |
|
|
| Supports Ubuntu/Debian, Fedora/RHEL, Arch Linux, and macOS (via Homebrew). |
|
|
| Or manually: |
| ```bash |
| # 1. Docker |
| curl -fsSL https://get.docker.com | sh |
| sudo usermod -aG docker $USER && newgrp docker |
| |
| # 2. SBCL |
| sudo apt install sbcl # or: brew install sbcl |
| |
| # 3. Quicklisp |
| curl -O https://beta.quicklisp.org/quicklisp.lisp |
| sbcl --load quicklisp.lisp --eval '(quicklisp-quickstart:install)' |
| |
| # 4. Load Nekomata |
| cd nekomata && sbcl --load nekod.asd --eval '(ql:quickload :nekod)' |
| ``` |
|
|
| --- |
|
|
| ## Quick Start |
|
|
| ```lisp |
| ;; Load the system |
| (ql:quickload :nekod) |
| |
| ;; Start the daemon |
| (nekod:nekomata-main) |
| |
| ;; Define a container β infrastructure as code, literally |
| (nekod:define-container my-app |
| :image "nginx:latest" |
| :ports '((8080 . 80)) |
| :env '((:NODE_ENV . "production")) |
| :restart-policy :always) |
| |
| ;; Self-healing failover chain |
| (nekod:with-failover my-app my-app-replica my-app-standby) |
| |
| ;; Drop into the live REPL |
| (nekod:nekod-repl) |
| ``` |
|
|
| --- |
|
|
| ## Architecture |
|
|
| ``` |
| βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| β NEKOMATA ENGINE β |
| βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€ |
| β β |
| β βββββββββββββ ββββββββββββββββ ββββββββββββββββββββββββββββ β |
| β β CLI β β EVAL LOOP β β CONTAINER REGISTRY β β |
| β β neko.lispβββ>β nekod-repl βββ>β define-container β β |
| β βββββββββββββ ββββββββββββββββ β with-failover β β |
| β ββββββββββββββββββββββββββββ β |
| β β |
| β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β |
| β β SPARSE MoE ROUTER β β |
| β β β β |
| β β Input(8) ββ> Gate Network ββ> Top-K(2) ββ> Softmax β β |
| β β β β |
| β β ββββββββββββ¬βββββββββββ¬ββββββββββ¬βββββββββββ¬βββββββββββ¬βββ β β |
| β β βSCHEDULINGβNETWORKINGβ STORAGE β RECOVERY β SECURITY βSCβ β β |
| β β β cron β socket β disk β failover β auth βalβ β β |
| β β β deploy β http β persist β rollback β encrypt βe β β β |
| β β β queue β route β worm β backup β seal β β β β |
| β β ββββββββββββ΄βββββββββββ΄ββββββββββ΄βββββββββββ΄βββββββββββ΄βββ β β |
| β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β |
| β β |
| β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β |
| β β LLM β ASM COMPILER β β |
| β β β β |
| β β "scale nginx to 5" β β |
| β β β β β |
| β β v β β |
| β β ββββββββββββ ββββββββββββ ββββββββββββ βββββββββββ β β |
| β β β TOKENIZE βββ>β AST βββ>β CODEGEN βββ>β VERIFY β β β |
| β β β intent β β extract β β x86/ARM β β bytes β β β |
| β β ββββββββββββ ββββββββββββ ββββββββββββ βββββββββββ β β |
| β β β β |
| β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β |
| β β |
| β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β |
| β β SELF-MODIFICATION β β |
| β β β β |
| β β ββββββββββββ ββββββββββββ ββββββββββββ βββββββββββ β β |
| β β β HOT-SWAP β β GENETIC β β STATE β βROLLBACK β β β |
| β β β live fn β β evolution β β capture β β points β β β |
| β β β redefine β β crossoverβ β snapshot β β restore β β β |
| β β ββββββββββββ ββββββββββββ ββββββββββββ βββββββββββ β β |
| β β β β |
| β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β |
| β β |
| β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β |
| β β DOCKER SUBSTRATE β β |
| β β β β |
| β β Unix Socket ββ> HTTP/1.1 Protocol ββ> Container Lifecycle β β |
| β β /var/run/docker.sock β β |
| β β β β |
| β β create | start | stop | kill | list | inspect | stats β β |
| β β pull | tag | prune | network | volume β β |
| β β β β |
| β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β |
| β β |
| β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β |
| β β SOCKET INGRESS PIPELINE β β |
| β β β β |
| β β /var/run/docker.sock β β |
| β β β β β |
| β β v β β |
| β β Unix Domain Socket (SBCL/CCL/IOlib portable) β β |
| β β β β β |
| β β v β β |
| β β Incremental HTTP Parser (chunked + content-length) β β |
| β β β β β |
| β β v β β |
| β β Docker /events Stream (infinite chunked consumption) β β |
| β β β β β |
| β β v β β |
| β β Compiled DFA Classifier (Thompson + subset construction) β β |
| β β β β β |
| β β v β β |
| β β 8-Feature Routing Vector ββ> Top-K=2 Sparse MoE β β |
| β β β β β |
| β β v β β |
| β β Expert Dispatch + Deterministic Receipt β β |
| β β β β |
| β β Security: capability-based policy, path validation, β β |
| β β DENY-by-default, no raw socket to untrusted agent β β |
| β β β β |
| β β Backpressure: high/low watermarks, queue depth cap, β β |
| β β event size limits, zero unbounded growth β β |
| β β β β |
| β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β |
| βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| ``` |
|
|
| --- |
|
|
| ## The 5-Layer Stack |
|
|
| ``` |
| LAYER 5: SELF-MODIFICATION |
| ββββββββββββββββββββββββββββββββββββββββββββββ |
| β Genetic evolution loop β |
| β Hot-swap live function redefinition β |
| β State capture + rollback points β |
| β Tournament / roulette selection β |
| ββββββββββββββββββββββββββββββββββββββββββββββ |
| β |
| LAYER 4: LLM β MACHINE CODE |
| ββββββββββββββββββββββββββββββββββββββββββββββ |
| β Intent tokenization β |
| β AST extraction (infra-ast struct) β |
| β x86-64 + ARM64 code generation β |
| β Byte-level verification β |
| β Constraint algebra (cpu/mem/latency) β |
| ββββββββββββββββββββββββββββββββββββββββββββββ |
| β |
| LAYER 3: SPARSE MoE ROUTING |
| ββββββββββββββββββββββββββββββββββββββββββββββ |
| β 6 domain experts β |
| β Noisy Top-K gating (k=2) β |
| β Load-balance loss β |
| β Xavier/Glorot trained weights (R pipeline) β |
| β WORM-sealed gradient history β |
| ββββββββββββββββββββββββββββββββββββββββββββββ |
| β |
| LAYER 2: REGEX MATHEMATICS |
| ββββββββββββββββββββββββββββββββββββββββββββββ |
| β Kleene algebra (concat/union/star) β |
| β DFA compilation + socket event filtering β |
| β NL intent β regex pattern mapping β |
| β Formal algebra at the wire level β |
| ββββββββββββββββββββββββββββββββββββββββββββββ |
| β |
| LAYER 1: LISP CORE |
| ββββββββββββββββββββββββββββββββββββββββββββββ |
| β s-expression infrastructure DSL β |
| β Container lifecycle management β |
| β Docker Engine API (Unix socket) β |
| β Condition system + restarts β |
| β Image persistence (save/restore world) β |
| ββββββββββββββββββββββββββββββββββββββββββββββ |
| ``` |
|
|
| --- |
|
|
| ## User Guide |
|
|
| ### Container Management |
|
|
| ``` |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| β COMMAND DESCRIPTION β |
| β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ£ |
| β neko run <spec> Create and start a container β |
| β neko stop <name> Stop a running container β |
| β neko kill <name> Force-kill a container β |
| β neko list List all managed containers β |
| β neko status Show system status + expert load β |
| β neko evolve Run one generation of evolution β |
| β neko repl Drop into the Nekomata REPL β |
| β neko save Snapshot current world state β |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| ``` |
|
|
| ### Container DSL Examples |
|
|
| ```lisp |
| ;; βββ Basic Container ββββββββββββββββββββββββββββββββββββββββββββ |
| (define-container web-server |
| :image "nginx:alpine" |
| :ports '((80 . 80) (443 . 443)) |
| :env '((:WORKER_PROCESSES . "auto")) |
| :restart-policy :always) |
| |
| ;; βββ Database with Persistent Volume ββββββββββββββββββββββββββββ |
| (define-container postgres-db |
| :image "postgres:16" |
| :ports '((5432 . 5432)) |
| :env '((:POSTGRES_PASSWORD . "sovereign") |
| (:POSTGRES_DB . "nekod")) |
| :volumes '(("/data/pg" . "/var/lib/postgresql/data")) |
| :restart-policy :unless-stopped) |
| |
| ;; βββ Failover Chain (automatic promotion) βββββββββββββββββββββββ |
| (with-failover postgres-db postgres-replica postgres-standby) |
| |
| ;; βββ Natural Language Intent ββββββββββββββββββββββββββββββββββββ |
| (nekod-eval "scale web-server to 5 replicas with 512mb memory limit") |
| ;; => Compiles to ASM, verifies bytes, executes container operations |
| ``` |
|
|
| ### The REPL |
|
|
| ``` |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| β NEKOMATA REPL v1.0 β |
| β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ£ |
| β β |
| β nekod> (list-containers) β |
| β => (#<CONTAINER web-server :running> β |
| β #<CONTAINER postgres-db :running> β |
| β #<CONTAINER redis-cache :running>) β |
| β β |
| β nekod> (route-intent "deploy new redis cluster") β |
| β => Expert: SCHEDULING (0.72) β |
| β Expert: STORAGE (0.28) β |
| β Action: create-cluster redis 3 replicas β |
| β β |
| β nekod> (evolve-generation :population 20 :rounds 5) β |
| β => Generation 1: best-fitness 0.847 β |
| β Generation 2: best-fitness 0.891 β |
| β Generation 3: best-fitness 0.923 β |
| β ... β |
| β Winner: scheduling-expert-v3 (fitness: 0.961) β |
| β Hot-swapping into live router... β |
| β Done. β |
| β β |
| β nekod> (save-nekod-image "checkpoint-2026-08-08") β |
| β => World saved. 847 objects, 12.3MB. β |
| β WORM sealed: a8f3c91d... β |
| β β |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| ``` |
|
|
| --- |
|
|
| ## MoE Router β Sparse Expert Selection |
|
|
| ``` |
| βββββββββββββββββββββββββββββββββββββββββββββββ |
| β INPUT VECTOR (8 features) β |
| β β |
| β [is_proof, is_auth, is_code, is_system, β |
| β complexity, entropy, confidence, urgency] β |
| ββββββββββββββββββββββββ¬βββββββββββββββββββββββ |
| β |
| v |
| βββββββββββββββββββββββββββββββββββββββββββββββ |
| β GATING NETWORK β |
| β β |
| β s_i = dot(W_i, h) + b_i + noise_i β |
| β noise_i ~ N(0, softplus(W_noise Β· h)) β |
| β β |
| β Top-K selection (K=2) β |
| β Softmax over selected ONLY β |
| ββββββββββββββββββββββββ¬βββββββββββββββββββββββ |
| β |
| ββββββββββββββββββΌβββββββββββββββββ |
| v v v |
| ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ |
| β EXPERT A β β EXPERT B β β (inactive) β |
| β prob: 0.72 β β prob: 0.28 β β prob: 0.00 β |
| ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ |
| β β |
| v v |
| βββββββββββββββββββββββββββββββββββββββββββββββ |
| β OUTPUT = p_A * expert_A + p_B * expert_B β |
| βββββββββββββββββββββββββββββββββββββββββββββββ |
| ``` |
|
|
| ### The 6 Experts |
|
|
| | Expert | Domain | Handles | |
| |--------|--------|---------| |
| | **SCHEDULING** | Time + orchestration | cron, deploy, queue, scaling events | |
| | **NETWORKING** | Connectivity | socket, http, routing, port management | |
| | **STORAGE** | Persistence | disk, WORM chains, volumes, snapshots | |
| | **RECOVERY** | Fault tolerance | failover, rollback, restart, backup | |
| | **SECURITY** | Auth + crypto | certificates, encryption, sealing | |
| | **SCALING** | Load management | replicas, sharding, capacity planning | |
|
|
| ### Weight Training Pipeline |
|
|
| ``` |
| WORM Chain ββ> R Feature Extraction ββ> Xavier/Glorot Init |
| (.jsonl) (8 features) (W1: 8x16, W2: 16x6) |
| β |
| v |
| Forward Pass + Backprop |
| Binary Cross-Entropy Loss |
| β |
| v |
| WORM Seal (every 10 epochs) |
| SHA-256 weight hash |
| β |
| v |
| Export: router_weights.json |
| β |
| v |
| Lisp: load-trained-weights |
| Hot-loaded into live router |
| ``` |
|
|
| --- |
|
|
| ## LLM β Machine Code Compilation |
|
|
| ``` |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| β β |
| β "scale nginx to 5 with 256mb memory limit" β |
| β β |
| β β TOKENIZE β |
| β v β |
| β [:scale :nginx :to :5 :with :256mb :memory :limit] β |
| β β |
| β β AST EXTRACT β |
| β v β |
| β #S(INFRA-AST β |
| β :TYPE :SCALE β |
| β :TARGET "nginx" β |
| β :PARAMS (:COUNT 5 :MEMORY 268435456)) β |
| β β |
| β β CODEGEN (x86-64) β |
| β v β |
| β #(#x48 #x89 #xF8 ; mov rax, rdi β |
| β #x48 #x6B #xC0 5 ; imul rax, 5 β |
| β #xC3) ; ret β |
| β β |
| β β VERIFY β |
| β v β |
| β [OK] First byte valid (0x48 = REX.W prefix) β |
| β [OK] Last byte = 0xC3 (RET) β |
| β [OK] No privileged instructions β |
| β [OK] Length within bounds β |
| β β |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| ``` |
|
|
| ### Supported Backends |
|
|
| | Backend | Status | Instruction Set | |
| |---------|--------|-----------------| |
| | **x86-64** | Production | REX prefix, MOV, ADD, IMUL, XOR, PUSH/POP, CALL, RET | |
| | **ARM64** | Production | Fixed-width 32-bit, MOV/MOVK, ADD, SUB, MUL, BR, RET | |
|
|
| --- |
|
|
| ## Self-Modification Engine |
|
|
| ``` |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| β GENETIC EVOLUTION LOOP β |
| β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ£ |
| β β |
| β 1. POPULATION β |
| β Generate N candidate expert functions β |
| β β |
| β 2. EVALUATE β |
| β Run each candidate against real container workloads β |
| β Fitness = success_rate * latency_inverse * memory_eff β |
| β β |
| β 3. SELECT β |
| β Tournament selection (pool=4) OR roulette wheel β |
| β β |
| β 4. CROSSOVER β |
| β Swap s-expression subtrees between parents β |
| β Code IS data β crossover is tree surgery β |
| β β |
| β 5. MUTATE β |
| β Random subtree replacement, constant perturbation β |
| β β |
| β 6. HOT-SWAP β |
| β Winner replaces live expert function β zero downtime β |
| β Automatic rollback if fitness drops below threshold β |
| β β |
| β 7. SEAL β |
| β State captured, rollback point created, WORM sealed β |
| β β |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| ``` |
|
|
| --- |
|
|
| ## Regex Mathematics β Formal Algebra at the Wire |
|
|
| ``` |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| β KLEENE ALGEBRA PRIMITIVES β |
| β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ£ |
| β β |
| β LITERAL(c) Match single character c β |
| β CONCAT(r1, r2) Sequence: r1 then r2 β |
| β UNION(r1, r2) Choice: r1 or r2 β |
| β KLEENE(r) Zero or more: r* β |
| β PLUS(r) One or more: r+ β |
| β OPTIONAL(r) Zero or one: r? β |
| β β |
| β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ£ |
| β β |
| β DFA COMPILATION: β |
| β β |
| β regex-algebra.lisp ββ> pattern-compiler.lisp β |
| β (algebraic form) (DFA states + transitions) β |
| β β |
| β dfa-step(state, char) => next-state β |
| β dfa-run(dfa, string) => accept | reject β |
| β β |
| β SOCKET FILTERING: β |
| β β |
| β Every Docker event passes through DFA filter β |
| β Pattern: container.(start|stop|die|kill) β |
| β Only matching events reach the MoE router β |
| β β |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| ``` |
|
|
| --- |
|
|
| ## Project Layout |
|
|
| ``` |
| nekod/ |
| βββ nekod.asd ASDF system definition |
| βββ setup.sh One-command Docker + SBCL installer |
| βββ README.md This file |
| βββ LICENSE AGPL-3.0 + cloud provider poison pill |
| βββ assets/ |
| β βββ nekomata-avatar.png Production model avatar |
| β |
| βββ core/ βββ LAYER 1: LISP CORE βββ |
| β βββ package.lisp Package definitions (nekod + nekod.docker) |
| β βββ conditions.lisp Error hierarchy + restart system |
| β βββ sexpr-infra.lisp Container DSL (define-container, with-failover) |
| β βββ eval-loop.lisp Nekomata REPL (nekod-eval, nekod-repl) |
| β βββ image-persist.lisp World state save/restore |
| β βββ nekomata.lisp Entry point + container registry |
| β |
| βββ docker/ βββ DOCKER SUBSTRATE βββ |
| β βββ unix-sock.lisp Real Unix socket I/O (SBCL/CCL/IOlib) |
| β βββ protocol.lisp Incremental HTTP/1.1 parser (chunked + CL) |
| β βββ events.lisp Streaming /events consumer (infinite chunked) |
| β βββ container.lisp Container lifecycle (create/start/stop/kill) |
| β βββ image.lisp Image management (pull/list/tag/prune) |
| β βββ network.lisp Network create/connect/disconnect |
| β βββ volume.lisp Volume create/mount/prune |
| β βββ inspect.lisp Container + stats inspection |
| β |
| βββ moe/ βββ LAYER 3: SPARSE MoE βββ |
| β βββ router.lisp Gating network (score, top-k, softmax) |
| β βββ sparse-activate.lisp Noisy Top-K + load-balance loss |
| β βββ expert-train.lisp Online weight updates from telemetry |
| β βββ load-balance.lisp Expert utilization balancing |
| β βββ load-trained-weights.lisp R-trained weight loader (JSON import) |
| β βββ experts/ |
| β βββ scheduling.lisp Cron, deploy, queue management |
| β βββ networking.lisp Socket, HTTP, port routing |
| β βββ storage.lisp Disk, WORM, volume persistence |
| β βββ recovery.lisp Failover, rollback, restart |
| β βββ security.lisp Auth, encryption, sealing |
| β βββ scaling.lisp Replicas, shards, capacity |
| β |
| βββ regex-math/ βββ LAYER 2: KLEENE ALGEBRA βββ |
| β βββ regex-algebra.lisp RE structs (literal/concat/union/kleene) |
| β βββ pattern-compiler.lisp Thompson NFA β subset DFA compilation |
| β βββ socket-filter.lisp Compiled DFA event classifier + features |
| β βββ intent-parse.lisp NL intent β expert keyword mapping |
| β |
| βββ socket/ βββ SOCKET INGRESS PIPELINE βββ |
| β βββ backpressure.lisp Watermarks, queue depth, size limits |
| β βββ policy.lisp Capability-based security boundary |
| β βββ receipt.lisp Deterministic operation receipts |
| β βββ agent-ingress.lisp Event β classify β route β dispatch |
| β |
| βββ llm2asm/ βββ LAYER 4: LLM β MACHINE CODE βββ |
| β βββ tokenizer.lisp Intent tokenization + kernel map |
| β βββ ast-extract.lisp infra-ast struct, intent type detection |
| β βββ codegen.lisp AST β byte vector compilation |
| β βββ verify.lisp Byte-level safety verification |
| β βββ jit-link.lisp JIT stub (mmap + mprotect reference) |
| β βββ constraint-build.lisp Constraint algebra (cpu/mem/latency) |
| β βββ backends/ |
| β βββ x86-64.lisp x86-64 instruction encoders |
| β βββ arm64.lisp ARM64 fixed-width instruction encoders |
| β |
| βββ selfmod/ βββ LAYER 5: SELF-MODIFICATION βββ |
| β βββ gen-loop.lisp Genetic evolution loop |
| β βββ hot-swap.lisp Live function redefinition + rollback |
| β βββ state-capture.lisp State snapshots |
| β βββ evolve.lisp Crossover + selection algorithms |
| β βββ rollback.lisp Rollback points, with-rollback macro |
| β |
| βββ cli/ βββ USER INTERFACE βββ |
| β βββ neko.lisp 8 CLI commands (run/stop/kill/list/...) |
| β |
| βββ tests/ |
| β βββ test-core.lisp Core test suite |
| β βββ test-edge-cases.lisp Edge case coverage |
| β βββ socket-tests.lisp Socket layer: 28 unit + 4 integration tests |
| β |
| βββ docs/ βββ DOCUMENTATION βββ |
| βββ manifesto.org Why Nekomata exists |
| βββ architecture.org 5-layer system design |
| βββ moe-theory.org Sparse MoE mathematics |
| βββ regex-calculus.org Kleene algebra formalism |
| βββ migration.org Kubernetes escape route |
| ``` |
|
|
| --- |
|
|
| ## Why Common Lisp? |
|
|
| ``` |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| β β |
| β CODE = DATA β |
| β An s-expression describing a container IS that container. β |
| β No YAML. No templating. No string interpolation. β |
| β The description evaluates to the thing itself. β |
| β β |
| β CONDITION SYSTEM β |
| β Not try/catch. Restarts. When a container dies, the β |
| β condition system offers: restart, promote-replica, β |
| β rollback, or escalate. Decided at runtime, not design-time. β |
| β β |
| β IMAGE-BASED PERSISTENCE β |
| β Save the entire world to disk. Restore it later. β |
| β The running state IS the deployment artifact. β |
| β No container image layers. No registries. Just the world. β |
| β β |
| β MACROS β |
| β define-container is a macro. with-failover is a macro. β |
| β The language extends itself to become the domain. β |
| β Infrastructure IS language. Language IS infrastructure. β |
| β β |
| β HOT RELOAD β |
| β Redefine any function while the system runs. β |
| β No restart. No redeployment. The new code IS the system. β |
| β Genetic evolution swaps expert functions live. β |
| β β |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| ``` |
|
|
| --- |
|
|
| ## Migration from Kubernetes |
|
|
| ``` |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| β K8S β NEKOMATA MIGRATION PATH β |
| β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ£ |
| β β |
| β Step 1: Install nekod alongside existing cluster β |
| β (nekod speaks Docker socket directly β no conflict) β |
| β β |
| β Step 2: Convert Deployment YAMLs β define-container forms β |
| β One YAML = one s-expression. Mechanical. β |
| β β |
| β Step 3: Wire failover chains β |
| β (with-failover primary replica standby) β |
| β β |
| β Step 4: Enable MoE routing β |
| β Expert weights train on YOUR workload patterns β |
| β β |
| β Step 5: Enable self-modification β |
| β The system evolves its own expert functions β |
| β β |
| β Step 6: Decommission K8s control plane β |
| β etcd, kube-apiserver, kube-scheduler β gone. β |
| β Nekomata IS the control plane now. β |
| β β |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| ``` |
|
|
| --- |
|
|
| ## Performance Characteristics |
|
|
| ``` |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| β METRIC VALUE β |
| β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ£ |
| β Memory per expert ~2.3 KB (sparse activation) β |
| β Router decision latency <1ms (dot product + softmax) β |
| β Active experts per call 2 (Top-K=2, out of 6) β |
| β Agents at 2.3KB each 500+ sustainable β |
| β Code generation x86-64 + ARM64 native β |
| β Hot-swap latency ~0ms (defun redefinition) β |
| β World snapshot Full state in single file β |
| β Container start Direct Docker API (no etcd) β |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| ``` |
|
|
| --- |
|
|
| ## License |
|
|
| **AGPL-3.0** with cloud provider poison pill. |
|
|
| The engine is free. Sovereignty is not optional. |
|
|
| Any cloud provider deploying Nekomata as a hosted service MUST: |
| 1. Release all modifications under AGPL-3.0 |
| 2. Provide users a prominent link to modified source |
| 3. Not remove attribution to SnapKitty Collective |
|
|
| --- |
|
|
| ### πΌ Commercial License |
|
|
| Snapkitty code is free and open under **AGPL-3.0** for open-source use. Building a commercial product or service? A **proprietary commercial license** from Snapkitty Collective LLC lets you ship this code without the AGPL's source-sharing and network-use obligations. |
|
|
| **[β Get a commercial license](mailto:A.parr@belespritdaccord.uk?subject=Commercial%20license:%20nekomata)** Β· A.parr@belespritdaccord.uk |
|
|
| ## Credits |
|
|
| ``` |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| β β |
| β Architecture Ahmad Ali Parr β |
| β Engineering SnapKitty Collective β |
| β Model Avatar Nekomata β the two-tailed sovereign cat β |
| β Execution WORM-sealed, receipt-generating β |
| β β |
| β "Infrastructure that rewrites itself." β |
| β β |
| ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ |
| ``` |
|
|
| --- |
|
|
| <p align="center"> |
| <img src="assets/nekomata-avatar.png" alt="Nekomata" width="160"/> |
| <br/> |
| <b>η«ε β The two-tailed cat that never dies.</b> |
| </p> |
|
|
