Engram-protocol/engram

1---2library_name: engram3tags:4  - kv-cache5  - fingerprinting6  - fourier7  - retrieval8  - hnsw9  - session-memory10  - cross-model11  - inference12  - mcp13  - llm-memory14license: apache-2.015language:16  - en17pipeline_tag: feature-extraction18---19 20# ENGRAM: KV Cache Fingerprinting Protocol21 22**You Don't Need Adapters: Cross-Model Document Retrieval via Intrinsic KV Cache Geometry**23 24ENGRAM 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.25 26> *By ENIGMA*27 28## Key Results29 30| Metric | Value |31|---|---|32| Recall@1 (N=200) | **100.0%** (post Stage-4) |33| Raw Fourier recall | **98.0%** (f0+f1 DFT) |34| HNSW search latency | **51.8 us** |35| HNSW speedup | **5.7x** vs brute-force |36| Cross-model transfer | **+0.124 margin** (FCDB, no adapter) |37| CKA isomorphism | **0.975** within-family, **0.927** cross-family |38| Certificate size | **~800 bytes** per document |39| Architectures | llama, gemma, gemma4/ISWA, phi, qwen, mistral |40| Tests | **220 passing** |41 42## How It Works43 44```45KV cache blob --> layer key extraction --> DFT(f0+f1) --> fingerprint (~800 bytes)46                                                              |47Query fingerprint --> HNSW search --> geodesic retrieval --> matched session/document48```49 50### The Fourier Fingerprint51 52ENGRAM decomposes per-layer key trajectories using a 2-component DFT:53- **f0** (DC component): captures the mean activation level per layer54- **f1** (first harmonic): captures the dominant oscillation pattern55 56The resulting fingerprint is a compact, deterministic signature of the KV cache state that is:57- **Model-intrinsic**: derived from the model's own geometry, not learned embeddings58- **Cross-model transferable**: via Frechet Cross-Domain Bridge (FCDB)59- **Compression-robust**: 0.99998 cosine similarity after INT8 quantization60 61### 4-Stage Geodesic Retrieval62 63```64Stage 0: Prior preemption     (IndexC chronic failure -> skip HNSW)65Stage 1: HNSW search          -> HIGH / MEDIUM confidence66Stage 2: Trajectory correction -> MEDIUM (interpolation w=0.3)67Stage 3: Negative constraints  -> LOW (apophatic layer)68Stage 4: Metadata disambig     -> LOW + stage4_used=True69```70 71## Install72 73```bash74# Python (core library)75pip install engram-kv76 77# Node.js (MCP client)78npm install engram-kv-mcp79```80 81### From source82 83```bash84git clone https://github.com/infraax/engram.git85cd engram86python3 -m venv .venv && source .venv/bin/activate87pip install -e ".[dev]"88 89# Run tests90KMP_DUPLICATE_LIB_OK=TRUE OMP_NUM_THREADS=1 PYTHONPATH=. pytest tests/ -x -q91```92 93## Architecture Support94 95| Architecture | Attention Type | Status |96|---|---|---|97| Llama (1B-70B) | Standard MHA | Fully supported |98| Gemma (2B-27B) | Standard MHA | Fully supported |99| Gemma 4 (26B) | ISWA (sliding + global) | Fully supported |100| Phi (3.8B) | Standard MHA | Fully supported |101| Qwen (1.8B-72B) | GQA | Fully supported |102| Mistral (7B) | GQA + sliding window | Fully supported |103 104## Cross-Model Transfer105 1069 strategies evaluated. **FCDB (Frechet Cross-Domain Bridge)** wins:107 108| Strategy | Margin | Method |109|---|---|---|110| FCDB | **+0.124** | Frechet mean of cross-model fingerprints |111| TruncAlign | +0.098 | Truncate to min shared layers |112| ZeroPad | +0.067 | Pad shorter fingerprint with zeros |113| SpectralInterp | +0.045 | Interpolate in frequency domain |114 115No adapter training required. The geometry is intrinsic.116 117## MCP Server (Claude Code Integration)118 119ENGRAM includes an MCP server for persistent session memory in Claude Code:120 121```bash122claude mcp add --global engram-memory \123  -e ENGRAM_SESSIONS_DIR=~/.engram/sessions \124  -- python3 mcp/engram_memory.py125```126 127**7 tools**: `write_session_engram`, `get_last_session`, `retrieve_relevant_sessions`, `get_relevant_context`, `list_indexed`, `index_knowledge`128 129## EIGENGRAM Binary Format (v1.2)130 131Compact, versioned binary certificates:132 133```134Header:  magic(4B) + version(2B) + flags(2B) + dimensions135Vectors: vec_perdoc + vec_fcdb + joint_center + vec_fourier + vec_fourier_v2136Meta:    corpus_hash + model_id + metrics + task_description137```138 139~800 bytes per document. Deterministic encoding. Cross-platform portable.140 141## Theoretical Contributions142 1431. **Margin Power Law**: margin ~ A * N^alpha where alpha = -0.207 (graceful degradation, no cliff)1442. **CKA Manifold Isomorphism**: within-family 0.975, cross-family 0.927 (geometry is intrinsic)1453. **Frequency Ablation**: f0+f1 is the sweet spot (f0-only: -23% recall, f0+f1+f2: -0.3% margin)1464. **FCDB Scaling Law**: cross-model recall drops from 100% (N<=20) to 0% (N=200) -- adapter-free has limits147 148## Citation149 150```bibtex151@article{enigma2026engram,152  title={You Don't Need Adapters: Cross-Model Document Retrieval153         via Intrinsic KV Cache Geometry},154  author={ENIGMA},155  year={2026},156  url={https://github.com/infraax/engram}157}158```159 160## Links161 162- [GitHub](https://github.com/infraax/engram)163- [PyPI: engram-kv](https://pypi.org/project/engram-kv/)164- [npm: engram-kv-mcp](https://www.npmjs.com/package/engram-kv-mcp)165 166## License167 168Apache-2.0169