Metadata-Version: 2.4
Name: phase-space-memory
Version: 1.0.0
Summary: A universal phase-space memory engine that retrieves knowledge via holographic interference instead of vector similarity search.
Home-page: https://github.com/Luckyy0311
Author: Abdul Mofique Siddiqui
Author-email: mofique7860@gmail.com
License: MIT
Keywords: holographic-memory,rag,vector-search,ai,retrieval
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.21
Provides-Extra: gpu
Requires-Dist: cupy>=12.0; extra == "gpu"
Provides-Extra: neural
Requires-Dist: sentence-transformers>=2.2; extra == "neural"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# holographic-memory

A universal phase-space memory engine that retrieves knowledge via **holographic
interference** instead of vector similarity search.

[![PyPI version](https://img.shields.io/pypi/v/holographic-memory)](https://pypi.org/project/holographic-memory/)
[![Python](https://img.shields.io/pypi/pyversions/holographic-memory)](https://pypi.org/project/holographic-memory/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## Why?

Classic RAG retrieves text chunks by cosine similarity and stuffs them into a
prompt. This returns **passages**, not answers, and pollutes the context window.

`holographic-memory` binds `key -> value` pairs into complex phase vectors and
retrieves by **constructive / destructive wave interference**. The result is the
exact value, directly, with no chunk stuffing.

| Feature | Classic RAG | holographic-memory |
|---|---|---|
| Retrieval signal | Cosine similarity | Phase interference |
| Returns | Text chunk | Exact value |
| Context pollution | High | None |
| Answer verbosity | High | Minimal |

---

## Installation

```bash
pip install holographic-memory
```

Optional extras:

```bash
# GPU acceleration via CuPy
pip install holographic-memory[gpu]

# Neural (sentence-transformers) encoder
pip install holographic-memory[neural]
```

---

## Quick Start

```python
from holographic import HolographicEngine, HashPhaseEncoder

engine = HolographicEngine(encoder=HashPhaseEncoder(dim=2048))

engine.add("capital France", "Paris")
engine.add("capital Japan", "Tokyo")
engine.add("ceo Tesla", "Elon Musk")
engine.build()

print(engine.ask("What is the capital of France?")["answer"])
# -> Paris
```

---

## Use a Neural Encoder

```python
from holographic import HolographicEngine, NeuralPhaseEncoder

engine = HolographicEngine(encoder=NeuralPhaseEncoder(dim=2048))
# ... same API
```

## Custom Encoder

Any object with a `dim` attribute and an `encode(text) -> complex ndarray`
method works:

```python
import numpy as np
from holographic import HolographicEngine

class MyEncoder:
    dim = 2048
    def encode(self, text: str) -> np.ndarray:
        # your logic; return complex64 vector of shape (dim,)
        ...

engine = HolographicEngine(encoder=MyEncoder())
```

---

## Ingest a Whole Document

```python
from holographic import HolographicEngine, HashPhaseEncoder, ingest_text

engine = HolographicEngine(encoder=HashPhaseEncoder(dim=2048))
ingest_text(engine, open("handbook.txt").read(), source="handbook")
engine.build()
```

## Save / Load

```python
from holographic import save_engine, load_engine

save_engine(engine, "memory.json")
load_engine(engine, "memory.json")
```

---

## Configuration

```python
from holographic import HolographicConfig

config = HolographicConfig(
    dim=4096,           # vector dimensionality
    shard_capacity=0,   # 0 = single large shard
    default_top_k=5,
    score_threshold=0.0,
    margin_ratio=1.02,
    use_gpu=False,
)
```

---

## How It Works

1. **Bind** — `key` and `value` are encoded to constant-modulus complex vectors, then bound via element-wise multiplication: `key * value`.
2. **Superpose** — all bindings are summed into a single memory vector.
3. **Retrieve** — the query is multiplied by the conjugate of the memory. Matching keys resonate (constructive interference) and surface their bound values; non-matches cancel out (destructive interference).

---

## Running the Benchmark

```bash
pip install -e .
python examples/evaluate.py
```

---

## License

MIT — see [LICENSE](LICENSE).
