ruvector-mragent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ruvnet
+
+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.

package/README.md

@@ -0,0 +1,159 @@
+# MRAgent — Self-Reconstructing Graph Memory over RuVector, evolved by Darwin
+
+A runnable reference implementation of **MRAgent** ("Memory is Reconstructed, Not
+Retrieved: Graph Memory for LLM Agents") on **RuVector** — and then *past* the
+paper. A **Meta-Harness Darwin** loop evolves the reconstruction harness while the
+memory substrate stays frozen ("freeze the model, evolve the harness").
+
+> **Frozen model:** the RuVector Cue-Tag-Content memory graph (`agent/memory.mjs`).
+> **Evolved harness:** a 12-gene reconstruction genome (`agent/harness.mjs`).
+
+ADRs: **[ADR-269](../../docs/adr/ADR-269-mragent-graph-memory-darwin-optimization.md)**
+(the MRAgent baseline) and **[ADR-270](../../docs/adr/ADR-270-self-reconstructing-graph-memory-beyond-sota.md)**
+(this beyond-SOTA version).
+
+## Beyond the paper
+
+MRAgent reconstructs an answer over a *static* graph: search cues → traverse
+cue→tag→content → prune → synthesize. This implementation adds three mechanisms a
+25-year-out memory system needs, each a tunable gene Darwin co-evolves:
+
+1. **Adaptive depth** (`haltConfidence`) — stop traversing once evidence is
+   decisive, so easy queries cost fewer hops (ACT-style adaptive computation).
+2. **Abstention + calibration** (`abstainThreshold`) — answer *"I don't know"*
+   when reconstructed evidence is too weak, instead of confidently hallucinating.
+   Graded by a **risk-adjusted utility**, not raw accuracy: a confident wrong
+   answer scores worse than an honest abstention.
+3. **Consolidation / replay** (`agent/consolidate.mjs`) — the store reorganizes
+   its own topology from workload (the self-learning GNN RuVector describes),
+   laying Cue→shortcut→Content edges so a 3-hop query resolves in 1 hop tomorrow.
+
+## The 12-gene reconstruction genome
+
+| Gene | Range | RuVector mapping |
+|------|-------|------------------|
+| `cueK` | 1–12 | # cue vectors from `hybridSearch` |
+| `efSearch` | 16–256 | HNSW search depth |
+| `hybridAlpha` | 0–1 | RRF sparse↔dense weight |
+| `fusion` | rrf · linear · dbsf | hybrid fusion strategy |
+| `traversalDepth` | 1–4 | Cypher `LINKED_TO*1..N` hops |
+| `tagFanout` | 1–8 | tags expanded per node |
+| `pruneThreshold` | 0–0.6 | path-evidence floor |
+| `maxContent` | 1–20 | content `LIMIT` to synthesis |
+| `haltConfidence` | 0.2–0.9 | **adaptive-depth halt** |
+| `rerank` | gnn · none | corroboration-aware rerank |
+| `promptStrategy` | terse · evidence-first · prune-explicit | synthesis prompt |
+| `abstainThreshold` | 0–0.6 | **abstention / calibration** |
+
+Every gene is proven load-bearing in `test/harness.test.mjs` — some only via
+*interaction* (distractor tasks are solved by `evidence-first` **or** by
+`terse + gnn + fanout≥2`, an epistatic landscape).
+
+## The hardened corpus (60 tasks, 6 classes, difficulty-varied)
+
+`data/eval-set.json` is **generated** by `tools/genCorpus.mjs` (`npm run
+gen-corpus`) as **structured signal specs**; `agent/memory.mjs` synthesizes the
+Cue/Tag/Content node texts so difficulty is guaranteed, not dependent on fragile
+English. A **concept layer** (`agent/concepts.mjs`) gives the dense embedding real
+semantics decoupled from lexical overlap. 10 instances per class, with varied
+difficulty (1-hop AND 2-hop bridges, 1–3 ranking-distractors) so a train/test
+split constrains every gene:
+
+| Class | Stresses |
+|-------|----------|
+| semantic | `hybridAlpha`→dense (paraphrase, no shared tokens) |
+| lexical | `hybridAlpha`→sparse (rare identifier, generic concept) |
+| hybrid | `fusion` / RRF (needs both signals) |
+| bridge | `traversalDepth` (1–2 intermediate hops) |
+| distractor | `rerank` / `tagFanout` / `promptStrategy` (ranking-distractor content) |
+| unanswerable | `abstainThreshold` (no correct content exists → abstain) |
+
+## Generalization, not overfitting (train / test / CV)
+
+The optimizer **evolves on a train split and reports a held-out test split it
+never saw** — proving the genome generalizes rather than memorizing the eval set.
+Selection uses **3-fold cross-validation with a variance penalty** (mean − ½·range
+across folds) so a knife-edge gene that wins one fold but collapses on another is
+rejected. A subtle bug this surfaced — confidence was depressed by `decay^depth`,
+making deep-but-relevant answers look weak and breaking abstention across depths —
+is fixed by deriving **abstention confidence from the answer's raw relevance, not
+its decayed path score** (`agent/memory.mjs`).
+
+```
+                 accuracy   risk    halluc
+baseline (test)   ~30%      ~0.25    0.17
+evolved  (test)   ~65%      ~0.81    0.04      ← held out, never seen in evolution
+                  +35pt    +0.56  generalizes
+```
+
+(The synthetic toy embedding has per-instance noise, and one global `hybridAlpha`
+cannot perfectly serve both dense- and sparse-keyed queries, so the test ceiling
+is ~80%, not 100% — the gate asks whether **evolution transfers**, which it does.)
+
+## Results on the full corpus (zero optional deps, deterministic)
+
+```
+config            accuracy  risk   halluc  latency  hops
+baseline           50.0%   0.417   0.17    2.81    1.23
+evolved (ref)      70.0%   0.775   0.03    3.09    1.08
+evolved+replay     70.0%   0.775   0.03    3.16    1.00
+
+evolved vs baseline: accuracy +20.0pt · risk +0.358 · hallucination 0.17 → 0.03
+consolidation: shortcuts → fewer hops at equal accuracy
+```
+
+`npm run optimize` (full GA + memetic polish) reaches **+33pt train accuracy /
+risk 0.94** and writes the evolved genome to `optimize.report.json`, which
+`npm run benchmark` then picks up. The optimizer is **memetic**: a genetic loop
+(Darwin `mapLimit`/`paretoFront`) explores broadly, then deterministic
+coordinate descent refines narrow optima (e.g. the abstention band).
+
+## Run it
+
+```bash
+cd examples/mragent
+npm test            # 12 deterministic gates, every gene proven load-bearing
+npm run benchmark   # baseline vs evolved vs evolved+replay
+npm run optimize    # Darwin loop + memetic polish + consolidation + held-out test
+npm run gen-corpus  # regenerate data/eval-set.json (deterministic)
+npm run probe       # inspect @metaharness/darwin exports (optional)
+```
+
+Nothing requires network, an API key, or native bindings. The substrate is a
+deterministic in-process graph with the **same semantics** as a live RuVector
+`.rvf` index (concept-dense + token-sparse hybrid RRF search, bounded-depth
+prunable Cypher traversal, GNN-style corroboration rerank), so an evolved genome
+transfers to production unchanged.
+
+### With the real Darwin write-layer (optional)
+
+```bash
+npm i -D @metaharness/darwin@latest
+npx metaharness evolve . --generations 12 --children 3 --eval-cmd "node benchmark.mjs"
+```
+
+`harness/scorePolicy.ts` is the fitness `metaharness evolve` calls per mutation.
+
+## ADR-150 compliance
+
+`@metaharness/darwin` and `ruvector` are **optionalDependencies** only; every
+touch is `try/catch` guarded; `npm test`, `npm run benchmark`, and `npm run
+optimize` all pass with no optional deps installed (the CI gate).
+
+## Layout
+
+```
+examples/mragent/
+├── agent/
+│   ├── concepts.mjs      # concept layer (dense semantics ≠ sparse tokens)
+│   ├── memory.mjs        # FROZEN: Cue-Tag-Content store (RuVector semantics)
+│   ├── harness.mjs       # EVOLVED: 12-gene genome + reasoning loop
+│   └── consolidate.mjs   # replay → self-reorganizing topology
+├── harness/scorePolicy.ts# Darwin fitness (accuracy + risk + cost)
+├── data/eval-set.json    # 60-task structured corpus (generated)
+├── tools/genCorpus.mjs   # deterministic corpus generator
+├── optimize.mjs          # GA + CV + memetic polish + held-out test + consolidation
+├── benchmark.mjs         # baseline vs evolved vs replay
+├── probeDarwin.mjs       # probe optional @metaharness/darwin
+└── test/harness.test.mjs # 12 acceptance gates
+```

package/agent/concepts.mjs

@@ -0,0 +1,71 @@
+// Concept layer — gives the FROZEN model a genuine *semantic* dimension that is
+// decoupled from raw lexical overlap.
+//
+// Why this matters: with a plain hash-of-tokens embedding, dense cosine and
+// sparse term-overlap are almost perfectly correlated, so `hybridAlpha` and
+// `fusion` have nothing to tune (ADR-269 measured Δfit≈0 for both). Real
+// embeddings differ: paraphrases ("rapid cold-start" ~ "fast boot") are dense-
+// close with ZERO token overlap, while rare identifiers ("rvf-7", "cve-2") are
+// lexically decisive but semantically generic.
+//
+// We model that split deterministically: tokens that belong to a synonym group
+// project onto a shared CONCEPT dimension (dense semantics), and identifier-like
+// tokens stay in a lexical tail. Result:
+//   • semantic queries  → answerable by DENSE only  (no shared tokens)
+//   • lexical  queries  → answerable by SPARSE only (concept-generic)
+//   • hybrid   queries  → need RRF over both
+// which is exactly the regime where hybridAlpha + fusion are load-bearing.
+
+// Synonym groups → concept ids. Tokens in the same group are dense-equivalent.
+const CONCEPT_GROUPS = [
+  ["fast", "rapid", "quick", "speed", "swift", "low-latency", "sub-millisecond", "instant"],
+  ["boot", "cold-start", "startup", "initialize", "cold-boot", "launch", "spin-up"],
+  ["compress", "compression", "quantize", "quantization", "shrink", "squeeze", "pack"],
+  ["store", "storage", "persist", "write", "save", "backend", "durable"],
+  ["search", "retrieve", "retrieval", "query", "lookup", "find", "recall"],
+  ["graph", "topology", "network", "node", "nodes", "edge", "edges", "associative"],
+  ["consensus", "agreement", "leader", "elect", "authoritative", "quorum"],
+  ["secure", "security", "tamper", "tamper-evident", "witness", "proof", "cryptographic", "immutable"],
+  ["merge", "fuse", "fusion", "combine", "aggregate", "blend"],
+  ["prune", "filter", "drop", "discard", "remove", "trim"],
+  ["accuracy", "recall", "precision", "fidelity", "correct", "quality"],
+  ["memory", "remember", "reconstruct", "reconstruction", "cue", "tag", "content"],
+  ["validate", "validation", "reject", "fail-fast", "guard", "check"],
+  ["concurrency", "lock-free", "parallel", "branching", "copy-on-write", "throughput"],
+  ["embedding", "vector", "dense", "representation", "latent"],
+];
+
+export const NUM_CONCEPTS = CONCEPT_GROUPS.length;
+
+// Canonical concept name = first token of each group. Corpus specs reference
+// concepts by these names; buildGraph synthesizes DIFFERENT surface tokens from
+// the same group for query vs cue, so they share a concept but not a token.
+export const CONCEPT_NAMES = CONCEPT_GROUPS.map((g) => g[0]);
+
+const NAME_TO_INDEX = new Map(CONCEPT_NAMES.map((n, i) => [n, i]));
+
+/** k-th distinct surface token of a concept (by name), wrapping the group. */
+export function syn(conceptName, k = 0) {
+  const ci = NAME_TO_INDEX.get(conceptName);
+  if (ci === undefined) return conceptName; // treat unknown as a literal token
+  const group = CONCEPT_GROUPS[ci];
+  return group[k % group.length];
+}
+
+const TOKEN_TO_CONCEPT = new Map();
+CONCEPT_GROUPS.forEach((group, ci) => {
+  for (const tok of group) TOKEN_TO_CONCEPT.set(tok, ci);
+});
+
+/** Concept id for a token, or -1 if it is lexical-only (identifier-like). */
+export function conceptOf(token) {
+  if (TOKEN_TO_CONCEPT.has(token)) return TOKEN_TO_CONCEPT.get(token);
+  return -1;
+}
+
+// A token is "identifier-like" (purely lexical) if it carries a digit or hyphen
+// with a digit, or is a known id prefix. These never get a concept, so only
+// sparse search can pin them down.
+export function isIdentifier(token) {
+  return /\d/.test(token) || /^(rvf|cve|adr|t\d|id)/.test(token);
+}

package/agent/consolidate.mjs

@@ -0,0 +1,55 @@
+// Memory consolidation / replay — the "sleep" phase of a self-reorganizing memory.
+//
+// Beyond MRAgent: the paper reconstructs over a STATIC graph. A 25-year-out memory
+// system reshapes its own topology from workload — exactly the self-learning GNN
+// RuVector describes ("pushes similarities back into the neighbor lists"). After a
+// batch of successful reconstructions, we REPLAY the winning paths and lay down a
+// direct Cue→shortcut→Content edge, so a query that needed a 3-hop traversal today
+// resolves in 1 hop tomorrow. Embeddings/content (the frozen model) are untouched;
+// only graph adjacency — the store's own learned index — changes.
+//
+// This is gated and deterministic: it consolidates only paths that already
+// reconstruct the CORRECT content, so it never invents associations.
+
+import { runReasoningLoop } from "./harness.mjs";
+
+/**
+ * Replay the corpus under `genome` and add shortcut edges for every task whose
+ * correct content is currently reconstructed. Mutates the store's graph topology.
+ * Returns { consolidated, hopsBefore } for reporting.
+ *
+ * @param {MemoryStore} store
+ * @param {Array} tasks
+ * @param {object} genome
+ */
+export function consolidate(store, tasks, genome) {
+  const { cues, tags } = store.graph;
+  let consolidated = 0;
+  let hopsBefore = 0;
+  let n = 0;
+
+  for (const task of tasks) {
+    if (task.answerable === false) continue;
+    const r = runReasoningLoop(store.queryText(task.id), store, genome, task);
+    hopsBefore += r.hops; n++;
+    if (!r.correct) continue; // only consolidate paths that genuinely work
+
+    const correctCue = cues.get(`cue:${task.id}:correct`);
+    const correctContentId = `content:${task.id}`;
+    if (!correctCue) continue;
+
+    // Lay down a 1-hop shortcut tag the correct cue reaches immediately.
+    const shortcutId = `tag:${task.id}-shortcut`;
+    if (!tags.has(shortcutId)) {
+      tags.set(shortcutId, {
+        id: shortcutId, name: `${task.id}-shortcut`, text: "shortcut",
+        toks: [], vec: new Float32Array(store.cueList[0].vec.length), content: [correctContentId], next: [],
+      });
+      // Prepend so it is the first link explored (reached at hop 1, fanout-safe).
+      correctCue.links = [shortcutId, ...correctCue.links];
+      consolidated++;
+    }
+  }
+
+  return { consolidated, avgHopsBefore: hopsBefore / (n || 1) };
+}

package/agent/harness.mjs

@@ -0,0 +1,204 @@
+// MRAgent EVOLVED HARNESS (v2 — beyond the paper) — the surface Darwin mutates.
+//
+// MRAgent's contribution: memory is a Cue-Tag-Content graph, reconstructed (not
+// retrieved) by searching cues, traversing cue→tag→content, and pruning paths.
+// This v2 adds three mechanisms the paper does not have, each a tunable gene:
+//
+//   • ADAPTIVE DEPTH  (haltConfidence) — stop traversing once evidence is decisive,
+//                       so easy queries cost fewer hops (ACT-style adaptive compute).
+//   • ABSTENTION      (abstainThreshold) — answer "I don't know" when reconstructed
+//                       evidence is too weak, instead of confidently hallucinating.
+//   • CORROBORATION   (rerank=gnn) — boost content reached by MULTIPLE paths, so a
+//                       single high-similarity distractor cannot win.
+//
+// The memory substrate (agent/memory.mjs) stays frozen. Darwin edits only the
+// DARWIN_MUTABLE_BLOCK regions.
+
+import { MemoryStore } from "./memory.mjs";
+
+// ─── DARWIN_MUTABLE_BLOCK: reconstruction genome ────────────────────────────
+export function baselineGenome() {
+  return {
+    // Stage 1 — hybrid cue search (RuVector hybridSearch).
+    cueK: 4,             // initial cue vectors fetched           [1..12]
+    efSearch: 64,        // HNSW search depth / candidate pool     [16..256]
+    hybridAlpha: 0.5,    // RRF weight: 0=sparse … 1=dense         [0..1]
+    fusion: "rrf",       // rrf | linear | dbsf
+
+    // Stage 2 — active reconstruction (Cypher LINKED_TO*1..N traversal).
+    traversalDepth: 2,   // cue→tag→content hops                   [1..4]
+    tagFanout: 3,        // tags expanded per frontier node        [1..8]
+    pruneThreshold: 0.1, // drop paths below this evidence score   [0..0.6]
+    maxContent: 8,       // content nodes handed to synthesis(LIMIT)[1..20]
+    haltConfidence: 0.9, // adaptive-depth: stop when top≥this     [0.2..0.9]
+
+    // Stage 3 — synthesis (LLM prompt strategy + safety).
+    rerank: "gnn",       // gnn | none  (corroboration-aware rerank)
+    promptStrategy: "evidence-first", // terse | evidence-first | prune-explicit
+    abstainThreshold: 0.0, // answer "I don't know" if top score < this [0..0.6]
+  };
+}
+// ─── END DARWIN_MUTABLE_BLOCK ───────────────────────────────────────────────
+
+const STRATEGY_WINDOW = { terse: 2, "evidence-first": Infinity, "prune-explicit": 5 };
+
+// Corroboration-aware rerank: content reached by multiple distinct paths is
+// boosted, so a single high-similarity ranking-distractor cannot outrank a
+// well-corroborated answer. (rerank="none" leaves raw similarity order.)
+function gnnRerank(reconstructed) {
+  return [...reconstructed]
+    .map((c) => ({ ...c, score: c.score * (1 + 0.7 * ((c.paths ?? 1) - 1)) }))
+    .sort((a, b) => b.score - a.score);
+}
+
+/**
+ * Synthesis judge — deterministic stand-in for the LLM. Decides: abstain, answer
+ * correctly, or answer wrongly, given the reconstructed context + confidence.
+ */
+function synthesize(reconstructed, task, genome, confidence) {
+  // ABSTENTION: weak evidence → refuse rather than hallucinate.
+  if (confidence < genome.abstainThreshold) return { abstained: true, correct: false, answer: "I don't know." };
+
+  const window = STRATEGY_WINDOW[genome.promptStrategy] ?? Infinity;
+  const visible = reconstructed.slice(0, window === Infinity ? reconstructed.length : window);
+  const hitIdx = visible.findIndex((c) => c.taskId === task.id);
+
+  if (hitIdx === -1) {
+    // Nothing correct in the window. If the top is a confident distractor, the LLM
+    // would emit it → a (wrong) answer; otherwise it produces an empty/no answer.
+    const wrong = visible.length > 0;
+    return { abstained: false, correct: false, answer: wrong ? "(distractor)" : "(no answer)" };
+  }
+
+  if (genome.promptStrategy === "prune-explicit") {
+    const distractorsAbove = visible.slice(0, hitIdx).filter((c) => c.taskId !== task.id).length;
+    if (distractorsAbove >= 2) return { abstained: false, correct: false, answer: "Pruned: ambiguous." };
+  }
+  return { abstained: false, correct: true, answer: task.expected_fact };
+}
+
+/** MRAgent reasoning loop for one task → deterministic result + telemetry. */
+export function runReasoningLoop(queryText, store, genome, task) {
+  const cueIds = store.hybridSearch(queryText, genome);
+  let { content, stats } = store.reconstruct(queryText, cueIds, genome);
+  if (genome.rerank === "gnn") content = gnnRerank(content);
+
+  // Abstention confidence = chosen content's RAW relevance (depth-independent),
+  // not its decayed ranking score — robust across traversal depths.
+  const confidence = content.length ? (content[0].sim ?? content[0].score) : 0;
+  const out = task ? synthesize(content, task, genome, confidence) : { abstained: false, correct: false };
+
+  const latencyMs =
+    0.02 * genome.efSearch +
+    0.05 * stats.nodesVisited +
+    0.30 * Math.min(content.length, genome.maxContent) +
+    (genome.rerank === "gnn" ? 0.4 : 0);
+
+  return { ...out, confidence, latencyMs, hops: stats.hops, halted: stats.halted, nodesVisited: stats.nodesVisited, contextSize: content.length };
+}
+
+/**
+ * Evaluate a genome over the corpus. Reports raw accuracy AND a risk-adjusted
+ * utility that rewards correct answers, tolerates honest abstention, and PUNISHES
+ * confident hallucination — the calibration objective a 25-year-out memory system
+ * is graded on, not raw accuracy alone.
+ *
+ *   answerable:   correct → +1 | abstain → 0 | wrong → −1
+ *   unanswerable: abstain → +1 | any answer → −1
+ */
+export function evaluate(genome, store, tasks) {
+  let correct = 0, answerable = 0, hallucinations = 0, util = 0;
+  let latency = 0, hops = 0, ctx = 0;
+  for (const task of tasks) {
+    const isAnswerable = task.answerable !== false;
+    const r = runReasoningLoop(store.queryText(task.id), store, genome, task);
+    if (isAnswerable) {
+      answerable++;
+      if (r.correct) { correct++; util += 1; }
+      else if (r.abstained) { util += 0; }
+      else { util -= 1; }
+    } else {
+      if (r.abstained) { util += 1; }
+      else { util -= 1; hallucinations++; }
+    }
+    latency += r.latencyMs; hops += r.hops; ctx += r.contextSize;
+  }
+  const n = tasks.length || 1;
+  return {
+    accuracy: correct / (answerable || 1),       // helpfulness on answerable tasks
+    riskScore: (util / n + 1) / 2,               // risk-adjusted utility in [0,1]
+    hallucinationRate: hallucinations / n,
+    avgLatencyMs: latency / n,
+    avgHops: hops / n,
+    avgContext: ctx / n,
+    n,
+  };
+}
+
+/**
+ * Deterministic, class-stratified train/test split. Within each class the first
+ * `trainFrac` (rounded, ≥1 each side when the class has ≥2) go to train, the rest
+ * to test. Used to prove the evolved genome GENERALIZES (we evolve on train, then
+ * report held-out test) rather than overfitting the eval set.
+ */
+export function splitByClass(tasks, trainFrac = 0.6) {
+  const byClass = new Map();
+  for (const t of tasks) {
+    const c = t.class ?? "default";
+    if (!byClass.has(c)) byClass.set(c, []);
+    byClass.get(c).push(t);
+  }
+  const train = [], test = [];
+  for (const group of byClass.values()) {
+    let nTrain = Math.round(group.length * trainFrac);
+    if (group.length >= 2) nTrain = Math.min(group.length - 1, Math.max(1, nTrain));
+    group.forEach((t, i) => (i < nTrain ? train : test).push(t));
+  }
+  return { train, test };
+}
+
+/**
+ * Deterministic, class-stratified k-fold partition. Each fold draws ~1/k of every
+ * class (round-robin), so folds are balanced. Used for cross-validated genome
+ * selection: scoring on mean-minus-variance across folds rejects genomes tuned to
+ * one split (e.g. a knife-edge abstainThreshold), which is what prevents overfit.
+ */
+export function kFoldByClass(tasks, k = 3) {
+  const byClass = new Map();
+  for (const t of tasks) {
+    const c = t.class ?? "default";
+    if (!byClass.has(c)) byClass.set(c, []);
+    byClass.get(c).push(t);
+  }
+  const folds = Array.from({ length: k }, () => []);
+  for (const group of byClass.values()) group.forEach((t, i) => folds[i % k].push(t));
+  return folds.filter((f) => f.length > 0);
+}
+
+// ─── DARWIN_MUTABLE_BLOCK: mutation operators ───────────────────────────────
+const FUSIONS = ["rrf", "linear", "dbsf"];
+const RERANKS = ["gnn", "none"];
+const STRATEGIES = ["terse", "evidence-first", "prune-explicit"];
+const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+const clampI = (v, lo, hi) => clamp(Math.round(v), lo, hi);
+const pick = (a) => a[Math.floor(Math.random() * a.length)];
+
+export function mutate(genome) {
+  const g = { ...genome };
+  if (Math.random() < 0.4) g.cueK = clampI(g.cueK + (Math.random() * 4 - 2), 1, 12);
+  if (Math.random() < 0.4) g.efSearch = clampI(g.efSearch * (0.7 + Math.random() * 0.8), 16, 256);
+  if (Math.random() < 0.5) g.hybridAlpha = clamp(g.hybridAlpha + (Math.random() * 0.4 - 0.2), 0, 1);
+  if (Math.random() < 0.3) g.fusion = pick(FUSIONS);
+  if (Math.random() < 0.4) g.traversalDepth = clampI(g.traversalDepth + (Math.random() < 0.5 ? 1 : -1), 1, 4);
+  if (Math.random() < 0.4) g.tagFanout = clampI(g.tagFanout + (Math.random() * 4 - 2), 1, 8);
+  if (Math.random() < 0.4) g.pruneThreshold = clamp(g.pruneThreshold + (Math.random() * 0.2 - 0.1), 0, 0.6);
+  if (Math.random() < 0.4) g.maxContent = clampI(g.maxContent + (Math.random() * 6 - 3), 1, 20);
+  if (Math.random() < 0.4) g.haltConfidence = clamp(g.haltConfidence + (Math.random() * 0.3 - 0.15), 0.2, 0.9);
+  if (Math.random() < 0.3) g.rerank = pick(RERANKS);
+  if (Math.random() < 0.3) g.promptStrategy = pick(STRATEGIES);
+  if (Math.random() < 0.4) g.abstainThreshold = clamp(g.abstainThreshold + (Math.random() * 0.2 - 0.1), 0, 0.6);
+  return g;
+}
+// ─── END DARWIN_MUTABLE_BLOCK ───────────────────────────────────────────────
+
+export { MemoryStore };

package/agent/llmMutator.mjs

@@ -0,0 +1,147 @@
+// GPU LLM write-layer for the MRAgent Darwin optimizer (ADR-260: "the real
+// Darwin write-layer proposes leaps directly from failure traces").
+//
+// The built-in GA explores the genome by RANDOM mutation. This adds the missing
+// directed-proposal layer: it shows a local, GPU-served code model (e.g.
+// qwen2.5-coder on an OpenAI-compatible endpoint) the current genome + the tasks
+// it is FAILING, and asks for an improved genome. Proposals are clamped to the
+// declared gene bounds before they ever enter the population, so a bad LLM
+// output can only ever be a no-op — never an unsafe gene.
+//
+// Fully opt-in + gracefully degrading (ADR-150): if no endpoint answers, the
+// optimizer runs exactly as before (deterministic GA + coordinate-descent).
+//
+// Endpoint: OpenAI-compatible POST {url}/chat/completions.
+//   MRAGENT_LLM_URL    (default http://localhost:11434/v1  — ollama on the GPU)
+//   MRAGENT_LLM_MODEL  (default qwen2.5-coder:7b)
+
+// Declared gene bounds — MUST stay in sync with agent/harness.mjs mutate().
+const BOUNDS = {
+  cueK: [1, 12, "int"],
+  efSearch: [16, 256, "int"],
+  hybridAlpha: [0, 1, "float"],
+  traversalDepth: [1, 4, "int"],
+  tagFanout: [1, 8, "int"],
+  pruneThreshold: [0, 0.6, "float"],
+  maxContent: [1, 20, "int"],
+  haltConfidence: [0.2, 0.9, "float"],
+  abstainThreshold: [0, 0.6, "float"],
+};
+const ENUMS = {
+  fusion: ["rrf", "linear", "dbsf"],
+  rerank: ["gnn", "none"],
+  promptStrategy: ["terse", "evidence-first", "prune-explicit"],
+};
+
+/** Clamp/validate an arbitrary object into a safe genome, based on `baseline`. */
+export function coerceGenome(obj, baseline) {
+  const g = { ...baseline };
+  if (!obj || typeof obj !== "object") return g;
+  for (const [k, [lo, hi, kind]] of Object.entries(BOUNDS)) {
+    const v = Number(obj[k]);
+    if (Number.isFinite(v)) {
+      const c = Math.max(lo, Math.min(hi, v));
+      g[k] = kind === "int" ? Math.round(c) : c;
+    }
+  }
+  for (const [k, opts] of Object.entries(ENUMS)) {
+    if (typeof obj[k] === "string" && opts.includes(obj[k])) g[k] = obj[k];
+  }
+  return g;
+}
+
+function extractJson(text) {
+  if (!text) return null;
+  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const body = fenced ? fenced[1] : text;
+  const start = body.indexOf("{");
+  const end = body.lastIndexOf("}");
+  if (start === -1 || end <= start) return null;
+  try {
+    return JSON.parse(body.slice(start, end + 1));
+  } catch {
+    return null;
+  }
+}
+
+/** Returns `{ url, model }` if a local LLM endpoint answers, else `null`. */
+export async function detectEndpoint(timeoutMs = 2500) {
+  const url = (process.env.MRAGENT_LLM_URL || "http://localhost:11434/v1").replace(/\/$/, "");
+  const model = process.env.MRAGENT_LLM_MODEL || "qwen2.5-coder:7b";
+  try {
+    const ctrl = AbortSignal.timeout(timeoutMs);
+    const r = await fetch(`${url}/models`, { signal: ctrl });
+    if (!r.ok) return null;
+    return { url, model };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Ask the GPU model for `n` improved genomes given the current best + failure
+ * traces. Each proposal is coerced into bounds. Returns `[]` on any failure.
+ */
+export async function llmProposeGenomes({ url, model, baseline, current, failures, n = 2, timeoutMs = 60000 }) {
+  const genes =
+    "cueK[1..12 int], efSearch[16..256 int], hybridAlpha[0..1], fusion(rrf|linear|dbsf), " +
+    "traversalDepth[1..4 int], tagFanout[1..8 int], pruneThreshold[0..0.6], maxContent[1..20 int], " +
+    "haltConfidence[0.2..0.9], rerank(gnn|none), promptStrategy(terse|evidence-first|prune-explicit), " +
+    "abstainThreshold[0..0.6]";
+  const sys =
+    "You tune a graph-memory retrieval harness (cue search -> bounded traversal -> synthesis). " +
+    "Goal: raise accuracy AND risk-adjusted utility (abstain on weak evidence; never confidently hallucinate) " +
+    "while keeping traversal cheap. Reason briefly, then output ONLY a JSON array of genome objects.";
+  const user =
+    `Current genome:\n${JSON.stringify(current)}\n\n` +
+    `Failing cases (id, why):\n${failures}\n\n` +
+    `Genes and ranges: ${genes}\n\n` +
+    `Propose ${n} distinct improved genomes as a JSON array. JSON only.`;
+
+  let res;
+  try {
+    res = await fetch(`${url}/chat/completions`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model,
+        messages: [
+          { role: "system", content: sys },
+          { role: "user", content: user },
+        ],
+        temperature: 0.5,
+        max_tokens: 700,
+      }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch {
+    return [];
+  }
+  if (!res.ok) return [];
+  let content;
+  try {
+    content = (await res.json()).choices?.[0]?.message?.content ?? "";
+  } catch {
+    return [];
+  }
+  // Accept either a JSON array or a single object.
+  const parsed = extractArray(content);
+  return parsed.slice(0, n).map((o) => coerceGenome(o, baseline));
+}
+
+function extractArray(text) {
+  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const body = fenced ? fenced[1] : text;
+  const a = body.indexOf("[");
+  const b = body.lastIndexOf("]");
+  if (a !== -1 && b > a) {
+    try {
+      const arr = JSON.parse(body.slice(a, b + 1));
+      if (Array.isArray(arr)) return arr;
+    } catch {
+      /* fall through to single-object */
+    }
+  }
+  const one = extractJson(text);
+  return one ? [one] : [];
+}