k-familiar 0.1.0

A holographic AI that thinks in six table lookups. 16K classifications/sec. Zero training. 313 bytes.

k-familiar

A holographic AI that thinks in six table lookups.

16,000 classifications per second. Zero training. 313 bytes of tables. Provably safe.

from k_familiar import Familiar

f = Familiar()
result = f.classify("I feel stuck on this problem")

print(result["suit"])        # "spades" (mind/analysis domain)
print(result["confidence"])  # 0.82
print(result["k_addr"])      # "-5S"
print(result["latency_us"])  # ~60

What It Does

Classifies any text into four cognitive domains using GF(4) finite field algebra:

Domain	Suit	What it catches
Hearts	H	Emotion, relationships, connection, care
Spades	S	Analysis, logic, conflict, truth-seeking
Diamonds	D	Material, building, engineering, physical
Clubs	C	Action, energy, will, commands, creation

Each classification also returns:

• Confidence (0.0-1.0)
• Rank (1-13, intensity/complexity)
• Polarity (light/dark, positive/negative valence)
• K-address (e.g., "+7H" = high-intensity positive emotional content)

Why It's Different

Feature	k-familiar	Typical classifier
Model size	313 bytes	100MB+
Training required	None	Hours/days
Parameters	0	Millions
Speed	~60us/query	~50ms/query
Dependencies	numpy only	torch, transformers, ...
Safety	By construction	By filtering
Offline	Always	Usually not

How It Works

Six operations over GF(4) lookup tables:

Operation	Symbol	What it does
BIND	a x b	Associate two ideas (GF(4) multiply)
BUNDLE	a + b	Hold multiple ideas at once (GF(4) add)
RETRIEVE	s x key^-1	Pull one idea back out (multiply by inverse)
FOLD	C(v)	Compress 3:1 through codon lookup table
CHECK	k <= sqrt(d)	Am I sure? Test holographic capacity
ASK	?	I'm not sure. Escalate to human/LLM

The entire computation is table lookups. No matrix multiplies. No floating point in the critical path. Fits in L1 cache.

Install

pip install k-familiar

Quick Start

Classify text

from k_familiar import Familiar

f = Familiar()

# Classify anything
print(f.classify("How do I fix this bug?"))
# {'suit': 'spades', 'confidence': 0.78, 'k_addr': '-5S', ...}

print(f.classify("I'm so grateful for my team"))
# {'suit': 'hearts', 'confidence': 0.85, 'k_addr': '+7H', ...}

print(f.classify("Ship the release by Friday"))
# {'suit': 'clubs', 'confidence': 0.71, 'k_addr': '+5C', ...}

print(f.classify("The server needs more RAM"))
# {'suit': 'diamonds', 'confidence': 0.69, 'k_addr': '+5D', ...}

Route to templates

f = Familiar()

# Set responses for each domain
f.set_template("H", response="Take a breath. You're not alone in this.")
f.set_template("S", response="Let's break this down step by step.")
f.set_template("D", response="Check the specs, then build a prototype.")
f.set_template("C", response="Start now. Iterate later.")

# Route automatically
result = f.route("I can't figure out this algorithm")
print(result["response"])  # "Let's break this down step by step."
print(result["source"])    # "template"

Working memory

f = Familiar()

# Remember things (holographic superposition)
f.remember("morning", "had coffee with Sarah, felt good")
f.remember("task", "need to finish the API by Thursday")

print(f.status())
# {'bundle_items': 2, 'capacity': {'phase': 'green', ...}, ...}

# Capacity is bounded: ~10 items for d=64
# The Familiar KNOWS when it's full and will refuse + ASK

Use the raw opcodes

from k_familiar import bind, bundle, retrieve, fold, check
import numpy as np

# Create vectors
key = np.random.randint(0, 4, 64).astype(np.uint8)
val = np.random.randint(0, 4, 64).astype(np.uint8)

# Bind, bundle, retrieve
bound = bind(key, val)
memory = bundle(bound, np.zeros(64, dtype=np.uint8))
recovered = retrieve(memory, key)

# Compress
folded = fold(recovered)  # 64 -> 21 elements (3:1 via genetic code table)

# Check capacity
status = check(bundle_items=3, d=64)
print(status)  # {'items': 3, 'capacity': 10.67, 'ok': True, 'phase': 'green'}

Use Cases

Pre-LLM router — Classify intent locally before making expensive API calls. Route 80% of queries to templates, send only the hard 20% to GPT/Claude.

Safety layer — The Familiar can't produce harmful outputs because the codon tables don't have paths to harm. Not filtered. Absent. Use as a first-pass safety check.

Agent classifier — In multi-agent systems (CrewAI, AutoGen, LangGraph), use k-familiar to route tasks to the right agent by domain.

Offline AI — Works on airplanes, in the field, on Raspberry Pi. No internet, no API keys, no latency.

Education — Teach information theory, finite fields, and holographic memory with a working implementation.

The Math

The GF(4) field has four elements {0, 1, 2, 3} with addition and multiplication tables:

ADD:  0 1 2 3    MUL:  0 1 2 3
    0 0 1 2 3        0 0 0 0 0
    1 1 0 3 2        1 0 1 2 3
    2 2 3 0 1        2 0 2 3 1
    3 3 2 1 0        3 0 3 1 2

These 32 bytes (two 4x4 tables) are the entire "model." Everything else is derived.

The capacity bound: a bundle of k items in d dimensions can be reliably retrieved when k <= (q/(q-1)) * sqrt(d). For GF(4), d=64: capacity ~ 10.67 items.

The fold operation uses the biological genetic code (64 codons -> 21 amino acids) as a compression table. This is not a metaphor. It's the same math.

License

MIT. Use it for anything.

Links

• HoldTheLine — Project home
• K-Systems Research — The math
• Papers — GF(4) routing, holographic capacity proofs