quantum-memory-graph 1.1.0__tar.gz → 1.2.0__tar.gz

quantum_memory_graph-1.2.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: quantum-memory-graph
+Version: 1.2.0
+Summary: Quantum-optimized knowledge graph memory for AI agents. Relationship-aware subgraph selection via QAOA.
+Home-page: https://github.com/Dustin-a11y/quantum-memory-graph
+Author: Coinkong (Chef's Attraction)
+License: MIT
+Keywords: quantum,memory,knowledge-graph,agents,qaoa,ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: quantum-agent-memory>=0.1.0
+Requires-Dist: sentence-transformers>=2.2.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: qiskit>=1.0.0
+Requires-Dist: qiskit-aer>=0.13.0
+Provides-Extra: api
+Requires-Dist: fastapi>=0.100.0; extra == "api"
+Requires-Dist: uvicorn>=0.20.0; extra == "api"
+Provides-Extra: ibm
+Requires-Dist: qiskit-ibm-runtime>=0.20.0; extra == "ibm"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# Quantum Memory Graph ⚛️🧠
+
+**Relationship-aware memory for AI agents. Knowledge graphs + quantum-optimized subgraph selection.**
+
+Every memory system treats memories as independent documents — search, rank, stuff into context. But memories aren't independent. They have *relationships*. "The team chose React" becomes 10x more useful paired with "because of ecosystem maturity" and "FastAPI handles the backend."
+
+Quantum Memory Graph maps these relationships, then uses QAOA to find the optimal *combination* of memories — not just the most relevant individuals, but the best connected subgraph that gives your agent maximum context.
+
+## Benchmark: MemCombine
+
+We created MemCombine to test what no existing benchmark measures — **memory combination quality**.
+
+| Method | Coverage | Evidence Recall | F1 | Perfect |
+|--------|----------|----------------|----|---------|
+| Embedding Top-K | 69.9% | 65.6% | 68.1% | 1/5 |
+| **Graph + QAOA** | **96.7%** | **91.0%** | **92.6%** | **4/5** |
+| **Advantage** | **+26.8%** | **+25.4%** | **+24.5%** | |
+
+When the task is "find memories that work *together*," graph-aware quantum selection crushes pure similarity search.
+## 🏆 #1 on LongMemEval (ICLR 2025 Benchmark)
+
+Tested on the official [LongMemEval benchmark](https://arxiv.org/abs/2410.10813) for long-term memory in AI agents:
+
+| Method | R@1 | R@5 | R@10 | NDCG@10 |
+|--------|:---:|:---:|:----:|:-------:|
+| OMEGA (prev SOTA) | — | 89.2% | 94.1% | 87.5% |
+| Mastra OM | — | 91.0% | 95.2% | 89.1% |
+| **QMG v1.1 (published #1)** | — | **95.8%** | **98.85%** | **93.2%** |
+| **QMG v1.2 (official, this repo)** 🏆 | **90.6%** | **98.6%** | **99.4%** | **0.9426** |
+
+**Benchmark run:** 500 questions, chunked gte-large embeddings (500-char blocks, 100-char overlap, mean-of-top-3 session scoring). Verified on DGX Spark GB10 (CUDA, ~53 min).
+
+**Chunking technique:** Each session split into overlapping 500-char chunks → gte-large embedding → per-session score = mean of top-3 chunk scores → rank by score. This recovers the v7 methodology that achieved our original #1, now verified with a clean reproducible pipeline.
+
+**See:** `benchmarks/run_longmemeval_chunked_staged.py` for the exact benchmark code, `benchmarks/longmemeval_chunked_staged_results.json` for full per-question results.
+
+
+## Install
+
+```bash
+pip install quantum-memory-graph
+```
+
+## Quick Start
+
+```python
+from quantum_memory_graph import store, recall
+
+# Store memories — automatically builds knowledge graph
+store("Project Alpha uses React frontend with TypeScript.")
+store("Project Alpha backend is FastAPI with PostgreSQL.")
+store("FastAPI connects to PostgreSQL via SQLAlchemy ORM.")
+store("React components use Material UI for styling.")
+store("Team had pizza for lunch. Pepperoni was great.")
+
+# Recall — graph traversal + QAOA finds the optimal combination
+result = recall("What is Project Alpha's full tech stack?", K=4)
+
+for memory in result["memories"]:
+    print(f"  {memory['text']}")
+    print(f"    Connected to {len(memory['connections'])} other selected memories")
+```
+
+Output: Returns React, FastAPI, PostgreSQL, and SQLAlchemy memories — connected, complete, no noise. The pizza memory is excluded because it has no graph connections to the tech stack cluster.
+
+## How It Works
+
+```
+Query: "What's the tech stack?"
+        │
+        ▼
+┌─────────────────────┐
+│  1. Graph Search     │  Embedding similarity + multi-hop traversal
+│     Find neighbors   │  Discovers memories connected to relevant ones
+└────────┬────────────┘
+         │ 14 candidates
+         ▼
+┌─────────────────────┐
+│  2. Subgraph Data    │  Extract adjacency matrix + relevance scores
+│     Build problem    │  Encode relationships as optimization weights
+└────────┬────────────┘
+         │ NP-hard selection
+         ▼
+┌─────────────────────┐
+│  3. QAOA Optimize    │  Quantum approximate optimization
+│     Find best K      │  Maximizes: relevance + connectivity + coverage
+└────────┬────────────┘
+         │ K memories
+         ▼
+┌─────────────────────┐
+│  4. Return with      │  Each memory includes its connections
+│     relationships    │  to other selected memories
+└─────────────────────┘
+```
+
+### Why Quantum?
+
+Optimal subgraph selection is NP-hard. Given N candidate memories, finding the best K that maximize relevance, connectivity, AND coverage has exponential classical complexity. QAOA provides polynomial-time approximate solutions that beat greedy heuristics — this is the one problem where quantum computing has a genuine algorithmic advantage over classical approaches.
+
+## Architecture
+
+### Three Layers
+
+1. **Knowledge Graph** (`graph.py`) — Memories are nodes. Relationships are weighted edges based on:
+   - Semantic similarity (embedding cosine distance)
+   - Entity co-occurrence (shared people, projects, concepts)
+   - Temporal proximity (memories close in time)
+   - Source proximity (same conversation/document)
+
+2. **Subgraph Optimizer** (`subgraph_optimizer.py`) — QAOA circuit that maximizes:
+   - α × relevance (individual memory scores)
+   - β × connectivity (edge weights within selected subgraph)
+   - γ × coverage (topic diversity across selection)
+
+3. **Pipeline** (`pipeline.py`) — Unified `store()` and `recall()` interface.
+
+```
+
+## API Server
+
+```bash
+pip install quantum-memory-graph[api]
+python -m quantum_memory_graph.api
+```
+
+Endpoints:
+- `POST /store` — Store a memory
+- `POST /recall` — Graph + QAOA recall
+- `POST /store-batch` — Batch store
+- `GET /stats` — Graph statistics
+- `GET /` — Health check
+
+## Advanced Usage
+
+### Custom Graph
+
+```python
+from quantum_memory_graph import MemoryGraph, recall
+from quantum_memory_graph.pipeline import set_graph
+
+# Tune similarity threshold for edge creation
+graph = MemoryGraph(similarity_threshold=0.25)
+set_graph(graph)
+
+# Store and recall as normal
+```
+
+### Tune QAOA Parameters
+
+```python
+result = recall(
+    "query",
+    K=5,
+    alpha=0.4,       # Relevance weight
+    beta_conn=0.35,   # Connectivity weight  
+    gamma_cov=0.25,   # Coverage/diversity weight
+    hops=3,           # Graph traversal depth
+    top_seeds=7,      # Initial seed nodes
+    max_candidates=14, # Max qubits for QAOA
+)
+```
+
+### Run MemCombine Benchmark
+
+```python
+from benchmarks.memcombine import run_benchmark
+
+def my_recall(memories, query, K):
+    # Your recall implementation
+    return selected_indices  # List[int]
+
+results = run_benchmark(my_recall, K=5)
+print(f"Coverage: {results['avg_coverage']*100:.1f}%")
+```
+
+## IBM Quantum Hardware
+
+For production workloads, run QAOA on real quantum hardware:
+
+```bash
+pip install quantum-memory-graph[ibm]
+export IBM_QUANTUM_TOKEN=your_token
+```
+
+Validated on `ibm_fez` and `ibm_kingston` backends.
+
+## Requirements
+
+- Python ≥ 3.9
+- sentence-transformers
+- networkx
+- qiskit + qiskit-aer
+- numpy
+
+## License
+
+MIT License — Copyright 2026 Coinkong (Chef's Attraction)
+
+
+## Links
+
+- [quantum-agent-memory](https://github.com/Dustin-a11y/quantum-agent-memory) — The QAOA optimization engine
+- [MemCombine Benchmark](benchmarks/memcombine.py) — Test memory combination quality

quantum_memory_graph-1.2.0/README.md

@@ -0,0 +1,203 @@
+# Quantum Memory Graph ⚛️🧠
+
+**Relationship-aware memory for AI agents. Knowledge graphs + quantum-optimized subgraph selection.**
+
+Every memory system treats memories as independent documents — search, rank, stuff into context. But memories aren't independent. They have *relationships*. "The team chose React" becomes 10x more useful paired with "because of ecosystem maturity" and "FastAPI handles the backend."
+
+Quantum Memory Graph maps these relationships, then uses QAOA to find the optimal *combination* of memories — not just the most relevant individuals, but the best connected subgraph that gives your agent maximum context.
+
+## Benchmark: MemCombine
+
+We created MemCombine to test what no existing benchmark measures — **memory combination quality**.
+
+| Method | Coverage | Evidence Recall | F1 | Perfect |
+|--------|----------|----------------|----|---------|
+| Embedding Top-K | 69.9% | 65.6% | 68.1% | 1/5 |
+| **Graph + QAOA** | **96.7%** | **91.0%** | **92.6%** | **4/5** |
+| **Advantage** | **+26.8%** | **+25.4%** | **+24.5%** | |
+
+When the task is "find memories that work *together*," graph-aware quantum selection crushes pure similarity search.
+## 🏆 #1 on LongMemEval (ICLR 2025 Benchmark)
+
+Tested on the official [LongMemEval benchmark](https://arxiv.org/abs/2410.10813) for long-term memory in AI agents:
+
+| Method | R@1 | R@5 | R@10 | NDCG@10 |
+|--------|:---:|:---:|:----:|:-------:|
+| OMEGA (prev SOTA) | — | 89.2% | 94.1% | 87.5% |
+| Mastra OM | — | 91.0% | 95.2% | 89.1% |
+| **QMG v1.1 (published #1)** | — | **95.8%** | **98.85%** | **93.2%** |
+| **QMG v1.2 (official, this repo)** 🏆 | **90.6%** | **98.6%** | **99.4%** | **0.9426** |
+
+**Benchmark run:** 500 questions, chunked gte-large embeddings (500-char blocks, 100-char overlap, mean-of-top-3 session scoring). Verified on DGX Spark GB10 (CUDA, ~53 min).
+
+**Chunking technique:** Each session split into overlapping 500-char chunks → gte-large embedding → per-session score = mean of top-3 chunk scores → rank by score. This recovers the v7 methodology that achieved our original #1, now verified with a clean reproducible pipeline.
+
+**See:** `benchmarks/run_longmemeval_chunked_staged.py` for the exact benchmark code, `benchmarks/longmemeval_chunked_staged_results.json` for full per-question results.
+
+
+## Install
+
+```bash
+pip install quantum-memory-graph
+```
+
+## Quick Start
+
+```python
+from quantum_memory_graph import store, recall
+
+# Store memories — automatically builds knowledge graph
+store("Project Alpha uses React frontend with TypeScript.")
+store("Project Alpha backend is FastAPI with PostgreSQL.")
+store("FastAPI connects to PostgreSQL via SQLAlchemy ORM.")
+store("React components use Material UI for styling.")
+store("Team had pizza for lunch. Pepperoni was great.")
+
+# Recall — graph traversal + QAOA finds the optimal combination
+result = recall("What is Project Alpha's full tech stack?", K=4)
+
+for memory in result["memories"]:
+    print(f"  {memory['text']}")
+    print(f"    Connected to {len(memory['connections'])} other selected memories")
+```
+
+Output: Returns React, FastAPI, PostgreSQL, and SQLAlchemy memories — connected, complete, no noise. The pizza memory is excluded because it has no graph connections to the tech stack cluster.
+
+## How It Works
+
+```
+Query: "What's the tech stack?"
+        │
+        ▼
+┌─────────────────────┐
+│  1. Graph Search     │  Embedding similarity + multi-hop traversal
+│     Find neighbors   │  Discovers memories connected to relevant ones
+└────────┬────────────┘
+         │ 14 candidates
+         ▼
+┌─────────────────────┐
+│  2. Subgraph Data    │  Extract adjacency matrix + relevance scores
+│     Build problem    │  Encode relationships as optimization weights
+└────────┬────────────┘
+         │ NP-hard selection
+         ▼
+┌─────────────────────┐
+│  3. QAOA Optimize    │  Quantum approximate optimization
+│     Find best K      │  Maximizes: relevance + connectivity + coverage
+└────────┬────────────┘
+         │ K memories
+         ▼
+┌─────────────────────┐
+│  4. Return with      │  Each memory includes its connections
+│     relationships    │  to other selected memories
+└─────────────────────┘
+```
+
+### Why Quantum?
+
+Optimal subgraph selection is NP-hard. Given N candidate memories, finding the best K that maximize relevance, connectivity, AND coverage has exponential classical complexity. QAOA provides polynomial-time approximate solutions that beat greedy heuristics — this is the one problem where quantum computing has a genuine algorithmic advantage over classical approaches.
+
+## Architecture
+
+### Three Layers
+
+1. **Knowledge Graph** (`graph.py`) — Memories are nodes. Relationships are weighted edges based on:
+   - Semantic similarity (embedding cosine distance)
+   - Entity co-occurrence (shared people, projects, concepts)
+   - Temporal proximity (memories close in time)
+   - Source proximity (same conversation/document)
+
+2. **Subgraph Optimizer** (`subgraph_optimizer.py`) — QAOA circuit that maximizes:
+   - α × relevance (individual memory scores)
+   - β × connectivity (edge weights within selected subgraph)
+   - γ × coverage (topic diversity across selection)
+
+3. **Pipeline** (`pipeline.py`) — Unified `store()` and `recall()` interface.
+
+```
+
+## API Server
+
+```bash
+pip install quantum-memory-graph[api]
+python -m quantum_memory_graph.api
+```
+
+Endpoints:
+- `POST /store` — Store a memory
+- `POST /recall` — Graph + QAOA recall
+- `POST /store-batch` — Batch store
+- `GET /stats` — Graph statistics
+- `GET /` — Health check
+
+## Advanced Usage
+
+### Custom Graph
+
+```python
+from quantum_memory_graph import MemoryGraph, recall
+from quantum_memory_graph.pipeline import set_graph
+
+# Tune similarity threshold for edge creation
+graph = MemoryGraph(similarity_threshold=0.25)
+set_graph(graph)
+
+# Store and recall as normal
+```
+
+### Tune QAOA Parameters
+
+```python
+result = recall(
+    "query",
+    K=5,
+    alpha=0.4,       # Relevance weight
+    beta_conn=0.35,   # Connectivity weight  
+    gamma_cov=0.25,   # Coverage/diversity weight
+    hops=3,           # Graph traversal depth
+    top_seeds=7,      # Initial seed nodes
+    max_candidates=14, # Max qubits for QAOA
+)
+```
+
+### Run MemCombine Benchmark
+
+```python
+from benchmarks.memcombine import run_benchmark
+
+def my_recall(memories, query, K):
+    # Your recall implementation
+    return selected_indices  # List[int]
+
+results = run_benchmark(my_recall, K=5)
+print(f"Coverage: {results['avg_coverage']*100:.1f}%")
+```
+
+## IBM Quantum Hardware
+
+For production workloads, run QAOA on real quantum hardware:
+
+```bash
+pip install quantum-memory-graph[ibm]
+export IBM_QUANTUM_TOKEN=your_token
+```
+
+Validated on `ibm_fez` and `ibm_kingston` backends.
+
+## Requirements
+
+- Python ≥ 3.9
+- sentence-transformers
+- networkx
+- qiskit + qiskit-aer
+- numpy
+
+## License
+
+MIT License — Copyright 2026 Coinkong (Chef's Attraction)
+
+
+## Links
+
+- [quantum-agent-memory](https://github.com/Dustin-a11y/quantum-agent-memory) — The QAOA optimization engine
+- [MemCombine Benchmark](benchmarks/memcombine.py) — Test memory combination quality

quantum_memory_graph-1.2.0/benchmarks/data_collector.py

@@ -0,0 +1,209 @@
+"""
+QMG Benchmark Data Collector.
+
+Logs every benchmark run with full metadata for study and analysis.
+Data is append-only, timestamped, and structured for easy analysis.
+
+DK 🦍
+
+Usage:
+    from benchmarks.data_collector import QMGBenchmarkLogger
+    
+    logger = QMGBenchmarkLogger()
+    logger.log_memcombine_run(method, results, params)
+    logger.log_qaoa_run(n_candidates, n_qubits, selection_result, timing)
+    logger.export_csv()  # Export all data for study
+"""
+
+import json
+import os
+import time
+from datetime import datetime
+from typing import Dict, List, Optional
+from pathlib import Path
+
+
+BENCHMARK_LOG_DIR = Path(os.environ.get(
+    "QMG_BENCHMARK_LOG", 
+    "/home/dt/.hermes/profiles/dk/quantum-tracker/benchmarks"
+))
+
+
+class QMGBenchmarkLogger:
+    """Append-only benchmark data logger."""
+    
+    def __init__(self, log_dir: str = None):
+        self.log_dir = Path(log_dir) if log_dir else BENCHMARK_LOG_DIR
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+        self._session_id = f"session_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+    
+    def log_memcombine_run(self, method: str, results: Dict, params: Dict = None):
+        """Log a MemCombine benchmark run."""
+        entry = {
+            "type": "memcombine_run",
+            "session_id": self._session_id,
+            "timestamp": datetime.now().isoformat(),
+            "unix_time": time.time(),
+            "method": method,
+            "results": {
+                "coverage": results.get("avg_coverage", results.get("coverage")),
+                "evidence_recall": results.get("avg_evidence_recall", results.get("evidence_recall")),
+                "f1": results.get("avg_f1", results.get("f1")),
+                "perfect": results.get("perfect_coverage", results.get("perfect")),
+                "perfect_pct": results.get("perfect_coverage_pct", results.get("perfect_pct")),
+                "n_scenarios": results.get("n_scenarios", len(results.get("per_scenario", []))),
+            },
+            "params": params or {},
+            "per_scenario": results.get("per_scenario", []),
+        }
+        self._write("memcombine", entry)
+        return entry
+    
+    def log_longmemeval_run(self, method: str, results: Dict, model: str = None, params: Dict = None):
+        """Log a LongMemEval benchmark run."""
+        entry = {
+            "type": "longmemeval_run",
+            "session_id": self._session_id,
+            "timestamp": datetime.now().isoformat(),
+            "unix_time": time.time(),
+            "model": model or "unknown",
+            "method": method,
+            "results": {
+                "recall_at_5": results.get("recall_at_5"),
+                "recall_at_10": results.get("recall_at_10"),
+                "ndcg_at_10": results.get("ndcg_at_10"),
+                "n": results.get("n"),
+            },
+            "params": params or {},
+        }
+        self._write("longmemeval", entry)
+        return entry
+    
+    def log_qaoa_run(self, 
+                      n_candidates: int, 
+                      n_qubits: int, 
+                      K: int,
+                      p_layers: int,
+                      method: str,
+                      selection_result: Dict,
+                      timing_ms: float,
+                      params: Dict = None):
+        """Log a single QAOA optimization run."""
+        entry = {
+            "type": "qaoa_run",
+            "session_id": self._session_id,
+            "timestamp": datetime.now().isoformat(),
+            "unix_time": time.time(),
+            "n_candidates": n_candidates,
+            "n_qubits": n_qubits,
+            "K": K,
+            "p_layers": p_layers,
+            "method": method,
+            "compression_ratio": selection_result.get("compression_ratio", f"{n_candidates}→{n_qubits}"),
+            "qaoa_score": selection_result.get("score"),
+            "qaoa_vs_greedy_pct": selection_result.get("qaoa_vs_greedy_pct"),
+            "qaoa_vs_optimal_pct": selection_result.get("qaoa_vs_optimal_pct"),
+            "timing_ms": timing_ms,
+            "params": params or {},
+        }
+        self._write("qaoa", entry)
+        return entry
+    
+    def log_graph_stats(self, graph_stats: Dict, tag: str = ""):
+        """Log memory graph statistics."""
+        entry = {
+            "type": "graph_stats",
+            "session_id": self._session_id,
+            "timestamp": datetime.now().isoformat(),
+            "unix_time": time.time(),
+            "tag": tag,
+            "nodes": graph_stats.get("nodes"),
+            "edges": graph_stats.get("edges"),
+            "density": graph_stats.get("density"),
+            "components": graph_stats.get("components"),
+            "avg_degree": graph_stats.get("avg_degree"),
+        }
+        self._write("graph", entry)
+        return entry
+    
+    def log_hardware_run(self, backend: str, n_qubits: int, result: Dict, timing_ms: float):
+        """Log a hardware execution run (IBM Quantum)."""
+        entry = {
+            "type": "hardware_run",
+            "session_id": self._session_id,
+            "timestamp": datetime.now().isoformat(),
+            "unix_time": time.time(),
+            "backend": backend,
+            "n_qubits": n_qubits,
+            "result": {
+                "score": result.get("score"),
+                "method": result.get("method"),
+                "error_mitigation": result.get("error_mitigation", "none"),
+            },
+            "timing_ms": timing_ms,
+        }
+        self._write("hardware", entry)
+        return entry
+    
+    def _write(self, category: str, entry: Dict):
+        """Append entry to category log file."""
+        log_file = self.log_dir / f"{category}_log.jsonl"
+        with open(log_file, "a") as f:
+            f.write(json.dumps(entry) + "\n")
+    
+    def export_csv(self, category: str = None) -> str:
+        """
+        Export logged data as CSV for analysis.
+        Returns path to CSV file.
+        """
+        import csv
+        from collections import OrderedDict
+        
+        categories = [category] if category else ["memcombine", "longmemeval", "qaoa", "graph", "hardware"]
+        output_paths = []
+        
+        for cat in categories:
+            log_file = self.log_dir / f"{cat}_log.jsonl"
+            if not log_file.exists():
+                continue
+            
+            csv_path = self.log_dir / f"{cat}_export.csv"
+            entries = []
+            with open(log_file) as f:
+                for line in f:
+                    line = line.strip()
+                    if line:
+                        entries.append(json.loads(line))
+            
+            if not entries:
+                continue
+            
+            # Gather all keys
+            all_keys = []
+            for e in entries:
+                for k in e.keys():
+                    if k not in all_keys:
+                        all_keys.append(k)
+            
+            with open(csv_path, "w", newline="") as f:
+                writer = csv.DictWriter(f, fieldnames=all_keys, extrasaction="ignore")
+                writer.writeheader()
+                for e in entries:
+                    writer.writerow(e)
+            
+            output_paths.append(str(csv_path))
+        
+        return ", ".join(output_paths) if output_paths else "No data logged yet"
+    
+    def summary(self) -> Dict:
+        """Quick summary of all logged data."""
+        result = {}
+        for cat in ["memcombine", "longmemeval", "qaoa", "graph", "hardware"]:
+            log_file = self.log_dir / f"{cat}_log.jsonl"
+            if log_file.exists():
+                with open(log_file) as f:
+                    lines = [l for l in f if l.strip()]
+                result[cat] = len(lines)
+            else:
+                result[cat] = 0
+        return result