quantum-agent-memory 0.1.0

QAOA-powered memory management for AI agents — clustering, compaction, and recall

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

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 instance running, point the benchmark at it:

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
2. Copy your API token from Account Settings
3. Run:

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:

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:

python scripts/quantum_api.py

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 (free — 10 min QPU/month)
2. Copy your API token from Account Settings
3. Save it:

export IBM_QUANTUM_TOKEN="your-token-here"

Submit to real hardware

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:

# 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