# v8.12 MAGMA/SYNAPSE Graph Retrieval Phase 2 Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Harden and expand graph retrieval quality for MAGMA/SYNAPSE paths while preserving current safety and latency guarantees.

**Architecture:** Keep planner-gated graph behavior, add stronger expansion scoring controls, provenance-rich explainability, and shadow-evaluation tooling. Do not force graph expansion into all queries; ship as measurable, controlled upgrades.

**Tech Stack:** TypeScript, `src/graph.ts`, `src/orchestrator.ts`, `src/intent.ts`, `src/tools.ts`, node:test.

---

## Task 1: Add graph expansion scoring controls

**Files:**
- Modify: `src/types.ts`
- Modify: `src/config.ts`
- Modify: `src/orchestrator.ts`
- Test: `tests/graph-recall-scoring.test.ts`
- Docs: `docs/config-reference.md`

**Steps:**
1. Add config knobs for activation weighting and graph-vs-qmd blend bounds.
2. Implement bounded blend function for graph-expanded candidates.
3. Add tests for monotonic ordering and cap-after-filter invariants.

## Task 2: Add richer graph provenance in recall snapshots

**Files:**
- Modify: `src/orchestrator.ts`
- Modify: `src/recall-state.ts`
- Test: `tests/graph-recall-integration.test.ts`
- Docs: `docs/architecture/retrieval-pipeline.md`

**Steps:**
1. Persist per-memory expansion provenance (seed, hop depth, decayed weight, graph type).
2. Add concise explain block for `memory_graph_explain_last_recall`.
3. Ensure snapshot size is bounded and safe for high-traffic sessions.

## Task 3: Add shadow-eval mode for graph assist in full mode

**Files:**
- Modify: `src/types.ts`
- Modify: `src/config.ts`
- Modify: `src/orchestrator.ts`
- Test: `tests/graph-shadow-eval.test.ts`
- Docs: `docs/setup-config-tuning.md`

**Steps:**
1. Add `graphAssistShadowEvalEnabled` flag.
2. In shadow mode, compute graph-expanded set but do not inject.
3. Emit comparison telemetry (baseline vs graph candidate overlap/score deltas).
4. Add tests ensuring injected output remains baseline-identical in shadow mode.

## Task 4: Add graph health diagnostics command

**Files:**
- Modify: `src/cli.ts`
- Modify: `src/graph.ts`
- Test: `tests/cli-graph-health.test.ts`
- Docs: `docs/operations.md`

**Steps:**
1. Add `openclaw engram graph-health` command.
2. Report edge-file integrity, node coverage, and corruption counts.
3. Add optional repair guidance output (no destructive writes by default).

## Task 5: Verification and rollout

**Files:**
- Modify: `CHANGELOG.md`

**Steps:**
1. Run full preflight and graph test suite.
2. Validate behavior with graph disabled remains unchanged.
3. Roll out as PR slices: scoring, provenance, shadow-eval, diagnostics.

