fatcrapinmybutt/SINGULARITY-MBP-APEX-MEMORY

SINGULARITY-MBP-APEX-MEMORY v1.0

The graph that remembers everything and forgets nothing important. Cognitive-science-grounded tri-layer memory architecture for litigation intelligence. Atkinson & Shiffrin (1968) meets A-MEM Zettelkasten (2025) meets Mem0 (2024).

---

Layer 1: Working Memory — Active Investigation Context

1.1 WorkingMemory Class (JavaScript — D3.js integration)

/**
 * WorkingMemory — capacity-limited attention buffer for active investigation.
 *
 * Cognitive model: Baddeley's working memory (2000) — central executive +
 * phonological loop + visuospatial sketchpad. Here: central executive =
 * attention allocator, buffer = Map<id, MemoryItem>, capacity = top-K.
 *
 * Decay follows Ebbinghaus (1885): R = e^(-t/S) where t = time since last
 * access, S = stability (increases with each access — spacing effect).
 */
class WorkingMemory {
  constructor(options = {}) {
    this.capacity = options.capacity || 50;
    this.decayHalfLife = options.decayHalfLife || 300000; // 5 min in ms
    this.minSalience = options.minSalience || 0.01;
    this.items = new Map(); // id → MemoryItem
    this._decayTimer = null;
    this._listeners = new Set();
    this._restore();
  }

  /** Persist snapshot to sessionStorage (survives page reloads, not tab close). */
  _persist() {
    const data = [];
    for (const [id, item] of this.items) {
      data.push([id, { ...item }]);
    }
    try {
      sessionStorage.setItem('mbp_working_memory', JSON.stringify(data));
    } catch (e) { /* quota exceeded — silently degrade */ }
  }

  _restore() {
    try {
      const raw = sessionStorage.getItem('mbp_working_memory');
      if (!raw) return;
      const data = JSON.parse(raw);
      for (const [id, item] of data) {
        this.items.set(id, item);
      }
    } catch (e) { /* corrupt — start fresh */ }
  }

  /**
   * Add an item to working memory. If at capacity, evict lowest-salience item.
   * @param {string} id — unique evidence/node identifier
   * @param {object} payload — { type, label, lane, source, evidence_refs }
   * @param {number} importance — base importance [0,1], default 0.5
   * @returns {object|null} evicted item, or null
   */
  add(id, payload, importance = 0.5) {
    const now = Date.now();
    let evicted = null;

    if (this.items.has(id)) {
      this.access(id);
      return null;
    }

    if (this.items.size >= this.capacity) {
      evicted = this._evictLowest();
    }

    this.items.set(id, {
      id,
      payload,
      importance,
      salience: importance,
      accessCount: 1,
      stability: 1.0,
      addedAt: now,
      lastAccessed: now,
      decayedSalience: importance
    });

    this._notify('add', id);
    this._persist();
    return evicted;
  }

  /**
   * Access an item — resets decay timer, increases stability (spacing effect).
   * Stability grows logarithmically: S_new = S_old + ln(1 + accessCount).
   */
  access(id) {
    const item = this.items.get(id);
    if (!item) return null;

    const now = Date.now();
    const timeSinceLast = now - item.lastAccessed;

    item.accessCount += 1;
    item.lastAccessed = now;
    // Spacing effect: longer intervals between accesses → greater stability gain
    const spacingBonus = Math.min(timeSinceLast / this.decayHalfLife, 2.0);
    item.stability += Math.log1p(item.accessCount) * (0.5 + spacingBonus * 0.5);
    item.salience = Math.min(item.importance + 0.1 * item.accessCount, 1.0);
    item.decayedSalience = item.salience;

    this._notify('access', id);
    this._persist();
    return item;
  }

  /**
   * Decay all items. Called on a timer (default every 30s).
   * R = e^(-t / (S * halfLife)) — Ebbinghaus with stability multiplier.
   */
  decay() {
    const now = Date.now();
    const toRemove = [];

    for (const [id, item] of this.items) {
      const elapsed = now - item.lastAccessed;
      const effectiveHalfLife = this.decayHalfLife * item.stability;
      const retention = Math.exp(-elapsed / effectiveHalfLife);
      item.decayedSalience = Math.max(item.salience * retention, this.minSalience);

      if (item.decayedSalience <= this.minSalience && item.accessCount <= 1) {
        toRemove.push(id);
      }
    }

    for (const id of toRemove) {
      this._notify('decay_evict', id);
      this.items.delete(id);
    }

    this._persist();
    return toRemove;
  }

  /** Get active items sorted by decayed salience (highest first). */
  getActive(limit = null) {
    this.decay();
    const sorted = [...this.items.values()]
      .sort((a, b) => b.decayedSalience - a.decayedSalience);
    return limit ? sorted.slice(0, limit) : sorted;
  }

  /** Highlight working memory items on the D3.js force graph. */
  highlight(nodeSelection) {
    const activeIds = new Set(this.items.keys());
    nodeSelection
      .transition().duration(300)
      .attr('stroke', d => activeIds.has(d.id) ? '#FF4444' : null)
      .attr('stroke-width', d => activeIds.has(d.id) ?
        2 + 3 * (this.items.get(d.id)?.decayedSalience || 0) : 0)
      .attr('stroke-opacity', d => activeIds.has(d.id) ?
        0.3 + 0.7 * (this.items.get(d.id)?.decayedSalience || 0) : 0);
  }

  /** Start automatic decay timer. */
  startDecayLoop(intervalMs = 30000) {
    this.stopDecayLoop();
    this._decayTimer = setInterval(() => this.decay(), intervalMs);
  }

  stopDecayLoop() {
    if (this._decayTimer) {
      clearInterval(this._decayTimer);
      this._decayTimer = null;
    }
  }

  /** Subscribe to memory events: add, access, decay_evict, evict. */
  subscribe(fn) { this._listeners.add(fn); return () => this._listeners.delete(fn); }
  _notify(event, id) { for (const fn of this._listeners) fn(event, id, this.items.get(id)); }

  _evictLowest() {
    let lowestId = null, lowestSalience = Infinity;
    for (const [id, item] of this.items) {
      if (item.decayedSalience < lowestSalience) {
        lowestSalience = item.decayedSalience;
        lowestId = id;
      }
    }
    if (lowestId) {
      const evicted = this.items.get(lowestId);
      this.items.delete(lowestId);
      this._notify('evict', lowestId);
      return evicted;
    }
    return null;
  }

  /** Get capacity utilization stats. */
  stats() {
    const items = [...this.items.values()];
    return {
      size: items.length,
      capacity: this.capacity,
      utilization: items.length / this.capacity,
      avgSalience: items.length ? items.reduce((s, i) => s + i.decayedSalience, 0) / items.length : 0,
      topItem: items.sort((a, b) => b.decayedSalience - a.decayedSalience)[0] || null,
      totalAccesses: items.reduce((s, i) => s + i.accessCount, 0)
    };
  }

  /** Export for promotion to episodic memory. */
  exportForPromotion(minAccesses = 3, minSalience = 0.3) {
    return [...this.items.values()].filter(
      i => i.accessCount >= minAccesses && i.decayedSalience >= minSalience
    );
  }

  clear() { this.items.clear(); this._persist(); }
}

1.2 WorkingMemoryDB (Python — SQLite persistence bridge)

"""Working memory persistence bridge — snapshots to SQLite for cross-session recall."""
import sqlite3
import json
import time
import re
from pathlib import Path

DB_PATH = Path(__file__).resolve().parents[3] / "litigation_context.db"

def _sanitize_fts5(query: str) -> str:
    return re.sub(r'[^\w\s*"]', ' ', query).strip()

