enigma-memory 0.1.18 → 0.1.22

package/packages/sdk/src/intelligence/contradiction.js

@@ -0,0 +1,337 @@
+// Enigma Memory Intelligence: Contradiction & Supersession DAG.
+// Automatically tracks state evolution, resolves conflicting factual assertions,
+// and preserves immutable provenance links for superseded facts.
+const CONTEXT_STOP_WORDS = new Set([
+  'and', 'are', 'changed', 'favorite', 'from', 'into', 'instead', 'is', 'living',
+  'lives', 'longer', 'moved', 'now', 'preference', 'prefer', 'prefers', 'stopped',
+  'switched', 'the', 'their', 'they', 'this', 'to', 'using', 'uses', 'with',
+]);
+
+function extractSubject(text, kind) {
+  const predicates = {
+    location: /^(.*?)\b(?:now\s+)?(?:lives?\s+in|living\s+in|moved\s+to)\b/i,
+    service: /^(.*?)\b(?:stopped\s+using|no\s+longer\s+uses?|switched\s+to|uses?|using)\b/i,
+    preference: /^(.*?)\b(?:changed\s+preference|now\s+prefers?|prefers?)\b/i,
+  };
+  const match = text.trim().match(predicates[kind]);
+  const subject = match?.[1]
+    ?.trim()
+    .replace(/\b(?:currently|is|was)\s*$/i, '')
+    .replace(/[^a-z0-9]+/gi, ' ')
+    .trim()
+    .toLowerCase();
+  return subject || null;
+}
+
+function contextTokens(text, subject) {
+  const subjectTokens = new Set((subject || '').split(/\s+/).filter(Boolean));
+  return new Set(
+    text.toLowerCase()
+      .split(/[^a-z0-9]+/)
+      .filter(token => token.length > 2 && !CONTEXT_STOP_WORDS.has(token) && !subjectTokens.has(token)),
+  );
+}
+
+function hasVerifiedSharedContext(newText, oldText, kind) {
+  const newSubject = extractSubject(newText, kind);
+  const oldSubject = extractSubject(oldText, kind);
+  if (newSubject && oldSubject) return newSubject === oldSubject;
+  const newTopics = contextTokens(newText, newSubject);
+  const oldTopics = contextTokens(oldText, oldSubject);
+  for (const topic of newTopics) {
+    if (oldTopics.has(topic)) return true;
+  }
+  return false;
+}
+
+
+export class ContradictionGraph {
+  constructor() {
+    /** @type {Map<string, { scope: string, supersedes: Set<string>, supersededBy: Set<string>, reasons: Map<string, string>, status: 'active'|'superseded', reason?: string }>} */
+    this.edges = new Map();
+  }
+
+  /**
+   * Registers a memory atom in the supersession graph.
+   * @param {string} id
+   * @param {{ scope?: string }} [meta]
+   */
+  registerNode(id, meta = {}) {
+    if (!id || typeof id !== 'string') {
+      throw new TypeError('Supersession node ID must be a non-empty string');
+    }
+    const scope = meta.scope || 'enigma.global';
+    const existing = this.edges.get(id);
+    if (existing) {
+      if (existing.scope !== scope) {
+        throw new Error(`Supersession node "${id}" is already registered in scope "${existing.scope}"`);
+      }
+      return;
+    }
+    this.edges.set(id, {
+      scope,
+      supersedes: new Set(),
+      supersededBy: new Set(),
+      reasons: new Map(),
+      status: 'active',
+      reason: undefined,
+    });
+  }
+
+  /**
+   * Records that newAtomId supersedes priorAtomId.
+   * Both nodes must already exist in the same scope.
+   * @param {string} newAtomId
+   * @param {string} priorAtomId
+   * @param {string} [reason]
+   */
+  recordSupersession(newAtomId, priorAtomId, reason = 'state_update') {
+    if (newAtomId === priorAtomId) {
+      throw new Error('A memory atom cannot supersede itself');
+    }
+    const newEntry = this.edges.get(newAtomId);
+    const priorEntry = this.edges.get(priorAtomId);
+    if (!newEntry || !priorEntry) {
+      const missing = [!newEntry ? newAtomId : null, !priorEntry ? priorAtomId : null].filter(Boolean);
+      throw new Error(`Unknown supersession node${missing.length > 1 ? 's' : ''}: ${missing.join(', ')}`);
+    }
+    if (newEntry.scope !== priorEntry.scope) {
+      throw new Error(`Cross-scope supersession is not allowed ("${newEntry.scope}" -> "${priorEntry.scope}")`);
+    }
+    if (newEntry.supersedes.has(priorAtomId)) {
+      newEntry.reasons.set(priorAtomId, reason);
+      priorEntry.reason = reason;
+      return;
+    }
+    if (this.#reaches(priorAtomId, newAtomId)) {
+      throw new Error(`Supersession edge "${newAtomId}" -> "${priorAtomId}" would create a cycle`);
+    }
+
+    newEntry.supersedes.add(priorAtomId);
+    newEntry.reasons.set(priorAtomId, reason);
+    priorEntry.supersededBy.add(newAtomId);
+    priorEntry.status = 'superseded';
+    priorEntry.reason = reason;
+  }
+
+  #reaches(startId, targetId) {
+    const pending = [startId];
+    const visited = new Set();
+    while (pending.length > 0) {
+      const id = pending.pop();
+      if (id === targetId) return true;
+      if (visited.has(id)) continue;
+      visited.add(id);
+      const entry = this.edges.get(id);
+      if (entry) pending.push(...entry.supersedes);
+    }
+    return false;
+  }
+
+  /**
+   * Removes a node and all incident edges. Used to roll back failed writes.
+   * @param {string} id
+   */
+  removeNode(id) {
+    const entry = this.edges.get(id);
+    if (!entry) return false;
+    for (const priorId of entry.supersedes) {
+      const prior = this.edges.get(priorId);
+      if (!prior) continue;
+      prior.supersededBy.delete(id);
+      if (prior.supersededBy.size === 0) {
+        prior.status = 'active';
+        prior.reason = undefined;
+      } else {
+        const remainingNewerId = prior.supersededBy.values().next().value;
+        prior.reason = this.edges.get(remainingNewerId)?.reasons.get(priorId);
+      }
+    }
+    for (const newerId of entry.supersededBy) {
+      const newer = this.edges.get(newerId);
+      newer?.supersedes.delete(id);
+      newer?.reasons.delete(id);
+    }
+    return this.edges.delete(id);
+  }
+
+  /**
+   * Checks if an atom is superseded by any newer record.
+   * @param {string} id
+   * @returns {boolean}
+   */
+  isSuperseded(id) {
+    const entry = this.edges.get(id);
+    return Boolean(entry && entry.supersededBy.size > 0);
+  }
+
+  /**
+   * Returns supersession lineage for an atom.
+   * @param {string} id
+   */
+  getLineage(id) {
+    const entry = this.edges.get(id);
+    if (!entry) return { supersedes: [], supersededBy: [], status: 'active' };
+    return {
+      supersedes: Array.from(entry.supersedes),
+      supersededBy: Array.from(entry.supersededBy),
+      status: entry.status,
+      reason: entry.reason,
+      scope: entry.scope,
+    };
+  }
+
+  /**
+   * Filters memory atoms to their current authoritative state.
+   * @param {Array<Object>} atoms
+   * @param {{ includeSuperseded?: boolean }} [options]
+   */
+  resolveActiveState(atoms, options = {}) {
+    const includeSuperseded = Boolean(options.includeSuperseded);
+    const result = [];
+    for (const atom of atoms) {
+      const isSup = this.isSuperseded(atom.id) || atom.metadata?.status === 'superseded';
+      if (!isSup || includeSuperseded) {
+        result.push({
+          ...atom,
+          _status: isSup ? 'superseded' : 'active',
+          _lineage: this.getLineage(atom.id),
+        });
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Serializes the complete scoped DAG. Reverse edges and statuses are derived on import.
+   */
+  exportState() {
+    const nodes = Array.from(this.edges, ([id, entry]) => ({ id, scope: entry.scope }))
+      .sort((a, b) => a.id.localeCompare(b.id));
+    const edges = [];
+    for (const [from, entry] of this.edges) {
+      for (const to of entry.supersedes) {
+        edges.push({ from, to, reason: entry.reasons.get(to) || 'state_update' });
+      }
+    }
+    edges.sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to));
+    return { schema: 'enigma.supersession_graph.v1', version: 1, nodes, edges };
+  }
+
+  /**
+   * Strictly imports and validates a serialized graph.
+   * @param {Object} state
+   * @param {Map<string, string>|Object<string, string>} [knownNodes]
+   */
+  importState(state, knownNodes) {
+    if (!state || state.schema !== 'enigma.supersession_graph.v1' || state.version !== 1
+      || !Array.isArray(state.nodes) || !Array.isArray(state.edges)) {
+      throw new Error('Invalid supersession graph state');
+    }
+    const expected = knownNodes instanceof Map
+      ? knownNodes
+      : new Map(Object.entries(knownNodes || {}));
+    const validateKnownNodes = knownNodes !== undefined;
+    const imported = new ContradictionGraph();
+    for (const node of state.nodes) {
+      if (!node || typeof node.id !== 'string' || !node.id || typeof node.scope !== 'string' || !node.scope) {
+        throw new Error('Invalid supersession graph node');
+      }
+      if (imported.edges.has(node.id)) {
+        throw new Error(`Duplicate supersession node "${node.id}"`);
+      }
+      if (validateKnownNodes) {
+        if (!expected.has(node.id)) throw new Error(`Unknown supersession node: ${node.id}`);
+        if (expected.get(node.id) !== node.scope) {
+          throw new Error(`Supersession node "${node.id}" has an invalid scope`);
+        }
+      }
+      imported.registerNode(node.id, { scope: node.scope });
+    }
+    if (validateKnownNodes) {
+      for (const [id, scope] of expected) {
+        if (!imported.edges.has(id)) imported.registerNode(id, { scope });
+      }
+    }
+    for (const edge of state.edges) {
+      if (!edge || typeof edge.from !== 'string' || !edge.from
+        || typeof edge.to !== 'string' || !edge.to
+        || (edge.reason !== undefined && typeof edge.reason !== 'string')) {
+        throw new Error('Invalid supersession graph edge');
+      }
+      imported.recordSupersession(edge.from, edge.to, edge.reason || 'state_update');
+    }
+    this.edges = imported.edges;
+    return this;
+  }
+}
+
+/**
+ * Heuristic detector for state contradiction between existing memories and a newly proposed statement.
+ * Checks for subject-predicate updates like "lives in [X]" vs "lives in [Y]", "using [A]" vs "stopped using [A], now using [B]".
+ * @param {string} newText
+ * @param {Array<{ id: string, text: string }>} candidateMemories
+ * @returns {Array<{ priorId: string, confidence: number, reason: string }>}
+ */
+export function detectContradictions(newText, candidateMemories = []) {
+  if (!newText || typeof newText !== 'string' || candidateMemories.length === 0) {
+    return [];
+  }
+
+  const conflicts = [];
+  const lowerNew = newText.toLowerCase();
+
+  for (const candidate of candidateMemories) {
+    const lowerOld = candidate.text.toLowerCase();
+
+    // 1. Relocation / Living location updates ("lives in X" -> "moved to Y")
+    if (
+      (lowerNew.includes('moved to ') || lowerNew.includes('now lives in ')) &&
+      (lowerOld.includes('lives in ') || lowerOld.includes('living in ')) &&
+      hasVerifiedSharedContext(newText, candidate.text, 'location')
+    ) {
+      conflicts.push({
+        priorId: candidate.id,
+        confidence: 0.95,
+        reason: 'location_relocation_detected',
+      });
+      continue;
+    }
+
+    // 2. Service / Tool cessation ("stopped using X" -> "using Y now")
+    if (
+      (lowerNew.includes('stopped using ') || lowerNew.includes('no longer use ') || lowerNew.includes('switched to ')) &&
+      (lowerOld.includes('favorite ') || lowerOld.includes('uses ') || lowerOld.includes('using ')) &&
+      hasVerifiedSharedContext(newText, candidate.text, 'service')
+    ) {
+      conflicts.push({
+        priorId: candidate.id,
+        confidence: 0.90,
+        reason: 'service_supersession_detected',
+      });
+      continue;
+    }
+
+    // 3. Preference changes ("changed preference to X", "prefers X instead of Y")
+    if (
+      (lowerNew.includes('changed preference') || lowerNew.includes('prefer ') || lowerNew.includes('now prefer ')) &&
+      (lowerOld.includes('prefer ') || lowerOld.includes('prefers ')) &&
+      hasVerifiedSharedContext(newText, candidate.text, 'preference')
+    ) {
+      // Check for token overlap to prevent false positives on distinct topics
+      const newTokens = new Set(lowerNew.split(/\W+/).filter(w => w.length > 3));
+      const oldTokens = lowerOld.split(/\W+/).filter(w => w.length > 3);
+      const overlap = oldTokens.filter(t => newTokens.has(t)).length;
+
+      if (overlap >= 2) {
+        conflicts.push({
+          priorId: candidate.id,
+          confidence: 0.85,
+          reason: 'preference_updated',
+        });
+      }
+    }
+  }
+
+  return conflicts;
+}

