engram / README.md

docs: add model card with full protocol description

2a3efd4 verified 7 days ago

5.2 kB

library_name: engram
tags:
  - kv-cache
  - fingerprinting
  - fourier
  - retrieval
  - hnsw
  - session-memory
  - cross-model
  - inference
  - mcp
  - llm-memory
license: apache-2.0
language:
  - en
pipeline_tag: feature-extraction

ENGRAM: KV Cache Fingerprinting Protocol

You Don't Need Adapters: Cross-Model Document Retrieval via Intrinsic KV Cache Geometry

ENGRAM extracts Fourier fingerprints from LLM KV caches, stores them as compact binary certificates (.eng files, ~800 bytes), and retrieves them via HNSW approximate nearest neighbor search. This enables persistent cross-session memory for large language models with zero training.

By ENIGMA

Key Results

Metric	Value
Recall@1 (N=200)	100.0% (post Stage-4)
Raw Fourier recall	98.0% (f0+f1 DFT)
HNSW search latency	51.8 us
HNSW speedup	5.7x vs brute-force
Cross-model transfer	+0.124 margin (FCDB, no adapter)
CKA isomorphism	0.975 within-family, 0.927 cross-family
Certificate size	~800 bytes per document
Architectures	llama, gemma, gemma4/ISWA, phi, qwen, mistral
Tests	220 passing

How It Works

KV cache blob --> layer key extraction --> DFT(f0+f1) --> fingerprint (~800 bytes)
                                                              |
Query fingerprint --> HNSW search --> geodesic retrieval --> matched session/document

The Fourier Fingerprint

ENGRAM decomposes per-layer key trajectories using a 2-component DFT:

f0 (DC component): captures the mean activation level per layer
f1 (first harmonic): captures the dominant oscillation pattern

The resulting fingerprint is a compact, deterministic signature of the KV cache state that is:

Model-intrinsic: derived from the model's own geometry, not learned embeddings
Cross-model transferable: via Frechet Cross-Domain Bridge (FCDB)
Compression-robust: 0.99998 cosine similarity after INT8 quantization

4-Stage Geodesic Retrieval

Stage 0: Prior preemption     (IndexC chronic failure -> skip HNSW)
Stage 1: HNSW search          -> HIGH / MEDIUM confidence
Stage 2: Trajectory correction -> MEDIUM (interpolation w=0.3)
Stage 3: Negative constraints  -> LOW (apophatic layer)
Stage 4: Metadata disambig     -> LOW + stage4_used=True

Install

# Python (core library)
pip install engram-kv

# Node.js (MCP client)
npm install engram-kv-mcp

From source

git clone https://github.com/infraax/engram.git
cd engram
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
KMP_DUPLICATE_LIB_OK=TRUE OMP_NUM_THREADS=1 PYTHONPATH=. pytest tests/ -x -q

Architecture Support

Architecture	Attention Type	Status
Llama (1B-70B)	Standard MHA	Fully supported
Gemma (2B-27B)	Standard MHA	Fully supported
Gemma 4 (26B)	ISWA (sliding + global)	Fully supported
Phi (3.8B)	Standard MHA	Fully supported
Qwen (1.8B-72B)	GQA	Fully supported
Mistral (7B)	GQA + sliding window	Fully supported

Cross-Model Transfer

9 strategies evaluated. FCDB (Frechet Cross-Domain Bridge) wins:

Strategy	Margin	Method
FCDB	+0.124	Frechet mean of cross-model fingerprints
TruncAlign	+0.098	Truncate to min shared layers
ZeroPad	+0.067	Pad shorter fingerprint with zeros
SpectralInterp	+0.045	Interpolate in frequency domain

No adapter training required. The geometry is intrinsic.

MCP Server (Claude Code Integration)

ENGRAM includes an MCP server for persistent session memory in Claude Code:

claude mcp add --global engram-memory \
  -e ENGRAM_SESSIONS_DIR=~/.engram/sessions \
  -- python3 mcp/engram_memory.py

7 tools: write_session_engram, get_last_session, retrieve_relevant_sessions, get_relevant_context, list_indexed, index_knowledge

EIGENGRAM Binary Format (v1.2)

Compact, versioned binary certificates:

Header:  magic(4B) + version(2B) + flags(2B) + dimensions
Vectors: vec_perdoc + vec_fcdb + joint_center + vec_fourier + vec_fourier_v2
Meta:    corpus_hash + model_id + metrics + task_description

~800 bytes per document. Deterministic encoding. Cross-platform portable.

Theoretical Contributions

Margin Power Law: margin ~ A * N^alpha where alpha = -0.207 (graceful degradation, no cliff)
CKA Manifold Isomorphism: within-family 0.975, cross-family 0.927 (geometry is intrinsic)
Frequency Ablation: f0+f1 is the sweet spot (f0-only: -23% recall, f0+f1+f2: -0.3% margin)
FCDB Scaling Law: cross-model recall drops from 100% (N<=20) to 0% (N=200) -- adapter-free has limits

Citation

@article{enigma2026engram,
  title={You Don't Need Adapters: Cross-Model Document Retrieval
         via Intrinsic KV Cache Geometry},
  author={ENIGMA},
  year={2026},
  url={https://github.com/infraax/engram}
}

License

Apache-2.0

Engram-protocol
/

engram