class WorkingMemoryDB:
    """Persist working memory snapshots to SQLite for post-session analysis."""

    DDL = """
    CREATE TABLE IF NOT EXISTS working_memory_snapshots (
        snapshot_id INTEGER PRIMARY KEY AUTOINCREMENT,
        session_id TEXT NOT NULL,
        timestamp REAL NOT NULL,
        items_json TEXT NOT NULL,
        item_count INTEGER NOT NULL,
        avg_salience REAL,
        top_item_id TEXT,
        created_at TEXT DEFAULT (datetime('now'))
    );
    CREATE INDEX IF NOT EXISTS idx_wm_session ON working_memory_snapshots(session_id);
    CREATE INDEX IF NOT EXISTS idx_wm_timestamp ON working_memory_snapshots(timestamp);
    """

    def __init__(self, db_path=None, session_id=None):
        self.db_path = db_path or str(DB_PATH)
        self.session_id = session_id or f"session_{int(time.time())}"
        self.conn = sqlite3.connect(self.db_path)
        self.conn.execute("PRAGMA busy_timeout = 60000")
        self.conn.execute("PRAGMA journal_mode = WAL")
        self.conn.execute("PRAGMA cache_size = -32000")
        self.conn.executescript(self.DDL)
        self.conn.commit()

    def save_snapshot(self, items: list[dict]) -> int:
        """Save a working memory snapshot. Returns snapshot_id."""
        avg_sal = sum(i.get('decayedSalience', 0) for i in items) / max(len(items), 1)
        top = max(items, key=lambda i: i.get('decayedSalience', 0)) if items else {}
        cur = self.conn.execute(
            """INSERT INTO working_memory_snapshots
               (session_id, timestamp, items_json, item_count, avg_salience, top_item_id)
               VALUES (?, ?, ?, ?, ?, ?)""",
            (self.session_id, time.time(), json.dumps(items),
             len(items), round(avg_sal, 4), top.get('id'))
        )
        self.conn.commit()
        return cur.lastrowid

    def load_latest(self, session_id=None) -> list[dict]:
        """Load most recent snapshot for a session."""
        sid = session_id or self.session_id
        row = self.conn.execute(
            """SELECT items_json FROM working_memory_snapshots
               WHERE session_id = ? ORDER BY timestamp DESC LIMIT 1""",
            (sid,)
        ).fetchone()
        return json.loads(row[0]) if row else []

    def get_session_trajectory(self, session_id=None, limit=50) -> list[dict]:
        """Get salience trajectory over a session — useful for visualizing attention drift."""
        sid = session_id or self.session_id
        rows = self.conn.execute(
            """SELECT timestamp, item_count, avg_salience, top_item_id
               FROM working_memory_snapshots
               WHERE session_id = ? ORDER BY timestamp ASC LIMIT ?""",
            (sid, limit)
        ).fetchall()
        return [
            {"timestamp": r[0], "count": r[1], "avg_salience": r[2], "top_item": r[3]}
            for r in rows
        ]

    def close(self):
        self.conn.close()

---

Layer 2: Episodic Memory — Temporal Event Retrieval

2.1 EpisodicMemory Class (JavaScript)

/**
 * EpisodicMemory — specific litigation events with temporal + causal indexing.
 *
 * Cognitive model: Tulving's episodic memory (1972) — "mental time travel."
 * Each episode encodes: what happened, when, who, where, why, and emotional
 * valence (high-harm events like jail/separation get elevated retention).
 *
 * Backed by timeline_events (16.8K rows) + evidence_quotes (175K rows) via
 * Python bridge. JavaScript side holds a session-local cache for fast D3.js
 * rendering; authoritative store is always SQLite.
 */
class EpisodicMemory {
  constructor() {
    this.episodes = new Map();       // id → Episode
    this.causalLinks = new Map();    // id → Set<caused_id>
    this.actorIndex = new Map();     // actor → Set<episode_id>
    this.temporalIndex = [];         // sorted by timestamp for binary search
    this._dirty = false;
  }