package/packages/sdk/src/intelligence/decision-engine.js

@@ -0,0 +1,155 @@
+// Enigma Memory Intelligence: Memory Decision & Consolidation Engine.
+// Evaluates observation novelty, filters transient conversation noise,
+// and consolidates redundant memory clusters.
+import { inferMemoryType, DEFAULT_TYPE_WEIGHTS } from './ontology.js';
+import { detectContradictions } from './contradiction.js';
+
+const NOISE_WORDS = new Set([
+  'ok', 'okay', 'got', 'it', 'thanks', 'thank', 'you', 'cool', 'yes', 'no',
+  'sure', 'yep', 'nope', 'hi', 'hello', 'hey', 'bye', 'i', 'see', 'understood',
+  'makes', 'sense', 'great', 'perfect', 'will', 'do', 'alright', 'k'
+]);
+
+export function isTransientNoise(text) {
+  if (!text || typeof text !== 'string') return true;
+  const tokens = text.toLowerCase().replace(/[^a-z\s]/g, '').trim().split(/\s+/).filter(Boolean);
+  if (tokens.length === 0) return true;
+  if (tokens.length <= 5 && tokens.every(t => NOISE_WORDS.has(t))) {
+    return true;
+  }
+  return false;
+}
+
+export class MemoryDecisionEngine {
+  /**
+   * @param {Object} [options]
+   * @param {number} [options.minNoveltyThreshold=0.25]
+   * @param {number} [options.minImportanceThreshold=0.3]
+   */
+  constructor(options = {}) {
+    this.minNoveltyThreshold = options.minNoveltyThreshold ?? 0.25;
+    this.minImportanceThreshold = options.minImportanceThreshold ?? 0.3;
+  }
+
+  /**
+   * Evaluates an incoming observation to decide if it warrants sovereign vault persistence.
+   * @param {string} text
+   * @param {Object} [metadata={}]
+   * @param {Array<{ id: string, text: string }>} [existingMemories=[]]
+   * @returns {{ shouldRemember: boolean, novelty: number, importance: number, type: string, conflicts: Array<Object>, reason: string }}
+   */
+  evaluate(text, metadata = {}, existingMemories = []) {
+    if (!text || typeof text !== 'string' || text.trim().length === 0) {
+      return { shouldRemember: false, novelty: 0, importance: 0, type: 'semantic', conflicts: [], reason: 'empty_text' };
+    }
+
+    const trimmed = text.trim();
+
+    // 1. Transient noise filter
+    if (isTransientNoise(trimmed)) {
+      return {
+        shouldRemember: false,
+        novelty: 0.05,
+        importance: 0.05,
+        type: 'working',
+        conflicts: [],
+        reason: 'transient_chat_chatter_filtered',
+      };
+    }
+
+    // 2. Infer ontology type & base importance weight
+    const type = metadata.type || inferMemoryType(trimmed);
+    const typeMultiplier = DEFAULT_TYPE_WEIGHTS[type] || 1.0;
+    const explicitImportance = typeof metadata.importance === 'number' ? metadata.importance : 1.0;
+    const computedImportance = Math.min(2.5, explicitImportance * typeMultiplier);
+
+    // 3. Compute novelty against existing memory corpus
+    const novelty = this.computeNovelty(trimmed, existingMemories);
+
+    // 4. Detect contradictions / supersessions
+    const conflicts = detectContradictions(trimmed, existingMemories);
+
+    // 5. Decision logic: Policies and preferences are always remembered
+    const isCriticalType = type === 'policy' || type === 'preference' || type === 'identity';
+    const hasSufficientSignal = novelty >= this.minNoveltyThreshold && computedImportance >= this.minImportanceThreshold;
+    const shouldRemember = isCriticalType || hasSufficientSignal || conflicts.length > 0;
+
+    return {
+      shouldRemember,
+      novelty: Math.round(novelty * 100) / 100,
+      importance: Math.round(computedImportance * 100) / 100,
+      type,
+      conflicts,
+      reason: shouldRemember ? 'high_value_signal_accepted' : 'redundant_or_low_signal',
+    };
+  }
+
+  /**
+   * Computes lexical novelty score (0.0 to 1.0) against existing memories.
+   * @param {string} text
+   * @param {Array<{ id: string, text: string }>} existing
+   * @returns {number}
+   */
+  computeNovelty(text, existing = []) {
+    if (existing.length === 0) return 1.0;
+
+    const newTokens = new Set(text.toLowerCase().split(/\W+/).filter(w => w.length > 2));
+    if (newTokens.size === 0) return 0.5;
+
+    let maxOverlapRatio = 0;
+
+    for (const item of existing) {
+      const oldTokens = new Set(item.text.toLowerCase().split(/\W+/).filter(w => w.length > 2));
+      if (oldTokens.size === 0) continue;
+
+      let overlapCount = 0;
+      for (const t of newTokens) {
+        if (oldTokens.has(t)) overlapCount++;
+      }
+
+      const ratio = overlapCount / Math.max(newTokens.size, oldTokens.size);
+      if (ratio > maxOverlapRatio) maxOverlapRatio = ratio;
+    }
+
+    return Math.max(0.0, 1.0 - maxOverlapRatio);
+  }
+
+  /**
+   * Consolidates redundant memory atoms into a concise summary record.
+   * @param {Array<{ id: string, text: string, type?: string, createdAt: number }>} memories
+   * @returns {Array<{ id: string, text: string, consolidatedFrom: string[], type: string }>}
+   */
+  consolidate(memories = []) {
+    if (memories.length <= 1) return memories;
+
+    // Group memories by category/topic
+    const clusters = new Map();
+    for (const mem of memories) {
+      const type = mem.type || 'semantic';
+      if (!clusters.has(type)) clusters.set(type, []);
+      clusters.get(type).push(mem);
+    }
+
+    const consolidated = [];
+    for (const [type, items] of clusters.entries()) {
+      if (items.length <= 3) {
+        consolidated.push(...items);
+        continue;
+      }
+
+      // Consolidate cluster into deduplicated items
+      const uniqueTexts = Array.from(new Set(items.map(i => i.text.trim())));
+      const sourceIds = items.map(i => i.id);
+
+      consolidated.push({
+        id: `consolidated_${type}_${Date.now()}`,
+        text: uniqueTexts.join('; '),
+        consolidatedFrom: sourceIds,
+        type,
+        createdAt: Date.now(),
+      });
+    }
+
+    return consolidated;
+  }
+}

