Metadata-Version: 2.1
Name: quantum-agent-memory
Version: 0.1.0
Summary: QAOA-powered memory management for AI agents — clustering, compaction, and recall
Author: Coinkong (Chef's Attraction)
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: qiskit>=2.0
Requires-Dist: qiskit-aer>=0.15
Requires-Dist: numpy
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: ibm
Requires-Dist: qiskit-ibm-runtime; extra == "ibm"
Provides-Extra: mem0
Requires-Dist: requests; extra == "mem0"

# Quantum Agent Memory

**QAOA-powered memory management for AI agents.** Uses the Quantum Approximate Optimization Algorithm to solve three fundamental memory operations — clustering, compaction, and recall — as combinatorial optimization problems on quantum circuits. Runs on the Qiskit Aer simulator out of the box; optionally submits to IBM Quantum hardware.

## What It Does

| Layer | Problem | Formulation |
|-------|---------|-------------|
| **1. Clustering** | Group memories into semantically coherent clusters | Balanced graph cut via QAOA — 4-dimension cost matrix (temporal, relational, categorical, recency) |
| **2. Compaction** | Select optimal K memories to keep from M total | Subset selection with budget constraint penalty — maximizes coverage, coherence, value, and recency |
| **3. Recall** | Find the best combination of K memories for a query | Context-aware selection — individual relevance + pairwise synergy + diversity + recency |

Each layer compares QAOA against classical baselines (brute-force, greedy, top-K) and reports approximation ratios.

## Requirements

- Python 3.10+
- Qiskit 2.0+, Qiskit Aer 0.15+, NumPy

## Quick Start

```bash
git clone https://github.com/Dustin-a11y/quantum-agent-memory.git
cd quantum-agent-memory
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python -m quantum_agent_memory benchmark
```

## Expected Output

```
╔══════════════════════════════════════════════════╗
║  QUANTUM AGENT MEMORY — BENCHMARK REPORT        ║
╠══════════════════════════════════════════════════╣
║  Layer 1: Clustering                             ║
║    n= 8: Quantum ~100%  optimal  [0.9s]          ║
║    n=10: Quantum ~95-100% optimal [1.8s]         ║
║    n=12: Quantum ~92-100% optimal [2.5s]         ║
║  Layer 2: Compaction                             ║
║    M=10,K=5: Quantum ~100% optimal              ║
║    M=12,K=6: Quantum ~100% optimal              ║
║  Layer 3: Recall                                 ║
║    Query 1: Quantum ~100% | Top-K  ~95%         ║
║    Query 2: Quantum ~99%  | Top-K  ~93%         ║
║  Summary: Avg accuracy ~98%, 3 layers tested     ║
╚══════════════════════════════════════════════════╝
```

Results are also saved as JSON to `results/benchmark_TIMESTAMP.json`.

## Optional: Live Mem0 Integration

If you have a [Mem0](https://github.com/mem0ai/mem0) instance running, point the benchmark at it:

```bash
pip install requests
python -m quantum_agent_memory benchmark --mem0-url http://localhost:8500
```

This fetches real agent memories instead of using the bundled demo data.

## Optional: IBM Quantum Hardware

To run on real quantum processors (free tier: 10 min/month):

1. Sign up at [quantum.ibm.com](https://quantum.ibm.com)
2. Copy your API token from Account Settings
3. Run:

```bash
pip install qiskit-ibm-runtime
python -m quantum_agent_memory submit --ibm-token YOUR_TOKEN
```

This transpiles and submits all 3 circuit types to the least-busy IBM backend.

## Project Structure

```
quantum_agent_memory/
├── __init__.py          # Package metadata
├── __main__.py          # CLI entry point
├── cost_function.py     # 4-dimension cost matrix builder
├── clustering.py        # Layer 1: QAOA balanced graph-cut clustering
├── compaction.py        # Layer 2: QAOA subset selection with budget penalty
├── recall.py            # Layer 3: QAOA context-aware memory retrieval
├── benchmark.py         # Full 3-layer benchmark runner
└── demo_data.py         # 20 synthetic test memories
```

## Use in Any Agent Framework

The quantum memory system is a standalone Python library — no OpenClaw dependency. Call it from any agent, any framework:

```python
from quantum_agent_memory.recall import run_recall
from quantum_agent_memory.compaction import run_compaction
from quantum_agent_memory.clustering import run_clustering

# Your memories — any list of dicts with a "memory" key
memories = [
    {"memory": "User prefers dark mode", "agent_id": "assistant"},
    {"memory": "Project deadline is Friday", "agent_id": "planner"},
    {"memory": "API key rotated on March 1", "agent_id": "security"},
    # ... more memories
]

# Quantum recall — find best K memories for a query
result = run_recall(memories, query="What's the project status?", K=3)
print(result["selected"])  # Optimal memory combination via QAOA

# Quantum compaction — pick K best memories to keep
result = run_compaction(memories, K=5)
print(result["keep"])      # Memories to retain
print(result["archive"])   # Memories safe to archive

# Quantum clustering — group related memories
result = run_clustering(memories)
print(result["clusters"])  # Grouped by semantic similarity
```

### REST API

Or run the API server and call it over HTTP from any language:

```bash
python scripts/quantum_api.py
```

```bash
curl -X POST http://localhost:8501/quantum-recall \
  -H "Content-Type: application/json" \
  -d '{"query": "project status", "k": 3}'
```

Works with LangChain, CrewAI, AutoGen, OpenClaw, or any agent framework that can make HTTP calls or import Python.

## How It Works

### Cost Function (Shared)

All three layers build on a **4-dimension pairwise cost matrix**:

1. **Temporal coherence** (25%) — memories close in time cluster together
2. **Relational coherence** (30%) — shared entities/words (Jaccard similarity)
3. **Categorical coherence** (25%) — same agent, source, or batch
4. **Recency weighting** (20%) — newer memories prioritized

### QAOA Encoding

- Each memory maps to one qubit
- Cost terms encode as ZZ interactions in the problem Hamiltonian
- Budget/balance constraints use quadratic penalty terms
- Grid search over (γ, β) parameters; p=1 QAOA depth
- Measured bitstrings decoded as memory assignments

## License

MIT — Copyright 2026 Coinkong (Chef's Attraction)

## Running on Real Quantum Hardware

By default, the benchmark runs on the Qiskit Aer simulator (free, local, perfect results). To run on **real IBM quantum processors**:

### Setup (one time)
1. Sign up at [quantum.ibm.com](https://quantum.ibm.com) (free — 10 min QPU/month)
2. Copy your API token from Account Settings
3. Save it:
```bash
export IBM_QUANTUM_TOKEN="your-token-here"
```

### Submit to real hardware
```bash
python -m quantum_agent_memory submit --ibm-token $IBM_QUANTUM_TOKEN
```

### Scheduled hardware runs
For ongoing real-hardware data collection, set up a cron job:
```bash
# Run 10x daily on real IBM quantum hardware
crontab -e
# Add: 0 0,2,5,7,10,12,14,17,19,22 * * * python /path/to/quantum_agent_memory/ibm_cron.py
```

### QPU Budget
- Free tier: 10 minutes/month
- Each run uses ~1 second of QPU time
- 10 runs/day = ~5 minutes/month (50% of free budget)
- Plenty of room for experimentation

### Why real hardware matters
- Simulator gives perfect results; real hardware has noise
- Real hardware data validates your quantum advantage claims
- IBM job IDs are timestamped proof of quantum computing usage
- Accumulating real-hardware results builds your quantum portfolio