  /**
   * Record a new episode.
   * @param {object} episode — { event_id, timestamp, actors[], action, location,
   *   evidence_refs[], emotional_valence, lane, source_table, source_id }
   */
  record(episode) {
    const e = {
      ...episode,
      id: episode.event_id || `ep_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
      recordedAt: Date.now(),
      accessCount: 0,
      consolidationScore: 0
    };

    this.episodes.set(e.id, e);

    // Actor index
    for (const actor of (e.actors || [])) {
      const key = actor.toLowerCase();
      if (!this.actorIndex.has(key)) this.actorIndex.set(key, new Set());
      this.actorIndex.get(key).add(e.id);
    }

    // Temporal index — insert sorted
    this._insertTemporal(e);
    this._dirty = true;
    return e;
  }

  _insertTemporal(episode) {
    const ts = new Date(episode.timestamp).getTime();
    let lo = 0, hi = this.temporalIndex.length;
    while (lo < hi) {
      const mid = (lo + hi) >>> 1;
      const midTs = new Date(this.temporalIndex[mid].timestamp).getTime();
      if (midTs < ts) lo = mid + 1; else hi = mid;
    }
    this.temporalIndex.splice(lo, 0, episode);
  }

  /**
   * Temporal retrieval: events between two dates.
   * O(log n) start via binary search + O(k) for k results.
   */
  retrieveByDateRange(startDate, endDate) {
    const startTs = new Date(startDate).getTime();
    const endTs = new Date(endDate).getTime();

    let lo = 0, hi = this.temporalIndex.length;
    while (lo < hi) {
      const mid = (lo + hi) >>> 1;
      if (new Date(this.temporalIndex[mid].timestamp).getTime() < startTs) lo = mid + 1;
      else hi = mid;
    }

    const results = [];
    for (let i = lo; i < this.temporalIndex.length; i++) {
      const ts = new Date(this.temporalIndex[i].timestamp).getTime();
      if (ts > endTs) break;
      const ep = this.temporalIndex[i];
      ep.accessCount = (ep.accessCount || 0) + 1;
      results.push(ep);
    }
    return results;
  }

  /** Actor-centric retrieval: all episodes involving a specific person. */
  retrieveByActor(actorName) {
    const key = actorName.toLowerCase();
    const ids = this.actorIndex.get(key);
    if (!ids) return [];
    return [...ids].map(id => {
      const ep = this.episodes.get(id);
      if (ep) ep.accessCount = (ep.accessCount || 0) + 1;
      return ep;
    }).filter(Boolean).sort((a, b) =>
      new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime()
    );
  }

  /**
   * Link two episodes causally: episode A caused episode B.
   * Causal chains enable "why did this happen?" reasoning.
   */
  linkCausal(causeId, effectId) {
    if (!this.episodes.has(causeId) || !this.episodes.has(effectId)) return false;
    if (!this.causalLinks.has(causeId)) this.causalLinks.set(causeId, new Set());
    this.causalLinks.get(causeId).add(effectId);
    this._dirty = true;
    return true;
  }

  /**
   * Find causal chain starting from a root episode.
   * BFS traversal of causal links — returns ordered chain.
   */
  findCausalChain(rootId, maxDepth = 10) {
    const chain = [];
    const visited = new Set();
    const queue = [{ id: rootId, depth: 0 }];

    while (queue.length > 0) {
      const { id, depth } = queue.shift();
      if (visited.has(id) || depth > maxDepth) continue;
      visited.add(id);

      const ep = this.episodes.get(id);
      if (ep) {
        chain.push({ ...ep, causalDepth: depth });
        const effects = this.causalLinks.get(id);
        if (effects) {
          for (const effectId of effects) {
            queue.push({ id: effectId, depth: depth + 1 });
          }
        }
      }
    }
    return chain;
  }

  /**
   * Consolidation: promote important working memory items to episodic memory.
   * Called at session end or on explicit save.
   */
  consolidate(workingMemoryItems) {
    const promoted = [];
    for (const item of workingMemoryItems) {
      if (this.episodes.has(item.id)) {
        const existing = this.episodes.get(item.id);
        existing.consolidationScore += item.decayedSalience;
        existing.accessCount += item.accessCount;
        continue;
      }
      const episode = this.record({
        event_id: item.id,
        timestamp: new Date(item.addedAt).toISOString(),
        actors: item.payload?.actors || [],
        action: item.payload?.label || 'investigated',
        location: item.payload?.lane || 'UNKNOWN',
        evidence_refs: item.payload?.evidence_refs || [],
        emotional_valence: item.importance > 0.7 ? 'HIGH' : 'NORMAL',
        lane: item.payload?.lane || null,
        source_table: 'working_memory',
        source_id: item.id
      });
      episode.consolidationScore = item.decayedSalience * item.accessCount;
      promoted.push(episode);
    }
    this._dirty = true;
    return promoted;
  }

  stats() {
    const episodes = [...this.episodes.values()];
    const lanes = {};
    for (const ep of episodes) {
      const l = ep.lane || 'UNKNOWN';
      lanes[l] = (lanes[l] || 0) + 1;
    }
    return {
      totalEpisodes: episodes.length,
      causalChains: this.causalLinks.size,
      uniqueActors: this.actorIndex.size,
      byLane: lanes,
      avgConsolidation: episodes.length ?
        episodes.reduce((s, e) => s + (e.consolidationScore || 0), 0) / episodes.length : 0
    };
  }
}

2.2 EpisodicMemoryDB (Python — timeline_events + evidence_quotes bridge)

"""Episodic memory bridge — queries timeline_events and evidence_quotes via FTS5."""
import sqlite3
import json
import re
from pathlib import Path

DB_PATH = Path(__file__).resolve().parents[3] / "litigation_context.db"

def _sanitize_fts5(query: str) -> str:
    return re.sub(r'[^\w\s*"]', ' ', query).strip()

class EpisodicMemoryDB:
    """Query litigation_context.db for episodic memory items."""

    def __init__(self, db_path=None):
        self.db_path = db_path or str(DB_PATH)
        self.conn = sqlite3.connect(self.db_path)
        self.conn.execute("PRAGMA busy_timeout = 60000")
        self.conn.execute("PRAGMA journal_mode = WAL")
        self.conn.execute("PRAGMA cache_size = -32000")
        self.conn.row_factory = sqlite3.Row

    def retrieve_by_date_range(self, start_date: str, end_date: str,
                                lane: str = None, limit: int = 200) -> list[dict]:
        """Temporal retrieval from timeline_events."""
        sql = """SELECT rowid, event_date, event_description, source_document,
                        category, actor, lane
                 FROM timeline_events
                 WHERE event_date BETWEEN ? AND ?"""
        params = [start_date, end_date]
        if lane:
            sql += " AND lane = ?"
            params.append(lane)
        sql += " ORDER BY event_date ASC LIMIT ?"
        params.append(limit)
        rows = self.conn.execute(sql, params).fetchall()
        return [dict(r) for r in rows]

    def retrieve_by_actor(self, actor_name: str, limit: int = 100) -> list[dict]:
        """Actor-centric retrieval — searches actor column + FTS5 fallback."""
        # Direct column match first (fast, indexed)
        rows = self.conn.execute(
            """SELECT rowid, event_date, event_description, source_document,
                      category, actor, lane
               FROM timeline_events
               WHERE actor LIKE ? ORDER BY event_date ASC LIMIT ?""",
            (f"%{actor_name}%", limit)
        ).fetchall()

        if not rows:
            # FTS5 fallback
            sanitized = _sanitize_fts5(actor_name)
            if sanitized:
                try:
                    rows = self.conn.execute(
                        """SELECT t.rowid, t.event_date, t.event_description,
                                  t.source_document, t.category, t.actor, t.lane
                           FROM timeline_fts f
                           JOIN timeline_events t ON f.rowid = t.rowid
                           WHERE timeline_fts MATCH ?
                           ORDER BY rank LIMIT ?""",
                        (sanitized, limit)
                    ).fetchall()
                except sqlite3.OperationalError:
                    rows = self.conn.execute(
                        """SELECT rowid, event_date, event_description,
                                  source_document, category, actor, lane
                           FROM timeline_events
                           WHERE event_description LIKE ?
                           ORDER BY event_date ASC LIMIT ?""",
                        (f"%{actor_name}%", limit)
                    ).fetchall()
        return [dict(r) for r in rows]

    def find_causal_candidates(self, event_date: str, actor: str,
                                window_days: int = 7, limit: int = 20) -> list[dict]:
        """Find temporally proximate events by the same actor — causal chain candidates."""
        rows = self.conn.execute(
            """SELECT rowid, event_date, event_description, source_document,
                      category, actor, lane
               FROM timeline_events
               WHERE actor LIKE ?
                 AND event_date BETWEEN date(?, '-' || ? || ' days')
                                    AND date(?, '+' || ? || ' days')
                 AND event_date != ?
               ORDER BY event_date ASC LIMIT ?""",
            (f"%{actor}%", event_date, window_days, event_date, window_days,
             event_date, limit)
        ).fetchall()
        return [dict(r) for r in rows]

    def get_evidence_for_episode(self, event_description: str,
                                  limit: int = 10) -> list[dict]:
        """Find supporting evidence_quotes for an episode via FTS5."""
        sanitized = _sanitize_fts5(event_description[:100])
        if not sanitized:
            return []
        try:
            rows = self.conn.execute(
                """SELECT e.rowid, e.quote_text, e.source_file, e.category,
                          e.lane, e.page_number
                   FROM evidence_fts f
                   JOIN evidence_quotes e ON f.rowid = e.rowid
                   WHERE evidence_fts MATCH ?
                   ORDER BY rank LIMIT ?""",
                (sanitized, limit)
            ).fetchall()
        except sqlite3.OperationalError:
            rows = self.conn.execute(
                """SELECT rowid, quote_text, source_file, category, lane, page_number
                   FROM evidence_quotes
                   WHERE quote_text LIKE ?
                   LIMIT ?""",
                (f"%{sanitized[:40]}%", limit)
            ).fetchall()
        return [dict(r) for r in rows]

    def close(self):
        self.conn.close()

---

Layer 3: Semantic Memory — Legal Knowledge Network

3.1 SemanticMemory Class (JavaScript)

/**
 * SemanticMemory — general legal knowledge: rules, authorities, precedents, doctrines.
 *
 * Cognitive model: Tulving's semantic memory (1972) — decontextualized knowledge.
 * Unlike episodic (specific events), semantic stores abstract patterns and rules.
 *
 * Concept network: MCR/MCL rules → elements → case law → doctrines.
 * Backed by authority_chains_v2 (167K), michigan_rules_extracted (19.8K),
 * master_citations (72K) via Python bridge.
 */
class SemanticMemory {
  constructor() {
    this.concepts = new Map();      // concept_id → ConceptNode
    this.relations = new Map();     // concept_id → [{ target, relation, strength }]
    this.schemas = new Map();       // schema_name → { pattern, instances[], confidence }
    this.abstractions = new Map();  // abstraction_id → { label, source_episodes[], pattern }
  }

  /**
   * Store a concept (rule, authority, doctrine).
   * @param {string} id — unique concept identifier (e.g., 'MCL_722_23_j')
   * @param {object} concept — { label, type, elements[], authority_text, lane, confidence }
   */
  store(id, concept) {
    const existing = this.concepts.get(id);
    if (existing) {
      existing.accessCount += 1;
      existing.lastAccessed = Date.now();
      existing.confidence = Math.min(
        (existing.confidence + concept.confidence) / 2 + 0.05, 1.0
      );
      return existing;
    }

    const node = {
      id,
      ...concept,
      accessCount: 1,
      createdAt: Date.now(),
      lastAccessed: Date.now(),
      confidence: concept.confidence || 0.5,
      linkedEpisodes: []
    };
    this.concepts.set(id, node);
    return node;
  }

  /** Link two concepts with a typed relation. */
  relate(sourceId, targetId, relation, strength = 0.5) {
    if (!this.relations.has(sourceId)) this.relations.set(sourceId, []);
    const existing = this.relations.get(sourceId)
      .find(r => r.target === targetId && r.relation === relation);
    if (existing) {
      existing.strength = Math.min(existing.strength + 0.1, 1.0);
      return;
    }
    this.relations.get(sourceId).push({ target: targetId, relation, strength });
  }

  /**
   * Retrieve concepts by type or keyword.
   * Searches label, type, and elements.
   */
  retrieve(query, options = {}) {
    const q = query.toLowerCase();
    const typeFilter = options.type || null;
    const minConfidence = options.minConfidence || 0;
    const limit = options.limit || 20;

    const results = [];
    for (const [id, concept] of this.concepts) {
      if (typeFilter && concept.type !== typeFilter) continue;
      if (concept.confidence < minConfidence) continue;

      const text = [
        concept.label || '',
        concept.type || '',
        ...(concept.elements || []),
        concept.authority_text || ''
      ].join(' ').toLowerCase();

      if (text.includes(q)) {
        concept.accessCount += 1;
        concept.lastAccessed = Date.now();
        results.push({ ...concept, relevance: this._scoreRelevance(concept, q) });
      }
    }

    return results
      .sort((a, b) => b.relevance - a.relevance)
      .slice(0, limit);
  }

  _scoreRelevance(concept, query) {
    let score = concept.confidence * 0.3;
    if (concept.label && concept.label.toLowerCase().includes(query)) score += 0.4;
    if (concept.type && concept.type.toLowerCase().includes(query)) score += 0.1;
    score += Math.min(concept.accessCount * 0.02, 0.2);
    return score;
  }

  /**
   * Abstract: extract pattern from multiple episodic memories.
   * E.g., 7 episodes of "Emily files false allegation" → abstract pattern.
   */
  abstract(label, sourceEpisodes, patternDescription) {
    const id = `abs_${label.replace(/\s+/g, '_').toLowerCase()}`;
    this.abstractions.set(id, {
      id,
      label,
      pattern: patternDescription,
      sourceEpisodes: sourceEpisodes.map(e => e.id || e.event_id),
      instanceCount: sourceEpisodes.length,
      createdAt: Date.now(),
      confidence: Math.min(0.3 + sourceEpisodes.length * 0.1, 0.95)
    });

    // Store as semantic concept too
    this.store(id, {
      label,
      type: 'ABSTRACTED_PATTERN',
      elements: [patternDescription],
      lane: sourceEpisodes[0]?.lane || null,
      confidence: Math.min(0.3 + sourceEpisodes.length * 0.1, 0.95)
    });

    return this.abstractions.get(id);
  }

  /**
   * Schema formation: identify recurring patterns across cases.
   * Schemas are higher-order abstractions over multiple abstractions.
   */
  formSchema(schemaName, abstractionIds, description) {
    const instances = abstractionIds
      .map(id => this.abstractions.get(id))
      .filter(Boolean);

    this.schemas.set(schemaName, {
      name: schemaName,
      description,
      instances: instances.map(i => i.id),
      instanceCount: instances.length,
      confidence: instances.length >= 3 ? 0.8 : 0.5,
      formedAt: Date.now()
    });

    return this.schemas.get(schemaName);
  }

  /** Get related concepts up to N hops away — knowledge graph traversal. */
  getRelated(conceptId, maxHops = 2) {
    const visited = new Set();
    const results = [];
    const queue = [{ id: conceptId, depth: 0 }];

    while (queue.length > 0) {
      const { id, depth } = queue.shift();
      if (visited.has(id) || depth > maxHops) continue;
      visited.add(id);

      const concept = this.concepts.get(id);
      if (concept && depth > 0) results.push({ ...concept, hops: depth });

      const rels = this.relations.get(id) || [];
      for (const rel of rels) {
        queue.push({ id: rel.target, depth: depth + 1 });
      }
    }
    return results;
  }

  stats() {
    return {
      totalConcepts: this.concepts.size,
      totalRelations: [...this.relations.values()].reduce((s, r) => s + r.length, 0),
      totalAbstractions: this.abstractions.size,
      totalSchemas: this.schemas.size,
      byType: this._countByType()
    };
  }

  _countByType() {
    const counts = {};
    for (const concept of this.concepts.values()) {
      counts[concept.type || 'UNKNOWN'] = (counts[concept.type || 'UNKNOWN'] || 0) + 1;
    }
    return counts;
  }
}

3.2 SemanticMemoryDB (Python — authority_chains_v2 + michigan_rules_extracted bridge)

"""Semantic memory bridge — legal knowledge from authority chains and rules."""
import sqlite3
import json
import re
from pathlib import Path

DB_PATH = Path(__file__).resolve().parents[3] / "litigation_context.db"

def _sanitize_fts5(query: str) -> str:
    return re.sub(r'[^\w\s*"]', ' ', query).strip()

class SemanticMemoryDB:
    """Query authority_chains_v2 and michigan_rules_extracted for semantic knowledge."""

    def __init__(self, db_path=None):
        self.db_path = db_path or str(DB_PATH)
        self.conn = sqlite3.connect(self.db_path)
        self.conn.execute("PRAGMA busy_timeout = 60000")
        self.conn.execute("PRAGMA journal_mode = WAL")
        self.conn.execute("PRAGMA cache_size = -32000")
        self.conn.row_factory = sqlite3.Row

    def retrieve_authority_chain(self, citation: str, limit: int = 30) -> list[dict]:
        """Find authority chain entries for a citation (MCR/MCL/case law)."""
        cols = {r[1] for r in self.conn.execute(
            "PRAGMA table_info(authority_chains_v2)"
        ).fetchall()}

        select_cols = []
        for c in ['primary_citation', 'supporting_citation', 'relationship',
                   'source_document', 'source_type', 'lane', 'paragraph_context']:
            if c in cols:
                select_cols.append(c)
        if not select_cols:
            return []

        sql = f"SELECT {', '.join(select_cols)} FROM authority_chains_v2 WHERE "
        if 'primary_citation' in cols:
            sql += "primary_citation LIKE ? OR supporting_citation LIKE ?"
        else:
            sql += "1=0"
        sql += f" LIMIT {limit}"

        rows = self.conn.execute(sql, (f"%{citation}%", f"%{citation}%")).fetchall()
        return [dict(r) for r in rows]

    def retrieve_rule(self, rule_ref: str, limit: int = 10) -> list[dict]:
        """Look up Michigan court rules by citation or keyword."""
        cols = {r[1] for r in self.conn.execute(
            "PRAGMA table_info(michigan_rules_extracted)"
        ).fetchall()}

        safe_cols = [c for c in ['rule_citation', 'rule_text', 'category',
                                  'chapter', 'source_file'] if c in cols]
        if not safe_cols:
            return []

        # Try exact citation match first
        if 'rule_citation' in cols:
            rows = self.conn.execute(
                f"SELECT {', '.join(safe_cols)} FROM michigan_rules_extracted "
                f"WHERE rule_citation LIKE ? LIMIT ?",
                (f"%{rule_ref}%", limit)
            ).fetchall()
            if rows:
                return [dict(r) for r in rows]

        # Fallback: search rule_text
        if 'rule_text' in cols:
            rows = self.conn.execute(
                f"SELECT {', '.join(safe_cols)} FROM michigan_rules_extracted "
                f"WHERE rule_text LIKE ? LIMIT ?",
                (f"%{rule_ref}%", limit)
            ).fetchall()
            return [dict(r) for r in rows]

        return []

    def find_concept_network(self, concept: str, hops: int = 2,
                              limit: int = 50) -> list[dict]:
        """Build concept network: find authorities related to a concept
        by following citation chains up to N hops."""
        sanitized = _sanitize_fts5(concept)
        if not sanitized:
            return []

        # Hop 0: direct matches
        direct = self.retrieve_authority_chain(sanitized, limit=limit)

        if hops < 2 or not direct:
            return direct

        # Hop 1: find citations that reference the same supporting authorities
        supporting = set()
        for row in direct:
            sc = row.get('supporting_citation', '')
            if sc:
                supporting.add(sc)

        hop1_results = []
        for sc in list(supporting)[:10]:
            hop1 = self.retrieve_authority_chain(sc, limit=5)
            hop1_results.extend(hop1)

        return direct + hop1_results

    def extract_pattern(self, query: str, limit: int = 20) -> dict:
        """Extract a semantic pattern: how many authorities support a concept,
        which lanes they appear in, what types of sources cite them."""
        chain = self.retrieve_authority_chain(query, limit=limit)
        if not chain:
            return {"query": query, "found": False, "count": 0}

        lanes = {}
        source_types = {}
        for row in chain:
            l = row.get('lane', 'UNKNOWN')
            lanes[l] = lanes.get(l, 0) + 1
            st = row.get('source_type', 'UNKNOWN')
            source_types[st] = source_types.get(st, 0) + 1

        return {
            "query": query,
            "found": True,
            "count": len(chain),
            "by_lane": lanes,
            "by_source_type": source_types,
            "top_authorities": [r.get('primary_citation', '') for r in chain[:5]]
        }

    def close(self):
        self.conn.close()

---

Layer 4: A-MEM Zettelkasten — Cross-Reference Discovery

4.1 ZettelkastenMemory Class (JavaScript)

/**
 * ZettelkastenMemory — Atomic Note Memory with auto-linking and surprise detection.
 *
 * Research: A-MEM (2025) — each evidence item is an atomic note with tags, links,
 * source, confidence. Auto-linking discovers non-obvious connections. Surprise
 * detection flags evidence that contradicts existing semantic memory.
 *
 * Each note (Zettel) = { id, content, tags[], links[], source, confidence,
 *   createdAt, lane, embedding (optional) }
 */
class ZettelkastenMemory {
  constructor(options = {}) {
    this.notes = new Map();          // id → Note
    this.tagIndex = new Map();       // tag → Set<note_id>
    this.linkGraph = new Map();      // id → Set<linked_id>
    this.surprises = [];             // contradictions / anomalies
    this.similarityThreshold = options.similarityThreshold || 0.6;
    this._embeddings = new Map();    // id → Float32Array (from LanceDB bridge)
  }

  /**
   * Add a note (evidence atom) to the Zettelkasten.
   * Automatically finds similar existing notes and creates links.
   */
  addNote(note) {
    const n = {
      id: note.id || `z_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
      content: note.content,
      tags: note.tags || [],
      links: new Set(),
      source: note.source || null,
      confidence: note.confidence || 0.5,
      lane: note.lane || null,
      createdAt: Date.now(),
      accessCount: 0,
      surprise: false
    };