package/packages/sdk/src/intelligence/index.js

@@ -0,0 +1,4 @@
+export * from './ontology.js';
+export * from './temporal.js';
+export * from './contradiction.js';
+export * from './decision-engine.js';

package/packages/sdk/src/intelligence/ontology.js

@@ -0,0 +1,122 @@
+// Enigma Memory Intelligence: Structured Memory Ontology & Taxonomy.
+// Distinguishes episodic events, semantic facts, agent preferences,
+// procedural workflows, security policies, and working context.
+
+export const MEMORY_TYPES = Object.freeze({
+  EPISODIC: 'episodic',       // Temporal events: "User executed trade #42 at 14:02"
+  SEMANTIC: 'semantic',       // General facts: "Solana slot time is approximately 400ms"
+  PROCEDURAL: 'procedural',   // Workflows / how-to: "To anchor a note tree, call settleIntent()"
+  PREFERENCE: 'preference',   // Actor preferences: "User prefers max 0.5% slippage on Raydium"
+  POLICY: 'policy',           // Governance & safety rules: "Never execute trades exceeding 10 SOL without 2FA"
+  IDENTITY: 'identity',       // Persistent facts: "Agent pubkey is 42d8ea..."
+  GOAL: 'goal',               // Future targets: "Reach 99.9% uptime on GhostMesh relay"
+  WORKING: 'working',         // Ephemeral scratchpad / session context
+});
+
+export const VALID_MEMORY_TYPES = new Set(Object.values(MEMORY_TYPES));
+
+export const DEFAULT_TYPE_WEIGHTS = Object.freeze({
+  [MEMORY_TYPES.POLICY]: 2.5,     // Policies & safety rules have highest default retrieval priority
+  [MEMORY_TYPES.IDENTITY]: 2.0,   // Core identity facts
+  [MEMORY_TYPES.PREFERENCE]: 1.8, // User preferences heavily shape responses
+  [MEMORY_TYPES.GOAL]: 1.5,
+  [MEMORY_TYPES.PROCEDURAL]: 1.3,
+  [MEMORY_TYPES.SEMANTIC]: 1.0,
+  [MEMORY_TYPES.EPISODIC]: 0.9,
+  [MEMORY_TYPES.WORKING]: 0.7,
+});
+
+/**
+ * Validates and normalizes memory type. Defaults to 'semantic' if omitted or unrecognized.
+ * @param {string} [type]
+ * @returns {string} Normalized memory type
+ */
+export function normalizeMemoryType(type) {
+  if (!type || typeof type !== 'string') return MEMORY_TYPES.SEMANTIC;
+  const normalized = type.trim().toLowerCase();
+  return VALID_MEMORY_TYPES.has(normalized) ? normalized : MEMORY_TYPES.SEMANTIC;
+}
+
+/**
+ * Automatically infers memory ontology type from text patterns and keywords.
+ * @param {string} text
+ * @returns {string} Inferred memory type
+ */
+export function inferMemoryType(text) {
+  if (!text || typeof text !== 'string') return MEMORY_TYPES.SEMANTIC;
+  const lower = text.toLowerCase();
+
+  // 1. Policy & Security Invariants
+  if (
+    lower.includes('never ') ||
+    lower.includes('must not') ||
+    lower.includes('prohibited') ||
+    lower.includes('always require') ||
+    lower.includes('policy:') ||
+    lower.includes('invariant:') ||
+    lower.includes('rule:') ||
+    lower.includes('security rule')
+  ) {
+    return MEMORY_TYPES.POLICY;
+  }
+
+  // 2. Preferences
+  if (
+    lower.includes('prefer') ||
+    lower.includes('likes') ||
+    lower.includes('dislikes') ||
+    lower.includes('favorite') ||
+    lower.includes('always use') ||
+    lower.includes('setting:') ||
+    lower.includes('preference:')
+  ) {
+    return MEMORY_TYPES.PREFERENCE;
+  }
+
+  // 3. Procedural / Workflows
+  if (
+    lower.includes('how to') ||
+    lower.includes('steps to') ||
+    lower.includes('procedure:') ||
+    lower.includes('workflow:') ||
+    lower.includes('first, ') && lower.includes('then, ')
+  ) {
+    return MEMORY_TYPES.PROCEDURAL;
+  }
+
+  // 4. Goals
+  if (
+    lower.includes('goal:') ||
+    lower.includes('target:') ||
+    lower.includes('objective:') ||
+    lower.includes('aim to') ||
+    lower.includes('milestone:')
+  ) {
+    return MEMORY_TYPES.GOAL;
+  }
+
+  // 5. Identity
+  if (
+    lower.includes('my name is') ||
+    lower.includes('i am an ai') ||
+    lower.includes('agent id') ||
+    lower.includes('public key') ||
+    lower.includes('pubkey')
+  ) {
+    return MEMORY_TYPES.IDENTITY;
+  }
+
+  // 6. Episodic (timestamps, events, actions)
+  if (
+    lower.includes('yesterday') ||
+    lower.includes('today at') ||
+    lower.includes('executed') ||
+    lower.includes('happened') ||
+    lower.includes('received signal') ||
+    /\b(20\d\d-\d\d-\d\d|\d{1,2}:\d{2})\b/.test(lower)
+  ) {
+    return MEMORY_TYPES.EPISODIC;
+  }
+
+  return MEMORY_TYPES.SEMANTIC;
+}