SKILL.md

---
name: quantum-agent-memory
title: Quantum Agent Memory
description: "QAOA-powered memory optimization for AI agents. Three quantum layers: clustering, compaction, and recall. Integrates with QMG v1.2 for chunked gte-large retrieval. Uses Qiskit for IBM Quantum hardware."
tags: [quantum, qaoa, memory, agents, qiskit, ibm, compaction, clustering, retrieval]
---

# Quantum Agent Memory

QAOA-powered memory management for AI agents. Three quantum layers replace classical heuristics for clustering, compaction, and recall.

**Companion to [Quantum Memory Graph (QMG) v1.2](https://clawhub.ai/dustin-a11y/quantum-memory)** — #1 on LongMemEval (98.6% R@5).

## Three Quantum Layers

### Layer 1: Clustering
Group N memories into coherent clusters via balanced graph-cut QAOA.

- Cost matrix: temporal (25%), relational (30%), categorical (25%), recency (20%)
- 100% optimal for n≤14, speed crossover at n=20

### Layer 2: Compaction
Select optimal K memories to keep from M total.

- Maximizes coverage + coherence + value + recency with budget penalty
- Beats greedy selection by ~1% consistently

### Layer 3: Recall
Find the best K memories for a query — optimizes for synergy, not just individual relevance.

- Finds memory combinations that Top-K similarity search misses
- Individual relevance (40%) + pairwise synergy (30%) + diversity (20%) + recency (10%)

## 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
```

## Integration with QMG v1.2

Point the benchmark at a live QMG instance:

```bash
python -m quantum_agent_memory benchmark --qmg-url http://localhost:8503
```

For OpenClaw agent integration, see `references/openclaw-plugin.md`.

## IBM Quantum Hardware

Submit circuits to real IBM quantum processors:

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

## Benchmarking

Run the full 3-layer benchmark:

```bash
python -m quantum_agent_memory benchmark
```

Expected output:
- **Clustering**: ~98-100% optimal
- **Compaction**: 100% optimal
- **Recall**: 100% optimal, quantum finds synergistic combos Top-K misses
- **Avg accuracy**: ~99.7%

## Requirements

- Python 3.10+
- Qiskit 2.0+
- qiskit-aer (simulation)
- numpy

Optional:
- qiskit-ibm-runtime (real hardware)
- sentence-transformers (embeddings)