    this.notes.set(n.id, n);

    // Tag index
    for (const tag of n.tags) {
      const key = tag.toLowerCase();
      if (!this.tagIndex.has(key)) this.tagIndex.set(key, new Set());
      this.tagIndex.get(key).add(n.id);
    }

    // Auto-link to similar notes
    const autoLinks = this.autoLink(n);

    // Link graph
    this.linkGraph.set(n.id, new Set(autoLinks.map(l => l.targetId)));
    for (const link of autoLinks) {
      if (!this.linkGraph.has(link.targetId)) this.linkGraph.set(link.targetId, new Set());
      this.linkGraph.get(link.targetId).add(n.id);
    }

    return { note: n, autoLinks };
  }

  /**
   * Auto-link: find notes that share tags, actors, or content keywords.
   * If embeddings are available, uses cosine similarity. Otherwise tag overlap.
   */
  autoLink(note) {
    const links = [];
    const noteTagSet = new Set(note.tags.map(t => t.toLowerCase()));
    const noteWords = new Set(
      note.content.toLowerCase().split(/\s+/).filter(w => w.length > 4)
    );

    for (const [id, existing] of this.notes) {
      if (id === note.id) continue;

      let similarity = 0;

      // Tag overlap (Jaccard)
      const existingTags = new Set(existing.tags.map(t => t.toLowerCase()));
      const intersection = new Set([...noteTagSet].filter(t => existingTags.has(t)));
      const union = new Set([...noteTagSet, ...existingTags]);
      const jaccard = union.size > 0 ? intersection.size / union.size : 0;
      similarity += jaccard * 0.5;

      // Content keyword overlap
      const existingWords = new Set(
        existing.content.toLowerCase().split(/\s+/).filter(w => w.length > 4)
      );
      const wordIntersection = [...noteWords].filter(w => existingWords.has(w));
      const wordSim = noteWords.size > 0 ? wordIntersection.length / noteWords.size : 0;
      similarity += wordSim * 0.3;

      // Lane match bonus
      if (note.lane && note.lane === existing.lane) similarity += 0.1;

      // Embedding cosine similarity (if available)
      const emb1 = this._embeddings.get(note.id);
      const emb2 = this._embeddings.get(id);
      if (emb1 && emb2) {
        similarity = this._cosineSimilarity(emb1, emb2);
      }

      if (similarity >= this.similarityThreshold) {
        links.push({
          targetId: id,
          similarity: Math.round(similarity * 1000) / 1000,
          sharedTags: [...intersection],
          linkType: similarity > 0.8 ? 'STRONG' : 'MODERATE'
        });
      }
    }

    return links.sort((a, b) => b.similarity - a.similarity).slice(0, 10);
  }

