quantum-memory-graph 0.1.0__tar.gz

quantum-memory-graph-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Coinkong (Chef's Attraction)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quantum-memory-graph-0.1.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.1
+Name: quantum-memory-graph
+Version: 0.1.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 :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: api
+Provides-Extra: ibm
+Provides-Extra: dev
+License-File: LICENSE
+
+# 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.
+
+## 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.
+
+### Optional: MemPalace Integration
+
+Use [MemPalace](https://github.com/milla-jovovich/mempalace) (MIT, by @bensig) as the storage/retrieval backend for 96.6% base retrieval quality:
+
+```python
+from quantum_memory_graph.mempalace_bridge import store_memory, recall_memories
+
+# MemPalace stores verbatim → ChromaDB retrieves candidates → QAOA selects optimal subgraph
+result = recall_memories("What happened in the meeting?", K=5, use_qaoa=True)
+```
+
+## 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)
+
+Built with [MemPalace](https://github.com/milla-jovovich/mempalace) by @bensig (MIT License). See [THIRD-PARTY-LICENSES](THIRD-PARTY-LICENSES).
+
+## Links
+
+- [quantum-agent-memory](https://github.com/Dustin-a11y/quantum-agent-memory) — The QAOA optimization engine
+- [MemPalace](https://github.com/milla-jovovich/mempalace) — Storage and retrieval backend
+- [MemCombine Benchmark](benchmarks/memcombine.py) — Test memory combination quality

quantum-memory-graph-0.1.0/README.md

@@ -0,0 +1,197 @@
+# 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.
+
+## 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.
+
+### Optional: MemPalace Integration
+
+Use [MemPalace](https://github.com/milla-jovovich/mempalace) (MIT, by @bensig) as the storage/retrieval backend for 96.6% base retrieval quality:
+
+```python
+from quantum_memory_graph.mempalace_bridge import store_memory, recall_memories
+
+# MemPalace stores verbatim → ChromaDB retrieves candidates → QAOA selects optimal subgraph
+result = recall_memories("What happened in the meeting?", K=5, use_qaoa=True)
+```
+
+## 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)
+
+Built with [MemPalace](https://github.com/milla-jovovich/mempalace) by @bensig (MIT License). See [THIRD-PARTY-LICENSES](THIRD-PARTY-LICENSES).
+
+## Links
+
+- [quantum-agent-memory](https://github.com/Dustin-a11y/quantum-agent-memory) — The QAOA optimization engine
+- [MemPalace](https://github.com/milla-jovovich/mempalace) — Storage and retrieval backend
+- [MemCombine Benchmark](benchmarks/memcombine.py) — Test memory combination quality

quantum-memory-graph-0.1.0/benchmarks/__init__.py

@@ -0,0 +1 @@
+"""MemCombine benchmark suite."""

quantum-memory-graph-0.1.0/benchmarks/memcombine.py

@@ -0,0 +1,236 @@
+"""
+MemCombine Benchmark — Tests memory COMBINATION quality.
+
+Unlike LongMemEval (needle-in-haystack retrieval), MemCombine tests whether
+selected memories work TOGETHER to answer complex questions.
+
+Questions require synthesizing information from multiple memories:
+  - "What was the decision AND its reasoning AND its outcome?"
+  - "How do project X and project Y relate?"
+  - "What changed between meeting A and meeting B?"
+
+Metrics:
+  - Combination Score: Do selected memories cover all required facets?
+  - Synergy Score: Do memories reference/build on each other?
+  - Completeness: Can the question be fully answered from selected memories?
+
+Copyright 2026 Coinkong (Chef's Attraction). MIT License.
+"""
+
+import json
+import numpy as np
+from typing import List, Dict
+from dataclasses import dataclass, field
+
+
+@dataclass
+class MemCombineQuestion:
+    """A question requiring multiple related memories."""
+    id: str
+    question: str
+    category: str  # synthesis, temporal, causal, multi-entity
+    memories: List[Dict]  # All available memories
+    evidence_ids: List[int]  # Which memories contain evidence
+    facets: List[str]  # Required information facets
+    facet_memory_map: Dict  # Which facet comes from which memory
+
+
+# Built-in benchmark scenarios
+SCENARIOS = [
+    {
+        "id": "synthesis_1",
+        "question": "What technology stack was chosen for the project and why was each component selected?",
+        "category": "synthesis",
+        "memories": [
+            {"id": 0, "text": "Team meeting: Decided to use React for the frontend. Sarah argued it has the best ecosystem for our use case."},
+            {"id": 1, "text": "Architecture review: PostgreSQL chosen for the database. Need JSONB support for flexible schemas."},
+            {"id": 2, "text": "Sprint planning: Set up CI/CD pipeline using GitHub Actions. Two-week sprint cycles."},
+            {"id": 3, "text": "Team lunch at the Italian place. Good pasta. Bob told a funny joke about recursion."},
+            {"id": 4, "text": "Backend discussion: FastAPI selected over Django. Need async support for real-time features."},
+            {"id": 5, "text": "Deployment strategy: Going with Docker + Kubernetes on AWS. Auto-scaling is critical for launch."},
+            {"id": 6, "text": "Budget review: Cloud costs estimated at $2000/month. Within budget allocation."},
+            {"id": 7, "text": "Coffee chat about the new office layout. Open floor plan vs cubicles debate."},
+            {"id": 8, "text": "Performance testing results: FastAPI handles 10K concurrent connections. Meets our requirements."},
+            {"id": 9, "text": "Security audit: Need to add rate limiting and input validation before launch."},
+        ],
+        "evidence_ids": [0, 1, 4, 5],
+        "facets": ["frontend_choice", "frontend_reason", "backend_choice", "backend_reason", "database_choice", "database_reason", "deployment_choice"],
+        "facet_memory_map": {"frontend_choice": 0, "frontend_reason": 0, "backend_choice": 4, "backend_reason": 4, "database_choice": 1, "database_reason": 1, "deployment_choice": 5},
+    },
+    {
+        "id": "temporal_1",
+        "question": "How did the team's stance on remote work change over the three months?",
+        "category": "temporal",
+        "memories": [
+            {"id": 0, "text": "January all-hands: CEO announced mandatory return to office 5 days a week starting February."},
+            {"id": 1, "text": "Q4 revenue report showed 15% growth. Celebrated with team dinner."},
+            {"id": 2, "text": "February survey results: 73% of employees reported decreased satisfaction with RTO policy."},
+            {"id": 3, "text": "New coffee machine installed in the break room. Everyone loves it."},
+            {"id": 4, "text": "February town hall: HR presented data showing 20% increase in turnover since RTO mandate."},
+            {"id": 5, "text": "March policy update: CEO reversed course. Now hybrid 3 days in office, 2 remote. Cited retention data."},
+            {"id": 6, "text": "IT upgraded the conference room AV equipment for better hybrid meetings."},
+            {"id": 7, "text": "Quarterly OKR review. Team hit 4 of 5 objectives."},
+            {"id": 8, "text": "March satisfaction survey: Employee satisfaction recovered to 85% after hybrid policy."},
+            {"id": 9, "text": "Parking garage construction causing noise complaints from third floor."},
+        ],
+        "evidence_ids": [0, 2, 4, 5, 8],
+        "facets": ["initial_policy", "employee_reaction", "turnover_impact", "policy_change", "final_outcome"],
+        "facet_memory_map": {"initial_policy": 0, "employee_reaction": 2, "turnover_impact": 4, "policy_change": 5, "final_outcome": 8},
+    },
+    {
+        "id": "causal_1",
+        "question": "What caused the production outage, what was done to fix it, and what prevention measures were taken?",
+        "category": "causal",
+        "memories": [
+            {"id": 0, "text": "Monday 2am alert: Production database hit 100% disk usage. All writes failing."},
+            {"id": 1, "text": "Sprint retrospective: Team agreed to improve code review process."},
+            {"id": 2, "text": "Root cause analysis: Logging table grew 500GB in 2 weeks due to debug logging left on after feature deploy."},
+            {"id": 3, "text": "Incident response: DevOps team purged old log entries and increased disk from 1TB to 2TB."},
+            {"id": 4, "text": "New hire orientation for three junior developers. HR handled logistics."},
+            {"id": 5, "text": "Post-mortem action item 1: Implement log rotation with 30-day retention policy."},
+            {"id": 6, "text": "Post-mortem action item 2: Add disk usage alerts at 70%, 80%, 90% thresholds."},
+            {"id": 7, "text": "Post-mortem action item 3: Require removing debug logging before merging to main."},
+            {"id": 8, "text": "Team building event at the escape room. Marketing team won."},
+            {"id": 9, "text": "Client demo went well. They want to proceed with Phase 2."},
+        ],
+        "evidence_ids": [0, 2, 3, 5, 6, 7],
+        "facets": ["what_happened", "root_cause", "immediate_fix", "prevention_1", "prevention_2", "prevention_3"],
+        "facet_memory_map": {"what_happened": 0, "root_cause": 2, "immediate_fix": 3, "prevention_1": 5, "prevention_2": 6, "prevention_3": 7},
+    },
+    {
+        "id": "multi_entity_1",
+        "question": "What are each team member's roles and how do their responsibilities interact?",
+        "category": "multi_entity",
+        "memories": [
+            {"id": 0, "text": "Alice leads frontend development. She works closely with Bob on API contracts."},
+            {"id": 1, "text": "Company picnic was fun. Great weather this year."},
+            {"id": 2, "text": "Bob owns the backend services. He designs APIs that Alice's frontend consumes."},
+            {"id": 3, "text": "Carol manages the infrastructure. She provisions the servers Bob's services run on."},
+            {"id": 4, "text": "New ping pong table in the break room. Tournament next Friday."},
+            {"id": 5, "text": "Dave handles QA. He writes integration tests that cover Alice's UI and Bob's APIs."},
+            {"id": 6, "text": "Eve is the project manager. She coordinates between Alice, Bob, Carol, and Dave."},
+            {"id": 7, "text": "Office plants are dying. Need to assign someone to water them."},
+            {"id": 8, "text": "Alice and Carol paired on improving the CI/CD pipeline. Reduced deploy time by 40%."},
+            {"id": 9, "text": "Dave found a critical bug in Bob's API. Bob fixed it same day."},
+        ],
+        "evidence_ids": [0, 2, 3, 5, 6, 8, 9],
+        "facets": ["alice_role", "bob_role", "carol_role", "dave_role", "eve_role", "alice_bob_interaction", "bob_carol_interaction", "dave_integration"],
+        "facet_memory_map": {"alice_role": 0, "bob_role": 2, "carol_role": 3, "dave_role": 5, "eve_role": 6, "alice_bob_interaction": 0, "bob_carol_interaction": 3, "dave_integration": 5},
+    },
+    {
+        "id": "synthesis_2",
+        "question": "What is the complete customer onboarding process from signup to first value?",
+        "category": "synthesis",
+        "memories": [
+            {"id": 0, "text": "Step 1: Customer signs up via website. Auto-creates account and sends welcome email."},
+            {"id": 1, "text": "Marketing team redesigned the landing page. Conversion rate up 12%."},
+            {"id": 2, "text": "Step 2: Customer success rep schedules onboarding call within 24 hours of signup."},
+            {"id": 3, "text": "Step 3: During onboarding call, rep helps customer import their data and configure integrations."},
+            {"id": 4, "text": "Sales team hit quarterly target. Pizza party celebration."},
+            {"id": 5, "text": "Step 4: Customer gets access to interactive tutorial. Must complete 3 core modules."},
+            {"id": 6, "text": "Step 5: After tutorial completion, customer success checks in at day 7 and day 30."},
+            {"id": 7, "text": "Office AC broken again. Facilities contacted."},
+            {"id": 8, "text": "Churn analysis: Customers who complete onboarding tutorial have 3x higher retention."},
+            {"id": 9, "text": "Support ticket about login issues. Resolved — was a password reset problem."},
+        ],
+        "evidence_ids": [0, 2, 3, 5, 6],
+        "facets": ["signup", "scheduling", "data_import", "tutorial", "followup"],
+        "facet_memory_map": {"signup": 0, "scheduling": 2, "data_import": 3, "tutorial": 5, "followup": 6},
+    },
+]
+
+
+def evaluate_combination(selected_ids: List[int], scenario: Dict) -> Dict:
+    """
+    Evaluate how well selected memories combine to answer the question.
+    
+    Returns facet coverage, synergy score, and overall combination quality.
+    """
+    evidence_ids = set(scenario["evidence_ids"])
+    facet_map = scenario["facet_memory_map"]
+    facets = scenario["facets"]
+    selected_set = set(selected_ids)
+    
+    # Facet coverage: what percentage of required facets are covered?
+    covered_facets = []
+    for facet in facets:
+        required_mem = facet_map[facet]
+        if required_mem in selected_set:
+            covered_facets.append(facet)
+    
+    coverage = len(covered_facets) / len(facets) if facets else 0
+    
+    # Evidence recall: what percentage of evidence memories selected?
+    evidence_found = selected_set & evidence_ids
+    evidence_recall = len(evidence_found) / len(evidence_ids) if evidence_ids else 0
+    
+    # Precision: what percentage of selected are actually evidence?
+    precision = len(evidence_found) / len(selected_set) if selected_set else 0
+    
+    # Noise: non-evidence memories selected
+    noise = len(selected_set - evidence_ids)
+    
+    return {
+        "coverage": coverage,
+        "evidence_recall": evidence_recall,
+        "precision": precision,
+        "noise": noise,
+        "covered_facets": covered_facets,
+        "missing_facets": [f for f in facets if f not in covered_facets],
+        "f1": (2 * precision * evidence_recall / (precision + evidence_recall)
+               if (precision + evidence_recall) > 0 else 0),
+    }
+
+
+def run_benchmark(recall_fn, K: int = 5, scenarios: List[Dict] = None) -> Dict:
+    """
+    Run MemCombine benchmark against a recall function.
+    
+    Args:
+        recall_fn: Function(memories, query, K) -> List[int] (selected indices)
+        K: Number of memories to select
+        scenarios: Custom scenarios (uses built-in if None)
+    
+    Returns:
+        Benchmark results with per-scenario and aggregate scores
+    """
+    if scenarios is None:
+        scenarios = SCENARIOS
+    
+    results = []
+    total_coverage = 0
+    total_recall = 0
+    total_f1 = 0
+    perfect = 0
+    
+    for scenario in scenarios:
+        memory_texts = [m["text"] for m in scenario["memories"]]
+        selected = recall_fn(memory_texts, scenario["question"], K)
+        
+        eval_result = evaluate_combination(selected, scenario)
+        
+        results.append({
+            "id": scenario["id"],
+            "category": scenario["category"],
+            "selected": selected,
+            **eval_result,
+        })
+        
+        total_coverage += eval_result["coverage"]
+        total_recall += eval_result["evidence_recall"]
+        total_f1 += eval_result["f1"]
+        if eval_result["coverage"] == 1.0:
+            perfect += 1
+    
+    n = len(scenarios)
+    return {
+        "benchmark": "MemCombine",
+        "n_scenarios": n,
+        "K": K,
+        "avg_coverage": total_coverage / n,
+        "avg_evidence_recall": total_recall / n,
+        "avg_f1": total_f1 / n,
+        "perfect_coverage": perfect,
+        "perfect_coverage_pct": perfect / n * 100,
+        "per_scenario": results,
+    }

quantum-memory-graph-0.1.0/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"