@evomap/evolver 1.29.0

package/src/gep/memoryGraphAdapter.js

@@ -0,0 +1,203 @@
+// ---------------------------------------------------------------------------
+// MemoryGraphAdapter -- stable interface boundary for memory graph operations.
+//
+// Default implementation delegates to the local JSONL-based memoryGraph.js.
+// SaaS providers can supply a remote adapter by setting MEMORY_GRAPH_PROVIDER=remote
+// and configuring MEMORY_GRAPH_REMOTE_URL / MEMORY_GRAPH_REMOTE_KEY.
+//
+// The adapter is designed so that the open-source evolver always works offline
+// with the local implementation. Remote is optional and degrades gracefully.
+// ---------------------------------------------------------------------------
+
+const localGraph = require('./memoryGraph');
+
+// ---------------------------------------------------------------------------
+// Adapter interface contract (all methods must be implemented by providers):
+//
+//   getAdvice({ signals, genes, driftEnabled }) => { preferredGeneId, bannedGeneIds, currentSignalKey, explanation }
+//   recordSignalSnapshot({ signals, observations }) => event
+//   recordHypothesis({ signals, mutation, personality_state, selectedGene, selector, driftEnabled, selectedBy, capsulesUsed, observations }) => { hypothesisId, signalKey }
+//   recordAttempt({ signals, mutation, personality_state, selectedGene, selector, driftEnabled, selectedBy, hypothesisId, capsulesUsed, observations }) => { actionId, signalKey }
+//   recordOutcome({ signals, observations }) => event | null
+//   recordExternalCandidate({ asset, source, signals }) => event | null
+//   memoryGraphPath() => string
+//   computeSignalKey(signals) => string
+//   tryReadMemoryGraphEvents(limit) => event[]
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Local adapter (default) -- wraps memoryGraph.js without any behavior change
+// ---------------------------------------------------------------------------
+
+const localAdapter = {
+  name: 'local',
+
+  getAdvice(opts) {
+    return localGraph.getMemoryAdvice(opts);
+  },
+
+  recordSignalSnapshot(opts) {
+    return localGraph.recordSignalSnapshot(opts);
+  },
+
+  recordHypothesis(opts) {
+    return localGraph.recordHypothesis(opts);
+  },
+
+  recordAttempt(opts) {
+    return localGraph.recordAttempt(opts);
+  },
+
+  recordOutcome(opts) {
+    return localGraph.recordOutcomeFromState(opts);
+  },
+
+  recordExternalCandidate(opts) {
+    return localGraph.recordExternalCandidate(opts);
+  },
+
+  memoryGraphPath() {
+    return localGraph.memoryGraphPath();
+  },
+
+  computeSignalKey(signals) {
+    return localGraph.computeSignalKey(signals);
+  },
+
+  tryReadMemoryGraphEvents(limit) {
+    return localGraph.tryReadMemoryGraphEvents(limit);
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Remote adapter (SaaS) -- calls external KG service with local fallback
+// ---------------------------------------------------------------------------
+
+function buildRemoteAdapter() {
+  const remoteUrl = process.env.MEMORY_GRAPH_REMOTE_URL || '';
+  const remoteKey = process.env.MEMORY_GRAPH_REMOTE_KEY || '';
+  const timeoutMs = Number(process.env.MEMORY_GRAPH_REMOTE_TIMEOUT_MS) || 5000;
+
+  async function remoteCall(endpoint, body) {
+    if (!remoteUrl) throw new Error('MEMORY_GRAPH_REMOTE_URL not configured');
+    const url = `${remoteUrl.replace(/\/+$/, '')}${endpoint}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...(remoteKey ? { Authorization: `Bearer ${remoteKey}` } : {}),
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+      if (!res.ok) {
+        throw new Error(`remote_kg_error: ${res.status}`);
+      }
+      return await res.json();
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  // Wrap remote call with local fallback -- ensures offline resilience.
+  function withFallback(localFn, remoteFn) {
+    return async function (...args) {
+      try {
+        return await remoteFn(...args);
+      } catch (e) {
+        // Fallback to local on any remote failure (network, timeout, config).
+        return localFn(...args);
+      }
+    };
+  }
+
+  return {
+    name: 'remote',
+
+    // getAdvice is the primary candidate for remote enhancement (richer graph reasoning).
+    getAdvice: withFallback(
+      (opts) => localGraph.getMemoryAdvice(opts),
+      async (opts) => {
+        const result = await remoteCall('/kg/advice', {
+          signals: opts.signals,
+          genes: (opts.genes || []).map((g) => ({ id: g.id, category: g.category, type: g.type })),
+          driftEnabled: opts.driftEnabled,
+        });
+        // Normalize remote response to match local contract.
+        return {
+          currentSignalKey: result.currentSignalKey || localGraph.computeSignalKey(opts.signals),
+          preferredGeneId: result.preferredGeneId || null,
+          bannedGeneIds: new Set(result.bannedGeneIds || []),
+          explanation: Array.isArray(result.explanation) ? result.explanation : [],
+        };
+      }
+    ),
+
+    // Write operations: always write locally first, then async-sync to remote.
+    // This preserves the append-only local graph as source of truth.
+    recordSignalSnapshot(opts) {
+      const ev = localGraph.recordSignalSnapshot(opts);
+      remoteCall('/kg/ingest', { kind: 'signal', event: ev }).catch(() => {});
+      return ev;
+    },
+
+    recordHypothesis(opts) {
+      const result = localGraph.recordHypothesis(opts);
+      remoteCall('/kg/ingest', { kind: 'hypothesis', event: result }).catch(() => {});
+      return result;
+    },
+
+    recordAttempt(opts) {
+      const result = localGraph.recordAttempt(opts);
+      remoteCall('/kg/ingest', { kind: 'attempt', event: result }).catch(() => {});
+      return result;
+    },
+
+    recordOutcome(opts) {
+      const ev = localGraph.recordOutcomeFromState(opts);
+      if (ev) {
+        remoteCall('/kg/ingest', { kind: 'outcome', event: ev }).catch(() => {});
+      }
+      return ev;
+    },
+
+    recordExternalCandidate(opts) {
+      const ev = localGraph.recordExternalCandidate(opts);
+      if (ev) {
+        remoteCall('/kg/ingest', { kind: 'external_candidate', event: ev }).catch(() => {});
+      }
+      return ev;
+    },
+
+    memoryGraphPath() {
+      return localGraph.memoryGraphPath();
+    },
+
+    computeSignalKey(signals) {
+      return localGraph.computeSignalKey(signals);
+    },
+
+    tryReadMemoryGraphEvents(limit) {
+      return localGraph.tryReadMemoryGraphEvents(limit);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Provider resolution
+// ---------------------------------------------------------------------------
+
+function resolveAdapter() {
+  const provider = (process.env.MEMORY_GRAPH_PROVIDER || 'local').toLowerCase().trim();
+  if (provider === 'remote') {
+    return buildRemoteAdapter();
+  }
+  return localAdapter;
+}
+
+const adapter = resolveAdapter();
+
+module.exports = adapter;

package/src/gep/mutation.js

@@ -0,0 +1,186 @@
+function clamp01(x) {
+  const n = Number(x);
+  if (!Number.isFinite(n)) return 0;
+  return Math.max(0, Math.min(1, n));
+}
+
+function nowTsMs() {
+  return Date.now();
+}
+
+function uniqStrings(list) {
+  const out = [];
+  const seen = new Set();
+  for (const x of Array.isArray(list) ? list : []) {
+    const s = String(x || '').trim();
+    if (!s) continue;
+    if (seen.has(s)) continue;
+    seen.add(s);
+    out.push(s);
+  }
+  return out;
+}
+
+function hasErrorishSignal(signals) {
+  const list = Array.isArray(signals) ? signals.map(s => String(s || '')) : [];
+  if (list.includes('issue_already_resolved') || list.includes('openclaw_self_healed')) return false;
+  if (list.includes('log_error')) return true;
+  if (list.some(s => s.startsWith('errsig:') || s.startsWith('errsig_norm:'))) return true;
+  return false;
+}
+
+// Opportunity signals that indicate a chance to innovate (not just fix).
+var OPPORTUNITY_SIGNALS = [
+  'user_feature_request',
+  'user_improvement_suggestion',
+  'perf_bottleneck',
+  'capability_gap',
+  'stable_success_plateau',
+  'external_opportunity',
+  'issue_already_resolved',
+  'openclaw_self_healed',
+  'empty_cycle_loop_detected',
+];
+
+function hasOpportunitySignal(signals) {
+  var list = Array.isArray(signals) ? signals.map(function (s) { return String(s || ''); }) : [];
+  for (var i = 0; i < OPPORTUNITY_SIGNALS.length; i++) {
+    var name = OPPORTUNITY_SIGNALS[i];
+    if (list.includes(name)) return true;
+    if (list.some(function (s) { return s.startsWith(name + ':'); })) return true;
+  }
+  return false;
+}
+
+function mutationCategoryFromContext({ signals, driftEnabled }) {
+  if (hasErrorishSignal(signals)) return 'repair';
+  if (driftEnabled) return 'innovate';
+  // Auto-innovate: opportunity signals present and no errors
+  if (hasOpportunitySignal(signals)) return 'innovate';
+  // Consult strategy preset: if the configured strategy favors innovation,
+  // default to innovate instead of optimize when there is nothing specific to do.
+  try {
+    var strategy = require('./strategy').resolveStrategy();
+    if (strategy && typeof strategy.innovate === 'number' && strategy.innovate >= 0.5) return 'innovate';
+  } catch (_) {}
+  return 'optimize';
+}
+
+function expectedEffectFromCategory(category) {
+  const c = String(category || '');
+  if (c === 'repair') return 'reduce runtime errors, increase stability, and lower failure rate';
+  if (c === 'optimize') return 'improve success rate and reduce repeated operational cost';
+  if (c === 'innovate') return 'explore new strategy combinations to escape local optimum';
+  return 'improve robustness and success probability';
+}
+
+function targetFromGene(selectedGene) {
+  if (selectedGene && selectedGene.id) return `gene:${String(selectedGene.id)}`;
+  return 'behavior:protocol';
+}
+
+function isHighRiskPersonality(p) {
+  // Conservative definition: low rigor or high risk_tolerance is treated as high-risk personality.
+  const rigor = p && Number.isFinite(Number(p.rigor)) ? Number(p.rigor) : null;
+  const riskTol = p && Number.isFinite(Number(p.risk_tolerance)) ? Number(p.risk_tolerance) : null;
+  if (rigor != null && rigor < 0.5) return true;
+  if (riskTol != null && riskTol > 0.6) return true;
+  return false;
+}
+
+function isHighRiskMutationAllowed(personalityState) {
+  const rigor = personalityState && Number.isFinite(Number(personalityState.rigor)) ? Number(personalityState.rigor) : 0;
+  const riskTol =
+    personalityState && Number.isFinite(Number(personalityState.risk_tolerance))
+      ? Number(personalityState.risk_tolerance)
+      : 1;
+  return rigor >= 0.6 && riskTol <= 0.5;
+}
+
+function buildMutation({
+  signals,
+  selectedGene,
+  driftEnabled,
+  personalityState,
+  allowHighRisk = false,
+  target,
+  expected_effect,
+} = {}) {
+  const ts = nowTsMs();
+  const category = mutationCategoryFromContext({ signals, driftEnabled: !!driftEnabled });
+  const triggerSignals = uniqStrings(signals);
+
+  const base = {
+    type: 'Mutation',
+    id: `mut_${ts}`,
+    category,
+    trigger_signals: triggerSignals,
+    target: String(target || targetFromGene(selectedGene)),
+    expected_effect: String(expected_effect || expectedEffectFromCategory(category)),
+    risk_level: 'low',
+  };
+
+  // Default risk assignment: innovate is medium; others low.
+  if (category === 'innovate') base.risk_level = 'medium';
+
+  // Optional high-risk escalation (rare, and guarded by strict safety constraints).
+  if (allowHighRisk && category === 'innovate') {
+    base.risk_level = 'high';
+  }
+
+  // Safety constraints (hard):
+  // - forbid innovate + high-risk personality (downgrade innovation to optimize)
+  // - forbid high-risk mutation unless personality satisfies constraints
+  const highRiskPersonality = isHighRiskPersonality(personalityState || null);
+  if (base.category === 'innovate' && highRiskPersonality) {
+    base.category = 'optimize';
+    base.expected_effect = 'safety downgrade: optimize under high-risk personality (avoid innovate+high-risk combo)';
+    base.risk_level = 'low';
+    base.trigger_signals = uniqStrings([...(base.trigger_signals || []), 'safety:avoid_innovate_with_high_risk_personality']);
+  }
+
+  if (base.risk_level === 'high' && !isHighRiskMutationAllowed(personalityState || null)) {
+    // Downgrade rather than emit illegal high-risk mutation.
+    base.risk_level = 'medium';
+    base.trigger_signals = uniqStrings([...(base.trigger_signals || []), 'safety:downgrade_high_risk']);
+  }
+
+  return base;
+}
+
+function isValidMutation(obj) {
+  if (!obj || typeof obj !== 'object') return false;
+  if (obj.type !== 'Mutation') return false;
+  if (!obj.id || typeof obj.id !== 'string') return false;
+  if (!obj.category || !['repair', 'optimize', 'innovate'].includes(String(obj.category))) return false;
+  if (!Array.isArray(obj.trigger_signals)) return false;
+  if (!obj.target || typeof obj.target !== 'string') return false;
+  if (!obj.expected_effect || typeof obj.expected_effect !== 'string') return false;
+  if (!obj.risk_level || !['low', 'medium', 'high'].includes(String(obj.risk_level))) return false;
+  return true;
+}
+
+function normalizeMutation(obj) {
+  const m = obj && typeof obj === 'object' ? obj : {};
+  const out = {
+    type: 'Mutation',
+    id: typeof m.id === 'string' ? m.id : `mut_${nowTsMs()}`,
+    category: ['repair', 'optimize', 'innovate'].includes(String(m.category)) ? String(m.category) : 'optimize',
+    trigger_signals: uniqStrings(m.trigger_signals),
+    target: typeof m.target === 'string' ? m.target : 'behavior:protocol',
+    expected_effect: typeof m.expected_effect === 'string' ? m.expected_effect : expectedEffectFromCategory(m.category),
+    risk_level: ['low', 'medium', 'high'].includes(String(m.risk_level)) ? String(m.risk_level) : 'low',
+  };
+  return out;
+}
+
+module.exports = {
+  clamp01,
+  buildMutation,
+  isValidMutation,
+  normalizeMutation,
+  isHighRiskMutationAllowed,
+  isHighRiskPersonality,
+  hasOpportunitySignal,
+};
+

package/src/gep/narrativeMemory.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { getNarrativePath, getEvolutionDir } = require('./paths');
+
+const MAX_NARRATIVE_ENTRIES = 30;
+const MAX_NARRATIVE_SIZE = 12000;
+
+function ensureDir(dir) {
+  try { if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true }); } catch (_) {}
+}
+
+function recordNarrative({ gene, signals, mutation, outcome, blast, capsule }) {
+  const narrativePath = getNarrativePath();
+  ensureDir(path.dirname(narrativePath));
+
+  const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);
+  const geneId = gene && gene.id ? gene.id : '(auto)';
+  const category = (mutation && mutation.category) || (gene && gene.category) || 'unknown';
+  const status = outcome && outcome.status ? outcome.status : 'unknown';
+  const score = outcome && typeof outcome.score === 'number' ? outcome.score.toFixed(2) : '?';
+  const signalsSummary = Array.isArray(signals) ? signals.slice(0, 4).join(', ') : '(none)';
+  const filesChanged = blast ? blast.files : 0;
+  const linesChanged = blast ? blast.lines : 0;
+  const rationale = mutation && mutation.rationale
+    ? String(mutation.rationale).slice(0, 200) : '';
+  const strategy = gene && Array.isArray(gene.strategy)
+    ? gene.strategy.slice(0, 3).map((s, i) => `  ${i + 1}. ${s}`).join('\n') : '';
+  const capsuleSummary = capsule && capsule.summary ? String(capsule.summary).slice(0, 200) : '';
+
+  const entry = [
+    `### [${ts}] ${category.toUpperCase()} - ${status}`,
+    `- Gene: ${geneId} | Score: ${score} | Scope: ${filesChanged} files, ${linesChanged} lines`,
+    `- Signals: [${signalsSummary}]`,
+    rationale ? `- Why: ${rationale}` : null,
+    strategy ? `- Strategy:\n${strategy}` : null,
+    capsuleSummary ? `- Result: ${capsuleSummary}` : null,
+    '',
+  ].filter(line => line !== null).join('\n');
+
+  let existing = '';
+  try {
+    if (fs.existsSync(narrativePath)) {
+      existing = fs.readFileSync(narrativePath, 'utf8');
+    }
+  } catch (_) {}
+
+  if (!existing.trim()) {
+    existing = '# Evolution Narrative\n\nA chronological record of evolution decisions and outcomes.\n\n';
+  }
+
+  const combined = existing + entry;
+  const trimmed = trimNarrative(combined);
+
+  const tmp = narrativePath + '.tmp';
+  fs.writeFileSync(tmp, trimmed, 'utf8');
+  fs.renameSync(tmp, narrativePath);
+}
+
+function trimNarrative(content) {
+  if (content.length <= MAX_NARRATIVE_SIZE) return content;
+
+  const headerEnd = content.indexOf('###');
+  if (headerEnd < 0) return content.slice(-MAX_NARRATIVE_SIZE);
+
+  const header = content.slice(0, headerEnd);
+  const entries = content.slice(headerEnd).split(/(?=^### \[)/m);
+
+  while (entries.length > MAX_NARRATIVE_ENTRIES) {
+    entries.shift();
+  }
+
+  let result = header + entries.join('');
+  if (result.length > MAX_NARRATIVE_SIZE) {
+    const keep = Math.max(1, entries.length - 5);
+    result = header + entries.slice(-keep).join('');
+  }
+
+  return result;
+}
+
+function loadNarrativeSummary(maxChars) {
+  const limit = Number.isFinite(maxChars) ? maxChars : 4000;
+  const narrativePath = getNarrativePath();
+  try {
+    if (!fs.existsSync(narrativePath)) return '';
+    const content = fs.readFileSync(narrativePath, 'utf8');
+    if (!content.trim()) return '';
+
+    const headerEnd = content.indexOf('###');
+    if (headerEnd < 0) return '';
+
+    const entries = content.slice(headerEnd).split(/(?=^### \[)/m);
+    const recent = entries.slice(-8);
+    let summary = recent.join('');
+    if (summary.length > limit) {
+      summary = summary.slice(-limit);
+      const firstEntry = summary.indexOf('### [');
+      if (firstEntry > 0) summary = summary.slice(firstEntry);
+    }
+    return summary.trim();
+  } catch (_) {
+    return '';
+  }
+}
+
+module.exports = { recordNarrative, loadNarrativeSummary, trimNarrative };

package/src/gep/paths.js

@@ -0,0 +1,113 @@
+const path = require('path');
+const fs = require('fs');
+
+function getRepoRoot() {
+  if (process.env.EVOLVER_REPO_ROOT) {
+    return process.env.EVOLVER_REPO_ROOT;
+  }
+
+  let dir = path.resolve(__dirname, '..', '..');
+  while (dir !== '/' && dir !== '.') {
+    const gitDir = path.join(dir, '.git');
+    if (fs.existsSync(gitDir)) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+
+  return path.resolve(__dirname, '..', '..');
+}
+
+function getWorkspaceRoot() {
+  if (process.env.OPENCLAW_WORKSPACE) {
+    return process.env.OPENCLAW_WORKSPACE;
+  }
+
+  const repoRoot = getRepoRoot();
+  const workspaceDir = path.join(repoRoot, 'workspace');
+  if (fs.existsSync(workspaceDir)) {
+    return workspaceDir;
+  }
+
+  return path.resolve(__dirname, '..', '..', '..', '..');
+}
+
+function getLogsDir() {
+  return process.env.EVOLVER_LOGS_DIR || path.join(getWorkspaceRoot(), 'logs');
+}
+
+function getEvolverLogPath() {
+  return path.join(getLogsDir(), 'evolver_loop.log');
+}
+
+function getMemoryDir() {
+  return process.env.MEMORY_DIR || path.join(getWorkspaceRoot(), 'memory');
+}
+
+// --- Session Scope Isolation ---
+// When EVOLVER_SESSION_SCOPE is set (e.g., to a Discord channel ID or project name),
+// evolution state, memory graph, and assets are isolated to a per-scope subdirectory.
+// This prevents cross-channel/cross-project memory contamination.
+// When NOT set, everything works as before (global scope, backward compatible).
+function getSessionScope() {
+  const raw = String(process.env.EVOLVER_SESSION_SCOPE || '').trim();
+  if (!raw) return null;
+  // Sanitize: only allow alphanumeric, dash, underscore, dot (prevent path traversal).
+  const safe = raw.replace(/[^a-zA-Z0-9_\-\.]/g, '_').slice(0, 128);
+  if (!safe || /^\.{1,2}$/.test(safe) || /\.\./.test(safe)) return null;
+  return safe;
+}
+
+function getEvolutionDir() {
+  const baseDir = process.env.EVOLUTION_DIR || path.join(getMemoryDir(), 'evolution');
+  const scope = getSessionScope();
+  if (scope) {
+    return path.join(baseDir, 'scopes', scope);
+  }
+  return baseDir;
+}
+
+function getGepAssetsDir() {
+  const repoRoot = getRepoRoot();
+  const baseDir = process.env.GEP_ASSETS_DIR || path.join(repoRoot, 'assets', 'gep');
+  const scope = getSessionScope();
+  if (scope) {
+    return path.join(baseDir, 'scopes', scope);
+  }
+  return baseDir;
+}
+
+function getSkillsDir() {
+  return process.env.SKILLS_DIR || path.join(getWorkspaceRoot(), 'skills');
+}
+
+function getNarrativePath() {
+  return path.join(getEvolutionDir(), 'evolution_narrative.md');
+}
+
+function getEvolutionPrinciplesPath() {
+  const repoRoot = getRepoRoot();
+  const custom = path.join(repoRoot, 'EVOLUTION_PRINCIPLES.md');
+  if (fs.existsSync(custom)) return custom;
+  return path.join(repoRoot, 'assets', 'gep', 'EVOLUTION_PRINCIPLES.md');
+}
+
+function getReflectionLogPath() {
+  return path.join(getEvolutionDir(), 'reflection_log.jsonl');
+}
+
+module.exports = {
+  getRepoRoot,
+  getWorkspaceRoot,
+  getLogsDir,
+  getEvolverLogPath,
+  getMemoryDir,
+  getEvolutionDir,
+  getGepAssetsDir,
+  getSkillsDir,
+  getSessionScope,
+  getNarrativePath,
+  getEvolutionPrinciplesPath,
+  getReflectionLogPath,
+};
+