  _cosineSimilarity(a, b) {
    let dot = 0, normA = 0, normB = 0;
    for (let i = 0; i < a.length; i++) {
      dot += a[i] * b[i];
      normA += a[i] * a[i];
      normB += b[i] * b[i];
    }
    const denom = Math.sqrt(normA) * Math.sqrt(normB);
    return denom > 0 ? dot / denom : 0;
  }

  /** Set embedding for a note (received from Python LanceDB bridge). */
  setEmbedding(noteId, embedding) {
    this._embeddings.set(noteId, embedding instanceof Float32Array ?
      embedding : new Float32Array(embedding));
  }

  /**
   * Surprise detection: flag notes that contradict existing semantic memory.
   * A "surprise" is evidence that says the opposite of what we've established.
   * Uses negation keywords + known contradiction patterns.
   */
  findSurprises(semanticMemory) {
    const negationPatterns = [
      /\bnever\b/i, /\bdid\s+not\b/i, /\bdenied?\b/i, /\bcontradicts?\b/i,
      /\bfalse\b/i, /\buntrue\b/i, /\brecanted?\b/i, /\bretracted?\b/i,
      /\bopposite\b/i, /\binconsistent\b/i
    ];

    this.surprises = [];

    for (const [id, note] of this.notes) {
      const content = note.content.toLowerCase();

      // Check each semantic concept — does this note contradict it?
      for (const [conceptId, concept] of semanticMemory.concepts) {
        const conceptText = (concept.label + ' ' + (concept.elements || []).join(' ')).toLowerCase();
        const conceptWords = new Set(conceptText.split(/\s+/).filter(w => w.length > 4));
        const noteWords = new Set(content.split(/\s+/).filter(w => w.length > 4));
        const overlap = [...conceptWords].filter(w => noteWords.has(w));

        if (overlap.length < 2) continue;

        const hasNegation = negationPatterns.some(p => p.test(note.content));
        if (hasNegation) {
          this.surprises.push({
            noteId: id,
            conceptId,
            noteContent: note.content.slice(0, 200),
            conceptLabel: concept.label,
            reason: 'NEGATION_OF_ESTABLISHED_CONCEPT',
            overlapWords: overlap,
            severity: overlap.length >= 4 ? 'HIGH' : 'MEDIUM',
            detectedAt: Date.now()
          });
          note.surprise = true;
        }
      }
    }

    return this.surprises;
  }

  /**
   * Insight generation: find non-obvious connections across lanes.
   * Notes from different lanes that share significant content = cross-lane insight.
   */
  generateInsights(minSimilarity = 0.5) {
    const insights = [];
    const notesList = [...this.notes.values()];

    for (let i = 0; i < notesList.length; i++) {
      for (let j = i + 1; j < notesList.length; j++) {
        const a = notesList[i], b = notesList[j];
        if (!a.lane || !b.lane || a.lane === b.lane) continue;

        const linkedToB = this.linkGraph.get(a.id);
        if (linkedToB && linkedToB.has(b.id)) {
          insights.push({
            noteA: { id: a.id, lane: a.lane, content: a.content.slice(0, 100) },
            noteB: { id: b.id, lane: b.lane, content: b.content.slice(0, 100) },
            insightType: 'CROSS_LANE_CONNECTION',
            lanes: [a.lane, b.lane].sort(),
            sharedTags: a.tags.filter(t => b.tags.includes(t))
          });
        }
      }
    }

    return insights.slice(0, 50);
  }

  stats() {
    const notes = [...this.notes.values()];
    return {
      totalNotes: notes.length,
      totalTags: this.tagIndex.size,
      totalLinks: [...this.linkGraph.values()].reduce((s, l) => s + l.size, 0),
      surprises: this.surprises.length,
      avgLinksPerNote: notes.length ?
        [...this.linkGraph.values()].reduce((s, l) => s + l.size, 0) / notes.length : 0,
      hasEmbeddings: this._embeddings.size
    };
  }
}

---

Layer 5: Mem0 Consolidation / Decay / Retrieval Orchestrator

5.1 MemoryOrchestrator Class (JavaScript)

/**
 * MemoryOrchestrator — Mem0-inspired consolidation, decay, and retrieval.
 *
 * Research: Mem0 (2024) — self-improving memory for LLM agents.
 * - Consolidation: periodically merge similar memories, strengthen important ones.
 * - Decay: memories not accessed/reinforced gradually lose salience.
 * - Retrieval: multi-stage — working memory → episodic → semantic.
 * - Importance: evidence used in filings gets permanent boost.
 * - Emotional tagging: high-harm events (jail, separation) elevated retention.
 */
class MemoryOrchestrator {
  constructor(workingMemory, episodicMemory, semanticMemory, zettelkasten) {
    this.working = workingMemory;
    this.episodic = episodicMemory;
    this.semantic = semanticMemory;
    this.zettel = zettelkasten;
    this._consolidationLog = [];
    this._importanceBoosts = new Map(); // id → boost multiplier
  }

  /**
   * Multi-stage retrieval: working → episodic → semantic.
   * Returns first layer that has relevant results, with source attribution.
   */
  retrieve(query, options = {}) {
    const maxResults = options.maxResults || 20;
    const results = { working: [], episodic: [], semantic: [], zettel: [], source: null };

    // Stage 1: Working memory (fastest, <5ms)
    const workingItems = this.working.getActive();
    results.working = workingItems.filter(item => {
      const text = JSON.stringify(item.payload || {}).toLowerCase();
      return text.includes(query.toLowerCase());
    }).slice(0, maxResults);

    if (results.working.length >= maxResults) {
      results.source = 'working';
      return results;
    }

    // Stage 2: Episodic memory (<50ms)
    if (options.dateRange) {
      results.episodic = this.episodic.retrieveByDateRange(
        options.dateRange[0], options.dateRange[1]
      );
    } else if (options.actor) {
      results.episodic = this.episodic.retrieveByActor(options.actor);
    } else {
      // Search all episodes by keyword
      const q = query.toLowerCase();
      results.episodic = [...this.episodic.episodes.values()]
        .filter(ep => {
          const text = [ep.action, ...(ep.actors || []), ep.location || '']
            .join(' ').toLowerCase();
          return text.includes(q);
        })
        .sort((a, b) => (b.consolidationScore || 0) - (a.consolidationScore || 0))
        .slice(0, maxResults);
    }

    if (results.episodic.length >= maxResults) {
      results.source = 'episodic';
      return results;
    }

    // Stage 3: Semantic memory (<30ms)
    results.semantic = this.semantic.retrieve(query, { limit: maxResults });

    if (results.semantic.length > 0) {
      results.source = 'semantic';
    }

    // Stage 4: Zettelkasten cross-refs (if still under limit)
    const zettelResults = [];
    for (const [id, note] of this.zettel.notes) {
      if (note.content.toLowerCase().includes(query.toLowerCase())) {
        zettelResults.push(note);
      }
    }
    results.zettel = zettelResults.slice(0, maxResults);

    if (!results.source && results.zettel.length > 0) {
      results.source = 'zettel';
    }

    results.source = results.source || 'none';
    return results;
  }

