holographic-memory 0.5.0

A high-performance Holographic Memory System (HMS) implementing Vector Symbolic Architectures (VSA).
Documentation
# HMS vs. Alternatives

Understanding where a Holographic Memory System (HMS) fits in the AI landscape is crucial for architectural decisions.

## Technical Comparison

| Feature | HMS (BSC/HDC) | Traditional Vector DB (Pinecone/Milvus) | LLM Embeddings (OpenAI/Cohere) |
|---------|---------------|-----------------------------------------|--------------------------------|
| **Vector Type** | High-D Binary (Bits) | Floating Point (f32) | Floating Point (f32) |
| **Storage** | Extremely Low (1 bit/dim) | High (32 bits/dim) | High (32 bits/dim) |
| **Search Ops** | XOR + Popcount (Hardware) | Cosine / Euclidean (Floating point) | Cosine / Euclidean |
| **Logic** | Symbolic Arithmetic (Bind/Bundle) | Linear Algebra | Deep Learning Inference |
| **Learning** | Instant (One-shot) | Requires Index Rebuild | Requires Training/Fine-tuning |
| **Hardware** | Optimized for FPGA/ASIC | GPU/High-end CPU | GPU Required |

## Why use HMS?

### 1. Hybrid Semantic Nuance
While the default N-gram encoder is structural, HMS supports **Semantic Projection**. You can take a high-nuance embedding from a model like BERT or OpenAI, project it into the HMS binary space using `memorize_vector`, and perform logic and search at bitwise speeds while retaining the original model's semantic relationships.

### 2. Transparent Reasoning
Unlike "Black Box" embeddings, HMS allows you to perform **Vector Arithmetic**. You can literally subtract one concept from another or find an analogy (A is to B as C is to D) using simple XOR operations.

### 2. Extreme Speed
Because similarity is calculated via **Hamming Distance** (XOR + Popcount), it can be several orders of magnitude faster than floating-point cosine similarity on modern CPUs with AVX-512 or NEON instructions.

### 3. Edge-First Design
The binary nature of the memory makes it ideal for IoT and mobile devices where memory and battery are limited. A 10,000-dimension vector takes only **1.25 KB**.

### 4. No "Catastrophic Forgetting"
HDC systems are inherently robust to noise. Because the information is distributed "holographically," losing 10% of the dimensions still results in ~90% accuracy.

## When NOT to use HMS

- **High-Precision Geometry**: If your application requires exact spatial coordinates in Euclidean space.
- **Deep Semantic Nuance**: While HMS is great for structural and symbolic similarity, Transformer-based LLM embeddings (like `text-embedding-3-small`) currently capture deeper contextual nuance in natural language for complex prose.