  /**
   * Consolidation: merge similar episodic memories, promote patterns to semantic.
   * Should run at session end or on explicit save — NOT during active interaction.
   */
  consolidate() {
    const startTime = Date.now();
    const log = { merged: 0, promoted: 0, strengthened: 0, timestamp: startTime };

    // 1. Promote high-value working memory items to episodic
    const promotable = this.working.exportForPromotion(3, 0.3);
    const promoted = this.episodic.consolidate(promotable);
    log.promoted = promoted.length;

    // 2. Strengthen repeatedly-accessed episodic memories
    for (const [id, ep] of this.episodic.episodes) {
      if (ep.accessCount >= 5) {
        ep.consolidationScore = Math.min(
          (ep.consolidationScore || 0) + ep.accessCount * 0.1, 10.0
        );
        log.strengthened++;
      }
    }

    // 3. Detect patterns in episodic memory → abstract to semantic
    const actorPatterns = this._detectActorPatterns();
    for (const pattern of actorPatterns) {
      this.semantic.abstract(
        pattern.label,
        pattern.episodes,
        pattern.description
      );
    }

    // 4. Add zettelkasten notes for promoted items
    for (const ep of promoted) {
      this.zettel.addNote({
        id: `zettel_${ep.id}`,
        content: ep.action || ep.event_description || '',
        tags: [...(ep.actors || []), ep.lane || ''].filter(Boolean),
        source: ep.source_table || 'episodic_promotion',
        confidence: Math.min((ep.consolidationScore || 0) / 10, 1.0),
        lane: ep.lane || null
      });
    }

    log.elapsed = Date.now() - startTime;
    this._consolidationLog.push(log);
    return log;
  }

  _detectActorPatterns() {
    const patterns = [];
    for (const [actor, episodeIds] of this.episodic.actorIndex) {
      if (episodeIds.size < 3) continue;

      const episodes = [...episodeIds]
        .map(id => this.episodic.episodes.get(id))
        .filter(Boolean);

      // Group by action keywords
      const actionGroups = {};
      for (const ep of episodes) {
        const action = (ep.action || '').toLowerCase();
        const key = action.split(/\s+/).slice(0, 3).join('_') || 'unknown';
        if (!actionGroups[key]) actionGroups[key] = [];
        actionGroups[key].push(ep);
      }

      for (const [actionKey, group] of Object.entries(actionGroups)) {
        if (group.length >= 3) {
          patterns.push({
            label: `${actor}_${actionKey}_pattern`,
            description: `${actor} performed "${actionKey}" ${group.length} times`,
            episodes: group,
            actor,
            count: group.length
          });
        }
      }
    }
    return patterns;
  }

  /**
   * Global decay: reduce salience of un-accessed memories across all layers.
   * Working memory decays fastest, semantic slowest.
   */
  decay() {
    // Working memory: fast decay (handled internally)
    const evicted = this.working.decay();

    // Episodic: slow decay — reduce consolidation score for un-accessed episodes
    const now = Date.now();
    const dayMs = 86400000;
    for (const [id, ep] of this.episodic.episodes) {
      const daysSinceAccess = (now - (ep.lastAccessed || ep.recordedAt || now)) / dayMs;
      if (daysSinceAccess > 7 && (ep.consolidationScore || 0) > 0.1) {
        // Emotional tagging: high-harm events resist decay
        const decayRate = (ep.emotional_valence === 'HIGH') ? 0.005 : 0.02;
        ep.consolidationScore = Math.max(
          (ep.consolidationScore || 0) - decayRate * daysSinceAccess,
          0.01
        );
      }
    }

    // Semantic: very slow decay (knowledge persists)
    // Only decay low-confidence concepts not accessed in 30+ days
    for (const [id, concept] of this.semantic.concepts) {
      const daysSinceAccess = (now - (concept.lastAccessed || concept.createdAt)) / dayMs;
      if (daysSinceAccess > 30 && concept.confidence < 0.3) {
        concept.confidence = Math.max(concept.confidence - 0.01, 0.01);
      }
    }

    return { workingEvicted: evicted.length };
  }

  /**
   * Importance boost: evidence used in court filings gets permanent elevation.
   * Called when evidence is cited in a filed document.
   */
  boost(itemId, reason = 'FILING_CITATION') {
    const multiplier = reason === 'FILING_CITATION' ? 2.0 :
                       reason === 'IMPEACHMENT_USE' ? 1.5 :
                       reason === 'JUDICIAL_EXHIBIT' ? 1.8 : 1.2;

    this._importanceBoosts.set(itemId, multiplier);

    // Boost in working memory
    const wmItem = this.working.items.get(itemId);
    if (wmItem) {
      wmItem.importance = Math.min(wmItem.importance * multiplier, 1.0);
      wmItem.salience = wmItem.importance;
    }

    // Boost in episodic memory
    const epItem = this.episodic.episodes.get(itemId);
    if (epItem) {
      epItem.consolidationScore = (epItem.consolidationScore || 0) * multiplier;
      epItem.emotional_valence = 'HIGH';
    }

    // Boost in zettelkasten
    const zNote = this.zettel.notes.get(itemId);
    if (zNote) {
      zNote.confidence = Math.min(zNote.confidence * multiplier, 1.0);
    }

    return { itemId, multiplier, reason };
  }

  /** Full memory system stats. */
  stats() {
    return {
      working: this.working.stats(),
      episodic: this.episodic.stats(),
      semantic: this.semantic.stats(),
      zettelkasten: this.zettel.stats(),
      consolidations: this._consolidationLog.length,
      lastConsolidation: this._consolidationLog[this._consolidationLog.length - 1] || null,
      importanceBoosts: this._importanceBoosts.size
    };
  }
}

---

Layer 6: Memory Visualization Bridge

6.1 MemoryVisualization Class (JavaScript — D3.js integration)

/**
 * MemoryVisualization — D3.js bridge for rendering memory state on the force graph.
 *
 * - Heat map: color nodes by memory layer (working=red, episodic=blue, semantic=green)
 * - Temporal timeline: scrubber showing memory state at any point
 * - Strength indicator: node opacity = memory salience
 * - Forgetting curve: overlay showing which evidence is fading
 * - Memory search: natural language query across all three layers
 */
class MemoryVisualization {
  constructor(orchestrator, svg, simulation) {
    this.orchestrator = orchestrator;
    this.svg = svg;
    this.simulation = simulation;
    this._overlayGroup = null;
    this._heatMapActive = false;
  }

  /** Initialize the memory overlay group on the SVG. */
  init() {
    this._overlayGroup = this.svg.append('g')
      .attr('class', 'memory-overlay')
      .style('pointer-events', 'none');
    return this;
  }

  /**
   * Render memory heat map: color-code every node by its memory layer.
   * Working (red) > Episodic (blue) > Semantic (green) > None (gray).
   * Opacity = salience/confidence.
   */
  renderHeatMap(nodeSelection) {
    this._heatMapActive = true;
    const working = this.orchestrator.working;
    const episodic = this.orchestrator.episodic;
    const semantic = this.orchestrator.semantic;

    nodeSelection
      .transition().duration(500)
      .attr('fill', d => {
        if (working.items.has(d.id)) return '#FF4444';
        if (episodic.episodes.has(d.id)) return '#4488FF';
        if (semantic.concepts.has(d.id)) return '#44CC44';
        return '#666666';
      })
      .attr('opacity', d => {
        const wm = working.items.get(d.id);
        if (wm) return 0.4 + 0.6 * wm.decayedSalience;
        const ep = episodic.episodes.get(d.id);
        if (ep) return 0.3 + 0.7 * Math.min((ep.consolidationScore || 0) / 5, 1);
        const sm = semantic.concepts.get(d.id);
        if (sm) return 0.3 + 0.7 * sm.confidence;
        return 0.15;
      });

    // Legend
    this._renderLegend();
  }

  _renderLegend() {
    const legend = this._overlayGroup.selectAll('.memory-legend').data([1]);
    const g = legend.enter().append('g').attr('class', 'memory-legend')
      .attr('transform', 'translate(20, 20)');

    const items = [
      { color: '#FF4444', label: 'Working Memory' },
      { color: '#4488FF', label: 'Episodic Memory' },
      { color: '#44CC44', label: 'Semantic Memory' },
      { color: '#666666', label: 'Not in Memory' }
    ];

    items.forEach((item, i) => {
      g.append('rect').attr('x', 0).attr('y', i * 22).attr('width', 14)
        .attr('height', 14).attr('fill', item.color).attr('rx', 2);
      g.append('text').attr('x', 20).attr('y', i * 22 + 11)
        .text(item.label).attr('fill', '#ccc').attr('font-size', '11px');
    });
  }

  /** Disable heat map, restore original colors. */
  clearHeatMap(nodeSelection, originalColorFn) {
    this._heatMapActive = false;
    nodeSelection.transition().duration(300)
      .attr('fill', originalColorFn)
      .attr('opacity', 1);
    this._overlayGroup.selectAll('.memory-legend').remove();
  }

  /**
   * Render forgetting curve overlay: rings around nodes that are fading.
   * Ring thickness ∝ remaining time before full decay.
   */
  renderForgettingCurve(nodeSelection) {
    const working = this.orchestrator.working;
    const now = Date.now();

    nodeSelection.each(function(d) {
      const item = working.items.get(d.id);
      if (!item) return;

      const elapsed = now - item.lastAccessed;
      const halfLife = working.decayHalfLife * item.stability;
      const retention = Math.exp(-elapsed / halfLife);

      // Only show for items actively decaying (retention < 0.8)
      if (retention >= 0.8) return;

      const sel = d3.select(this);
      const r = parseFloat(sel.attr('r') || 6);

      // Pulsing ring — faster pulse = faster decay
      const pulseSpeed = 2000 * retention; // slower pulse = more urgent
      sel.attr('stroke', `rgba(255, ${Math.floor(retention * 200)}, 0, ${1 - retention})`)
         .attr('stroke-width', 2 + (1 - retention) * 3)
         .attr('stroke-dasharray', `${r * retention * 2} ${r * (1 - retention) * 2}`);
    });
  }

  /**
   * Memory search: query across all layers, highlight matching nodes.
   * Returns results grouped by layer.
   */
  searchAllLayers(query, nodeSelection) {
    const results = this.orchestrator.retrieve(query);

    // Collect all matching node IDs
    const matchIds = new Set();
    for (const item of results.working) matchIds.add(item.id);
    for (const ep of results.episodic) matchIds.add(ep.id || ep.event_id);
    for (const sm of results.semantic) matchIds.add(sm.id);
    for (const z of results.zettel) matchIds.add(z.id);

    // Highlight matches, dim everything else
    nodeSelection
      .transition().duration(300)
      .attr('opacity', d => matchIds.has(d.id) ? 1.0 : 0.08)
      .attr('r', d => matchIds.has(d.id) ?
        (parseFloat(d3.select(`#node-${d.id}`).attr('r') || 6) * 1.5) : null);

    return {
      query,
      totalMatches: matchIds.size,
      byLayer: {
        working: results.working.length,
        episodic: results.episodic.length,
        semantic: results.semantic.length,
        zettel: results.zettel.length
      },
      primarySource: results.source
    };
  }

  /**
   * Memory status gauge for HUD overlay.
   * Returns data for rendering memory utilization bars.
   */
  getHUDData() {
    const stats = this.orchestrator.stats();
    return {
      workingUtil: stats.working.utilization,
      workingAvgSalience: stats.working.avgSalience,
      episodicTotal: stats.episodic.totalEpisodes,
      episodicChains: stats.episodic.causalChains,
      semanticConcepts: stats.semantic.totalConcepts,
      semanticRelations: stats.semantic.totalRelations,
      zettelNotes: stats.zettelkasten.totalNotes,
      zettelLinks: stats.zettelkasten.totalLinks,
      surprises: stats.zettelkasten.surprises,
      lastConsolidation: stats.lastConsolidation
    };
  }

  /**
   * Render compact HUD bar showing memory system health.
   * Positioned at bottom-left of SVG viewport.
   */
  renderHUD(width, height) {
    const data = this.getHUDData();
    const g = this._overlayGroup.selectAll('.memory-hud').data([1]);
    const hud = g.enter().append('g').attr('class', 'memory-hud')
      .attr('transform', `translate(20, ${height - 80})`);

    // Working memory bar
    hud.append('rect').attr('x', 0).attr('y', 0).attr('width', 120).attr('height', 14)
      .attr('fill', '#222').attr('stroke', '#444').attr('rx', 3);
    hud.append('rect').attr('x', 1).attr('y', 1)
      .attr('width', Math.max(1, 118 * data.workingUtil)).attr('height', 12)
      .attr('fill', '#FF4444').attr('rx', 2);
    hud.append('text').attr('x', 125).attr('y', 11)
      .text(`WM ${Math.round(data.workingUtil * 100)}%`)
      .attr('fill', '#aaa').attr('font-size', '10px');

    // Episodic count
    hud.append('text').attr('x', 0).attr('y', 30)
      .text(`EP: ${data.episodicTotal} events, ${data.episodicChains} chains`)
      .attr('fill', '#4488FF').attr('font-size', '10px');

    // Semantic count
    hud.append('text').attr('x', 0).attr('y', 44)
      .text(`SM: ${data.semanticConcepts} concepts, ${data.semanticRelations} relations`)
      .attr('fill', '#44CC44').attr('font-size', '10px');

    // Surprise indicator
    if (data.surprises > 0) {
      hud.append('text').attr('x', 0).attr('y', 58)
        .text(`⚠ ${data.surprises} SURPRISES DETECTED`)
        .attr('fill', '#FFaa00').attr('font-size', '10px').attr('font-weight', 'bold');
    }
  }
}

---

Anti-Patterns (24 Rules)

These rules are INVIOLABLE. Every violation risks data loss, PII exposure, or corrupted litigation intelligence.

| # | Anti-Pattern | Why | Consequence | |---|-------------|-----|-------------| | 1 | NEVER delete memories — decay to minSalience but retain | Every evidence atom may be needed years later in appellate proceedings | Lost impeachment ammunition | | 2 | NEVER store child's full name in working memory localStorage | MCR 8.119(H) — PII violation if browser storage is forensically examined | Court sanction, ethics violation | | 3 | NEVER let episodic memory exceed 100K items without consolidation | Memory bloat degrades retrieval from O(log n) to O(n) | UI freeze on temporal queries | | 4 | NEVER bypass semantic memory when it has a cached answer | Redundant DB queries waste the <50ms retrieval budget | Performance degradation | | 5 | NEVER consolidate memories during active user interaction | Consolidation is O(n²) for pattern detection — blocks UI thread | >16ms frame drop, jank | | 6 | NEVER let decay function reach zero — minimum salience = 0.01 | Zero-salience items vanish from all retrieval paths permanently | Unrecoverable evidence loss | | 7 | NEVER promote working memory to episodic without source verification | Unverified promotions inject hallucinated events into the timeline | Corrupted causal chains | | 8 | NEVER auto-link notes with similarity < 0.4 | Low-similarity links create noise that drowns real connections | False cross-references | | 9 | NEVER run surprise detection on > 5000 notes without batching | O(n × m) complexity for n notes × m concepts — CPU bound | Browser tab crash | | 10 | NEVER store embeddings in localStorage (384-dim × 4 bytes × 75K = 114 MB) | Exceeds 10 MB localStorage quota on all browsers | Silent data truncation | | 11 | NEVER modify episodic memory timestamps after recording | Temporal index integrity depends on immutable timestamps | Binary search returns wrong results | | 12 | NEVER merge causal chains from different lanes without explicit flag | Cross-lane contamination violates case separation (Rule 7 — CRIMINAL) | Legal malpractice risk | | 13 | NEVER run global decay more than once per minute | Excessive decay sweeps create write contention on SQLite WAL | SQLITE_BUSY cascade | | 14 | NEVER consolidate without first running decay() | Consolidation on stale salience data produces wrong importance rankings | Weak evidence promoted over strong | | 15 | NEVER skip the multi-stage retrieval order (W → E → S) | Working memory is the fastest path — skipping it wastes the 5ms budget | Unnecessary DB round-trips | | 16 | NEVER store raw SQL in memory items | SQL injection risk if memory items are used in template interpolation | Security vulnerability | | 17 | NEVER let zettelkasten link graph become fully connected | Complete graphs destroy the information value of links | Every note "related" to every other | | 18 | NEVER persist working memory to disk more than once per 30 seconds | Disk I/O on every access defeats the purpose of in-memory cache | Performance regression to disk-speed | | 19 | NEVER use JSON.parse on untrusted memory snapshots without try/catch | Corrupt sessionStorage data crashes the entire memory system | Unrecoverable initialization failure | | 20 | NEVER assume embeddings are available — always have keyword fallback | LanceDB may be unavailable; sentence-transformers may not be loaded | Silent empty results | | 21 | NEVER boost importance above 1.0 — clamp all multiplied values | Unbounded importance breaks normalization in visualization opacity | Visual rendering artifacts | | 22 | NEVER create circular causal links (A caused B caused A) | Infinite loops in findCausalChain() BFS traversal | Stack overflow, frozen UI | | 23 | NEVER expose memory orchestrator stats in court filings | AI system details are prohibited in court-facing output (Rule 3) | Filing rejected, credibility destroyed | | 24 | NEVER share memory state across browser tabs without mutex | Concurrent sessionStorage writes cause last-write-wins data loss | Memory corruption |

---

Performance Budgets

| Operation | Budget | Technique | Measured Against | |-----------|--------|-----------|-----------------| | Working memory access() | < 5 ms | In-memory Map with LRU eviction | 50 items, AMD Ryzen 3 3200G | | Working memory decay() | < 10 ms | Single Map.forEach with math | 50 items, exponential calc | | Episodic retrieveByDateRange() | < 50 ms | Binary search on sorted temporal index | 16.8K episodes | | Episodic retrieveByActor() | < 30 ms | Pre-built actor→episode Set index | 200 unique actors | | Semantic retrieve() | < 30 ms | Linear scan with early termination | 10K concepts | | Semantic getRelated() (2 hops) | < 50 ms | BFS with visited Set | 10K nodes, avg degree 3 | | Zettelkasten autoLink() | < 200 ms | Tag Jaccard + word overlap (no embeddings) | 5K notes | | Zettelkasten autoLink() (embeddings) | < 100 ms | Pre-computed 384-dim cosine via Float32Array | 5K notes, LanceDB | | Zettelkasten findSurprises() | < 500 ms | Batched: 1000 notes × 500 concepts per batch | Full corpus | | Consolidation cycle | < 2 s | Batch merge with dedup, pattern detect O(actors × groups) | 16.8K episodes | | Global decay sweep | < 100 ms | Single UPDATE ... WHERE on SQLite | 100K rows | | Memory heat map render | < 16 ms | D3 transition with pre-computed membership Sets | 2500 nodes | | Memory search (all layers) | < 80 ms | Sequential: 5ms + 50ms + 30ms worst case | Full corpus | | HUD gauge update | < 5 ms | Pre-computed stats object, no DOM query | 4 gauge bars | | SessionStorage persist | < 15 ms | JSON.stringify of 50-item Map | 50 items avg 200 bytes | | Causal chain BFS | < 20 ms | Visited Set, max depth 10 | 1K causal links |

---

Integration Matrix

| This Skill | Integrates With | Direction | Data Flow | |-----------|----------------|-----------|-----------| | Working Memory | MBP-INTERFACE-CONTROLS | ← receives | Node clicks/searches populate working memory | | Working Memory | MBP-INTERFACE-HUD | → sends | Memory utilization gauge data | | Episodic Memory | MBP-DATAWEAVE | ← receives | timeline_events → episodic memory bootstrap | | Episodic Memory | MBP-INTERFACE-TIMELINE | ↔ bidirectional | Timeline scrubber queries episodic; episodes feed timeline | | Semantic Memory | MBP-COMBAT-AUTHORITY | ← receives | Authority chain data → semantic concept network | | Semantic Memory | MBP-COMBAT-EVIDENCE | → sends | Pattern abstractions feed evidence density analysis | | Zettelkasten | MBP-EMERGENCE-CONVERGENCE | ↔ bidirectional | Cross-refs feed convergence; convergence gaps → zettel notes | | Zettelkasten | MBP-COMBAT-IMPEACHMENT | → sends | Surprise detection → impeachment contradiction candidates | | Orchestrator | MBP-EMERGENCE-SELFEVOLVE | → sends | Consolidation logs → self-evolution learning data | | Visualization | MBP-FORGE-RENDERER | ← receives | SVG/Canvas context for overlay rendering | | Visualization | MBP-FORGE-EFFECTS | → sends | Decay ring animations → effects pipeline | | All Layers | MBP-INTEGRATION-BRAINS | ↔ bidirectional | Brain DBs feed memories; memory stats feed brain health | | All Layers | APEX-COGNITION | → sends | Cross-session memory persistence via cognitive bridge |

Database Table Mapping

| Memory Layer | Primary Tables | Access Pattern | |-------------|---------------|----------------| | Working Memory | working_memory_snapshots (created by this skill) | Write: snapshots; Read: session restore | | Episodic Memory | timeline_events (16.8K), evidence_quotes (175K) | Read: FTS5 MATCH + date range; Write: consolidation | | Semantic Memory | authority_chains_v2 (167K), michigan_rules_extracted (19.8K), master_citations (72K) | Read: LIKE + chain traversal | | Zettelkasten | evidence_quotes, contradiction_map (2.5K) | Read: FTS5; Write: surprise flags | | Orchestrator | All of above + impeachment_matrix (5.1K), judicial_violations (1.9K) | Read: multi-table fusion |

LanceDB Integration

# Auto-linking with pre-computed embeddings from LanceDB (75K vectors, 384-dim)
import lancedb

def get_similar_notes(query_text: str, top_k: int = 10):
    """Find semantically similar evidence for zettelkasten auto-linking."""
    db = lancedb.connect("00_SYSTEM/engines/semantic/lancedb_store")
    try:
        table = db.open_table("evidence_vectors")
    except Exception:
        return []  # LanceDB unavailable — keyword fallback

    # sentence-transformers embedding happens in the search call
    results = table.search(query_text).limit(top_k).to_list()
    return [
        {"id": r.get("id", ""), "text": r.get("text", ""),
         "score": r.get("_distance", 0), "source": r.get("source", "")}
        for r in results
    ]

DuckDB Consolidation Analytics

# DuckDB analytical queries for memory consolidation (10-100× faster than SQLite)
import duckdb

def analyze_memory_patterns(db_path: str = "litigation_context.db"):
    """Use DuckDB for fast analytical queries during consolidation."""
    conn = duckdb.connect()
    conn.execute(f"ATTACH '{db_path}' AS lit (TYPE sqlite, READ_ONLY)")

    # Find actors with most timeline events (pattern candidates)
    actor_patterns = conn.execute("""
        SELECT actor, COUNT(*) as event_count,
               MIN(event_date) as first_event,
               MAX(event_date) as last_event,
               COUNT(DISTINCT lane) as lane_count
        FROM lit.timeline_events
        WHERE actor IS NOT NULL AND actor != ''
        GROUP BY actor
        HAVING COUNT(*) >= 5
        ORDER BY event_count DESC
        LIMIT 50
    """).fetchall()

    # Find evidence clusters by category + lane
    evidence_clusters = conn.execute("""
        SELECT category, lane, COUNT(*) as quote_count,
               AVG(LENGTH(quote_text)) as avg_length
        FROM lit.evidence_quotes
        WHERE category IS NOT NULL
        GROUP BY category, lane
        HAVING COUNT(*) >= 10
        ORDER BY quote_count DESC
        LIMIT 30
    """).fetchall()

    conn.close()
    return {
        "actor_patterns": [
            {"actor": r[0], "events": r[1], "first": r[2],
             "last": r[3], "lanes": r[4]}
            for r in actor_patterns
        ],
        "evidence_clusters": [
            {"category": r[0], "lane": r[1], "count": r[2],
             "avg_length": round(r[3], 1) if r[3] else 0}
            for r in evidence_clusters
        ]
    }

---

Research Citations

| Model | Authors/Year | Key Contribution | Applied Here | |-------|-------------|-----------------|-------------| | Multi-Store Model | Atkinson & Shiffrin, 1968 | Sensory → Short-term → Long-term memory stores | Three-layer architecture (Working → Episodic → Semantic) | | Episodic vs Semantic | Tulving, 1972 | Distinct memory systems for events vs knowledge | Separate episodic (timeline) and semantic (authority) layers | | Working Memory Model | Baddeley, 2000 | Central executive + phonological loop + visuospatial sketchpad | Attention allocator + capacity-limited buffer | | Forgetting Curve | Ebbinghaus, 1885 | R = e^(-t/S) retention decay over time | Exponential decay with stability multiplier | | Spacing Effect | Cepeda et al., 2006 | Distributed practice improves retention | Stability increases with spaced access intervals | | Cognitive Load Theory | Sweller, 1988 | Working memory has limited capacity (~7±2 items) | Configurable capacity limit (default 50) | | A-MEM | Zhang et al., 2025 | Agentic Memory with Zettelkasten for LLM agents | Atomic notes + auto-linking + cross-reference discovery | | Mem0 | Chhablani et al., 2024 | Self-improving memory layer for AI agents | Consolidation, decay, multi-stage retrieval | | Knowledge Graphs | Ehrlinger & Wöß, 2016 | Graph-based knowledge representation | Semantic concept network with typed relations | | Levels of Processing | Craik & Lockhart, 1972 | Deeper processing → stronger memory traces | Importance boost for filing-cited evidence |

---

Activation Checklist

When this skill activates, ensure:

□ WorkingMemory initialized with capacity=50, decayHalfLife=300000
□ EpisodicMemory bootstrapped from timeline_events (FTS5 verified)
□ SemanticMemory loaded with top-500 authorities from authority_chains_v2
□ ZettelkastenMemory initialized (embeddings loaded if LanceDB available)
□ MemoryOrchestrator wired to all four sub-systems
□ MemoryVisualization bound to SVG overlay group
□ Decay loop started (30s interval)
□ HUD gauge registered with MBP-INTERFACE-HUD
□ SessionStorage restore attempted (graceful failure OK)
□ Anti-pattern guards active (PII filter, capacity limits, decay floor)