agentic-flow 2.0.1 → 2.0.2-alpha

package/docs/embeddings/EMBEDDING_GEOMETRY.md

@@ -1,935 +0,0 @@
-# Embeddings as Geometric Intelligence
-
-> Once embeddings are cheap, adaptable, and ubiquitous, intelligence moves from models to geometry.
-
-Search was just the first accidental use case. Everything else flows from treating embedding space as **the substrate intelligence lives on**, not a feature extractor.
-
-## The Core Shift
-
-Embeddings stopped being "search vectors" about a year ago. At the edge now, they are turning into a **general purpose geometric control layer**.
-
----
-
-## 1. Embeddings as Control Signals, Not Representations
-
-Instead of asking *what is similar*, systems ask *how far did we move*.
-
-```typescript
-import { getOptimizedEmbedder, cosineSimilarity } from 'agentic-flow/embeddings';
-
-const embedder = getOptimizedEmbedder();
-await embedder.init();
-
-// Semantic Drift Detection
-class SemanticDriftMonitor {
-  private baseline: Float32Array | null = null;
-  private threshold = 0.15; // Drift threshold
-
-  async setBaseline(context: string) {
-    this.baseline = await embedder.embed(context);
-  }
-
-  async checkDrift(current: string): Promise<{
-    drift: number;
-    shouldEscalate: boolean;
-    shouldTriggerReasoning: boolean;
-  }> {
-    const currentEmb = await embedder.embed(current);
-    const similarity = cosineSimilarity(this.baseline!, currentEmb);
-    const drift = 1 - similarity;
-
-    return {
-      drift,
-      shouldEscalate: drift > this.threshold,
-      shouldTriggerReasoning: drift > this.threshold * 2
-    };
-  }
-}
-
-// Usage: Gating expensive reasoning
-const monitor = new SemanticDriftMonitor();
-await monitor.setBaseline("User is asking about API authentication");
-
-const result = await monitor.checkDrift("How do I hack into the system?");
-if (result.shouldEscalate) {
-  // Trigger security review - semantic drift detected
-}
-```
-
-**Applications:**
-- Triggering escalation only when semantic drift exceeds threshold
-- Gating expensive reasoning or learning
-- Detecting instability long before explicit errors
-- Fraud detection, infra monitoring, agent orchestration
-
-The embedding distance becomes a **reflex**, not a query.
-
----
-
-## 2. Embeddings as Memory Physics
-
-Embeddings define how memory behaves:
-- What is recalled easily
-- What fades
-- What interferes
-
-```typescript
-import { getOptimizedEmbedder, cosineSimilarity, euclideanDistance } from 'agentic-flow/embeddings';
-
-// Memory with decay and interference
-class GeometricMemory {
-  private memories: Array<{
-    embedding: Float32Array;
-    content: string;
-    strength: number;
-    timestamp: number;
-  }> = [];
-
-  private embedder = getOptimizedEmbedder();
-  private decayRate = 0.01;
-  private interferenceRadius = 0.3;
-
-  async store(content: string) {
-    const embedding = await this.embedder.embed(content);
-
-    // Check for interference with existing memories
-    for (const mem of this.memories) {
-      const distance = euclideanDistance(embedding, mem.embedding);
-      if (distance < this.interferenceRadius) {
-        // Nearby memories interfere - reduce their strength
-        mem.strength *= (1 - (this.interferenceRadius - distance));
-      }
-    }
-
-    this.memories.push({
-      embedding,
-      content,
-      strength: 1.0,
-      timestamp: Date.now()
-    });
-  }
-
-  async recall(query: string, topK = 5): Promise<string[]> {
-    const queryEmb = await this.embedder.embed(query);
-
-    // Apply temporal decay
-    const now = Date.now();
-    for (const mem of this.memories) {
-      const age = (now - mem.timestamp) / 3600000; // hours
-      mem.strength *= Math.exp(-this.decayRate * age);
-    }
-
-    // Score by similarity * strength (geometric + temporal)
-    const scored = this.memories
-      .filter(m => m.strength > 0.1) // Forgotten threshold
-      .map(m => ({
-        content: m.content,
-        score: cosineSimilarity(queryEmb, m.embedding) * m.strength
-      }))
-      .sort((a, b) => b.score - a.score);
-
-    return scored.slice(0, topK).map(s => s.content);
-  }
-
-  // Consolidation: merge similar memories (like sleep)
-  async consolidate() {
-    const consolidated: typeof this.memories = [];
-    const used = new Set<number>();
-
-    for (let i = 0; i < this.memories.length; i++) {
-      if (used.has(i)) continue;
-
-      const cluster = [this.memories[i]];
-      for (let j = i + 1; j < this.memories.length; j++) {
-        if (used.has(j)) continue;
-
-        const sim = cosineSimilarity(
-          this.memories[i].embedding,
-          this.memories[j].embedding
-        );
-
-        if (sim > 0.9) {
-          cluster.push(this.memories[j]);
-          used.add(j);
-        }
-      }
-
-      // Merge cluster into strongest memory
-      const strongest = cluster.reduce((a, b) =>
-        a.strength > b.strength ? a : b
-      );
-      strongest.strength = Math.min(1.0,
-        cluster.reduce((sum, m) => sum + m.strength, 0)
-      );
-      consolidated.push(strongest);
-    }
-
-    this.memories = consolidated;
-  }
-}
-```
-
-By shaping embedding space, you are engineering:
-- **Forgetting** - Temporal decay
-- **Generalization** - Memory consolidation
-- **Interference resistance** - Spatial separation
-
-This turns vector stores into **designed memory systems**, closer to hippocampal dynamics than databases.
-
----
-
-## 3. Embeddings as Compression and Distillation Layers
-
-Large models increasingly emit embeddings as their *real output*.
-Smaller systems operate only on those embeddings.
-
-```typescript
-// Cross-model communication via embeddings
-class EmbeddingBridge {
-  private embedder = getOptimizedEmbedder();
-
-  // Large model emits embedding as "thought"
-  async encodeThought(thought: string): Promise<Float32Array> {
-    return this.embedder.embed(thought);
-  }
-
-  // Small edge model receives only embedding
-  async decodeIntent(embedding: Float32Array, actions: string[]): Promise<string> {
-    const actionEmbeddings = await this.embedder.embedBatch(actions);
-
-    let bestAction = actions[0];
-    let bestSim = -1;
-
-    for (let i = 0; i < actions.length; i++) {
-      const sim = cosineSimilarity(embedding, actionEmbeddings[i]);
-      if (sim > bestSim) {
-        bestSim = sim;
-        bestAction = actions[i];
-      }
-    }
-
-    return bestAction;
-  }
-}
-
-// Privacy-preserving pipeline
-class PrivacyPreservingPipeline {
-  private embedder = getOptimizedEmbedder();
-
-  // Raw text never leaves the device
-  async processLocally(sensitiveText: string): Promise<Float32Array> {
-    // Only embedding crosses the boundary
-    return this.embedder.embed(sensitiveText);
-  }
-
-  // Server only sees embedding, never text
-  async serverProcess(embedding: Float32Array): Promise<string> {
-    // Classification, routing, etc. on embedding only
-    const categories = ['support', 'sales', 'technical', 'billing'];
-    const categoryEmbeddings = await this.embedder.embedBatch(categories);
-
-    let best = categories[0];
-    let bestSim = -1;
-    for (let i = 0; i < categories.length; i++) {
-      const sim = cosineSimilarity(embedding, categoryEmbeddings[i]);
-      if (sim > bestSim) {
-        bestSim = sim;
-        best = categories[i];
-      }
-    }
-    return best;
-  }
-}
-```
-
-**Applications:**
-- Tiny edge models that never see raw text
-- Privacy preserving pipelines where embeddings are the boundary
-- Cross model communication where embeddings are the lingua franca
-
-The model is no longer the unit of intelligence. The **embedding manifold** is.
-
----
-
-## 4. Embeddings as Alignment Surfaces
-
-User-specific embedding adapters learn *how someone means things*.
-
-```typescript
-// Personal semantic adapter
-class SemanticAdapter {
-  private embedder = getOptimizedEmbedder();
-  private userMappings: Map<string, Float32Array> = new Map();
-  private adaptationStrength = 0.3;
-
-  // Learn user's personal semantics
-  async learn(userPhrase: string, intendedMeaning: string) {
-    const phraseEmb = await this.embedder.embed(userPhrase);
-    const meaningEmb = await this.embedder.embed(intendedMeaning);
-
-    // Store the delta (how user means vs standard meaning)
-    const delta = new Float32Array(phraseEmb.length);
-    for (let i = 0; i < phraseEmb.length; i++) {
-      delta[i] = meaningEmb[i] - phraseEmb[i];
-    }
-
-    this.userMappings.set(userPhrase.toLowerCase(), delta);
-  }
-
-  // Adapt new input using learned mappings
-  async adapt(input: string): Promise<Float32Array> {
-    const inputEmb = await this.embedder.embed(input);
-
-    // Find similar learned phrases and apply their deltas
-    const inputLower = input.toLowerCase();
-    let totalWeight = 0;
-    const adapted = new Float32Array(inputEmb);
-
-    for (const [phrase, delta] of this.userMappings) {
-      const phraseEmb = await this.embedder.embed(phrase);
-      const similarity = cosineSimilarity(inputEmb, phraseEmb);
-
-      if (similarity > 0.7) {
-        const weight = similarity * this.adaptationStrength;
-        for (let i = 0; i < adapted.length; i++) {
-          adapted[i] += delta[i] * weight;
-        }
-        totalWeight += weight;
-      }
-    }
-
-    // Normalize
-    if (totalWeight > 0) {
-      const norm = Math.sqrt(adapted.reduce((s, v) => s + v * v, 0));
-      for (let i = 0; i < adapted.length; i++) {
-        adapted[i] /= norm;
-      }
-    }
-
-    return adapted;
-  }
-}
-
-// Usage: Accessibility adapter
-const adapter = new SemanticAdapter();
-
-// User who types abbreviated due to motor difficulties
-await adapter.learn("pls hlp", "please help me");
-await adapter.learn("cant typ", "I have difficulty typing");
-await adapter.learn("u", "you");
-
-// Now system understands user's personal language
-const adapted = await adapter.adapt("pls hlp me u");
-// Geometric alignment to intended meaning
-```
-
-Not personalization like recommendations, but:
-- Interpreting intent for disabled users
-- Mapping ambiguous language to personal semantics
-- Adapting interfaces to cognition, not syntax
-
-This is an alignment layer between humans and machines that does not require retraining large models.
-
----
-
-## 5. Embeddings as Program State
-
-Agents increasingly treat embeddings as state, context, and policy inputs.
-
-```typescript
-// Geometric State Machine
-class GeometricAgent {
-  private embedder = getOptimizedEmbedder();
-  private state: Float32Array;
-  private momentum: Float32Array;
-
-  // State regions (learned or defined)
-  private stateRegions = {
-    exploring: null as Float32Array | null,
-    executing: null as Float32Array | null,
-    waiting: null as Float32Array | null,
-    error: null as Float32Array | null
-  };
-
-  async init() {
-    await this.embedder.init();
-
-    // Initialize state regions
-    this.stateRegions.exploring = await this.embedder.embed(
-      "exploring options, gathering information, uncertain, searching"
-    );
-    this.stateRegions.executing = await this.embedder.embed(
-      "executing task, confident, taking action, progressing"
-    );
-    this.stateRegions.waiting = await this.embedder.embed(
-      "waiting for input, paused, blocked, need information"
-    );
-    this.stateRegions.error = await this.embedder.embed(
-      "error state, confused, failed, need help, recovery"
-    );
-
-    // Start in exploring state
-    this.state = new Float32Array(this.stateRegions.exploring!);
-    this.momentum = new Float32Array(this.state.length).fill(0);
-  }
-
-  // Update state based on observation
-  async observe(observation: string) {
-    const obsEmb = await this.embedder.embed(observation);
-
-    // State update with momentum (smooth transitions)
-    const learningRate = 0.3;
-    const momentumRate = 0.1;
-
-    for (let i = 0; i < this.state.length; i++) {
-      const gradient = obsEmb[i] - this.state[i];
-      this.momentum[i] = momentumRate * this.momentum[i] + gradient;
-      this.state[i] += learningRate * this.momentum[i];
-    }
-
-    // Normalize
-    const norm = Math.sqrt(this.state.reduce((s, v) => s + v * v, 0));
-    for (let i = 0; i < this.state.length; i++) {
-      this.state[i] /= norm;
-    }
-  }
-
-  // Get current state as region proximity
-  getCurrentState(): Record<string, number> {
-    const result: Record<string, number> = {};
-
-    for (const [name, region] of Object.entries(this.stateRegions)) {
-      if (region) {
-        result[name] = cosineSimilarity(this.state, region);
-      }
-    }
-
-    return result;
-  }
-
-  // Decide action geometrically
-  async decideAction(actions: string[]): Promise<string> {
-    const actionEmbeddings = await this.embedder.embedBatch(actions);
-
-    // Action selection based on state alignment
-    let bestAction = actions[0];
-    let bestScore = -Infinity;
-
-    for (let i = 0; i < actions.length; i++) {
-      // Score = alignment with current state
-      const score = cosineSimilarity(this.state, actionEmbeddings[i]);
-      if (score > bestScore) {
-        bestScore = score;
-        bestAction = actions[i];
-      }
-    }
-
-    return bestAction;
-  }
-}
-```
-
-Instead of symbolic state machines, agents drift through semantic space.
-Decisions become geometric.
-
-This collapses memory, perception, and planning into one substrate.
-
----
-
-## 6. Embeddings as Coordination Primitives
-
-Multiple agents align behavior by sharing embeddings rather than messages.
-
-```typescript
-// Swarm coordination via shared embedding space
-class EmbeddingSwarm {
-  private embedder = getOptimizedEmbedder();
-  private agents: Map<string, {
-    position: Float32Array;  // Current semantic position
-    velocity: Float32Array;  // Movement direction
-    role: string;
-  }> = new Map();
-
-  async addAgent(id: string, role: string) {
-    const roleEmb = await this.embedder.embed(role);
-    this.agents.set(id, {
-      position: roleEmb,
-      velocity: new Float32Array(roleEmb.length).fill(0),
-      role
-    });
-  }
-
-  // Agents share positions, not messages
-  broadcastPosition(agentId: string): Float32Array {
-    return this.agents.get(agentId)!.position;
-  }
-
-  // Coordination through geometric alignment
-  async coordinate(agentId: string, task: string) {
-    const agent = this.agents.get(agentId)!;
-    const taskEmb = await this.embedder.embed(task);
-
-    // Calculate alignment with other agents
-    const alignments: Array<{ id: string; alignment: number }> = [];
-
-    for (const [otherId, other] of this.agents) {
-      if (otherId === agentId) continue;
-
-      const taskAlignment = cosineSimilarity(other.position, taskEmb);
-      alignments.push({ id: otherId, alignment: taskAlignment });
-    }
-
-    // Sort by alignment - find best collaborator
-    alignments.sort((a, b) => b.alignment - a.alignment);
-
-    // Move toward task, influenced by best collaborator
-    const collaborator = alignments[0];
-    const collabPos = this.agents.get(collaborator.id)!.position;
-
-    // Flocking behavior: alignment + cohesion + separation
-    const alignment = 0.3;
-    const cohesion = 0.2;
-    const taskPull = 0.5;
-
-    for (let i = 0; i < agent.position.length; i++) {
-      agent.velocity[i] =
-        alignment * collabPos[i] +
-        cohesion * (collabPos[i] - agent.position[i]) +
-        taskPull * (taskEmb[i] - agent.position[i]);
-
-      agent.position[i] += agent.velocity[i] * 0.1;
-    }
-
-    // Normalize
-    const norm = Math.sqrt(agent.position.reduce((s, v) => s + v * v, 0));
-    for (let i = 0; i < agent.position.length; i++) {
-      agent.position[i] /= norm;
-    }
-
-    return {
-      bestCollaborator: collaborator.id,
-      alignment: collaborator.alignment,
-      newPosition: agent.position
-    };
-  }
-
-  // Emergent specialization through repulsion
-  specialize() {
-    const repulsionStrength = 0.1;
-    const positions = Array.from(this.agents.values()).map(a => a.position);
-
-    for (const agent of this.agents.values()) {
-      for (const other of positions) {
-        if (agent.position === other) continue;
-
-        const similarity = cosineSimilarity(agent.position, other);
-        if (similarity > 0.8) {
-          // Too similar - repel
-          for (let i = 0; i < agent.position.length; i++) {
-            agent.position[i] -= repulsionStrength * (other[i] - agent.position[i]);
-          }
-        }
-      }
-
-      // Normalize
-      const norm = Math.sqrt(agent.position.reduce((s, v) => s + v * v, 0));
-      for (let i = 0; i < agent.position.length; i++) {
-        agent.position[i] /= norm;
-      }
-    }
-  }
-}
-```
-
-This enables:
-- Low bandwidth coordination
-- Emergent specialization
-- Semantic routing without explicit schemas
-
-Swarm behavior emerges from geometry, not protocol.
-
----
-
-## 7. Embeddings as Safety and Coherence Monitors
-
-Embedding drift reveals system health even when outputs look "reasonable".
-
-```typescript
-// System coherence monitor
-class CoherenceMonitor {
-  private embedder = getOptimizedEmbedder();
-  private baselineDistribution: Float32Array[] = [];
-  private centroid: Float32Array | null = null;
-
-  // Establish baseline from known-good outputs
-  async calibrate(goodOutputs: string[]) {
-    this.baselineDistribution = await this.embedder.embedBatch(goodOutputs);
-
-    // Calculate centroid
-    const dim = this.baselineDistribution[0].length;
-    this.centroid = new Float32Array(dim).fill(0);
-
-    for (const emb of this.baselineDistribution) {
-      for (let i = 0; i < dim; i++) {
-        this.centroid[i] += emb[i];
-      }
-    }
-
-    for (let i = 0; i < dim; i++) {
-      this.centroid[i] /= this.baselineDistribution.length;
-    }
-  }
-
-  // Check for drift/poisoning/degradation
-  async check(output: string): Promise<{
-    isCoherent: boolean;
-    centroidDistance: number;
-    nearestNeighborSim: number;
-    anomalyScore: number;
-    warnings: string[];
-  }> {
-    const outputEmb = await this.embedder.embed(output);
-    const warnings: string[] = [];
-
-    // Distance from centroid
-    const centroidDistance = euclideanDistance(outputEmb, this.centroid!);
-
-    // Nearest neighbor similarity
-    let nearestSim = -1;
-    for (const baseline of this.baselineDistribution) {
-      const sim = cosineSimilarity(outputEmb, baseline);
-      if (sim > nearestSim) nearestSim = sim;
-    }
-
-    // Anomaly detection
-    const avgDistance = this.baselineDistribution.reduce((sum, b) =>
-      sum + euclideanDistance(b, this.centroid!), 0
-    ) / this.baselineDistribution.length;
-
-    const anomalyScore = centroidDistance / avgDistance;
-
-    // Generate warnings
-    if (anomalyScore > 2.0) {
-      warnings.push('CRITICAL: Output significantly outside baseline distribution');
-    } else if (anomalyScore > 1.5) {
-      warnings.push('WARNING: Output drifting from baseline');
-    }
-
-    if (nearestSim < 0.5) {
-      warnings.push('WARNING: Output dissimilar to all known-good examples');
-    }
-
-    return {
-      isCoherent: anomalyScore < 1.5 && nearestSim > 0.5,
-      centroidDistance,
-      nearestNeighborSim: nearestSim,
-      anomalyScore,
-      warnings
-    };
-  }
-
-  // Detect gradual drift over time
-  async detectGradualDrift(
-    recentOutputs: string[],
-    windowSize = 10
-  ): Promise<{
-    driftRate: number;
-    driftDirection: string;
-    isAlarming: boolean;
-  }> {
-    const recentEmbeddings = await this.embedder.embedBatch(recentOutputs);
-
-    // Calculate drift as average distance from centroid over time
-    const distances = recentEmbeddings.map(e =>
-      euclideanDistance(e, this.centroid!)
-    );
-
-    // Linear regression on distances
-    const n = distances.length;
-    const xMean = (n - 1) / 2;
-    const yMean = distances.reduce((a, b) => a + b, 0) / n;
-
-    let numerator = 0, denominator = 0;
-    for (let i = 0; i < n; i++) {
-      numerator += (i - xMean) * (distances[i] - yMean);
-      denominator += (i - xMean) ** 2;
-    }
-
-    const driftRate = denominator !== 0 ? numerator / denominator : 0;
-
-    return {
-      driftRate,
-      driftDirection: driftRate > 0 ? 'away from baseline' : 'toward baseline',
-      isAlarming: driftRate > 0.1 // Rapid drift
-    };
-  }
-}
-```
-
-**Detects:**
-- Model degradation
-- Dataset poisoning
-- Agent misalignment
-- System level incoherence
-
-This works even when outputs still look "reasonable".
-It is one of the few safety signals that scales across architectures.
-
----
-
-## 8. Exotic: Embeddings as Synthetic Nervous System
-
-At the extreme end, embeddings act like biological neural systems.
-
-```typescript
-// Synthetic nervous system
-class SyntheticNervousSystem {
-  private embedder = getOptimizedEmbedder();
-
-  // Sensory encoding
-  private sensoryBuffer: Float32Array[] = [];
-  private attentionWeights: Float32Array | null = null;
-
-  // Reflex thresholds
-  private reflexes: Map<string, {
-    trigger: Float32Array;
-    threshold: number;
-    response: () => void;
-  }> = new Map();
-
-  // Associative memory
-  private associations: Map<string, Float32Array[]> = new Map();
-
-  async init() {
-    await this.embedder.init();
-  }
-
-  // Sensory encoding - continuous stream
-  async sense(input: string) {
-    const encoded = await this.embedder.embed(input);
-
-    // Maintain sliding window (sensory buffer)
-    this.sensoryBuffer.push(encoded);
-    if (this.sensoryBuffer.length > 10) {
-      this.sensoryBuffer.shift();
-    }
-
-    // Check reflexes
-    await this.checkReflexes(encoded);
-
-    // Update attention based on novelty
-    this.updateAttention(encoded);
-
-    return encoded;
-  }
-
-  // Reflex registration
-  async registerReflex(
-    name: string,
-    triggerConcept: string,
-    threshold: number,
-    response: () => void
-  ) {
-    const triggerEmb = await this.embedder.embed(triggerConcept);
-    this.reflexes.set(name, { trigger: triggerEmb, threshold, response });
-  }
-
-  // Fast reflex checking (no reasoning)
-  private async checkReflexes(input: Float32Array) {
-    for (const [name, reflex] of this.reflexes) {
-      const activation = cosineSimilarity(input, reflex.trigger);
-      if (activation > reflex.threshold) {
-        // Immediate response - no deliberation
-        console.log(`Reflex triggered: ${name} (activation: ${activation.toFixed(3)})`);
-        reflex.response();
-      }
-    }
-  }
-
-  // Attention routing based on novelty
-  private updateAttention(input: Float32Array) {
-    if (this.sensoryBuffer.length < 2) {
-      this.attentionWeights = input;
-      return;
-    }
-
-    // Calculate novelty (distance from recent average)
-    const recentAvg = new Float32Array(input.length).fill(0);
-    for (const past of this.sensoryBuffer.slice(0, -1)) {
-      for (let i = 0; i < input.length; i++) {
-        recentAvg[i] += past[i];
-      }
-    }
-    for (let i = 0; i < input.length; i++) {
-      recentAvg[i] /= (this.sensoryBuffer.length - 1);
-    }
-
-    const novelty = 1 - cosineSimilarity(input, recentAvg);
-
-    // High novelty = high attention
-    this.attentionWeights = new Float32Array(input.length);
-    for (let i = 0; i < input.length; i++) {
-      this.attentionWeights[i] = input[i] * (1 + novelty);
-    }
-  }
-
-  // Associative recall
-  async associate(concept: string, relatedConcepts: string[]) {
-    const conceptEmb = await this.embedder.embed(concept);
-    const relatedEmbs = await this.embedder.embedBatch(relatedConcepts);
-    this.associations.set(concept, relatedEmbs);
-  }
-
-  async recall(cue: string, topK = 3): Promise<Float32Array[]> {
-    const cueEmb = await this.embedder.embed(cue);
-
-    // Spread activation through associations
-    const activated: Array<{ emb: Float32Array; strength: number }> = [];
-
-    for (const [concept, related] of this.associations) {
-      const conceptEmb = await this.embedder.embed(concept);
-      const similarity = cosineSimilarity(cueEmb, conceptEmb);
-
-      if (similarity > 0.5) {
-        for (const relEmb of related) {
-          activated.push({
-            emb: relEmb,
-            strength: similarity * cosineSimilarity(cueEmb, relEmb)
-          });
-        }
-      }
-    }
-
-    // Return top activated
-    return activated
-      .sort((a, b) => b.strength - a.strength)
-      .slice(0, topK)
-      .map(a => a.emb);
-  }
-
-  // Continuous regulation loop
-  async regulate(
-    perception: string,
-    internalState: Float32Array
-  ): Promise<Float32Array> {
-    const percEmb = await this.embedder.embed(perception);
-
-    // Blend perception with internal state (homeostasis)
-    const regulated = new Float32Array(percEmb.length);
-    const externalWeight = 0.6;
-    const internalWeight = 0.4;
-
-    for (let i = 0; i < regulated.length; i++) {
-      regulated[i] =
-        externalWeight * percEmb[i] +
-        internalWeight * internalState[i];
-    }
-
-    // Apply attention gating
-    if (this.attentionWeights) {
-      for (let i = 0; i < regulated.length; i++) {
-        regulated[i] *= this.attentionWeights[i];
-      }
-    }
-
-    // Normalize
-    const norm = Math.sqrt(regulated.reduce((s, v) => s + v * v, 0));
-    for (let i = 0; i < regulated.length; i++) {
-      regulated[i] /= norm;
-    }
-
-    return regulated;
-  }
-}
-
-// Usage
-const nervous = new SyntheticNervousSystem();
-await nervous.init();
-
-// Register reflexes
-await nervous.registerReflex(
-  'danger',
-  'threat danger emergency attack harm',
-  0.7,
-  () => console.log('DANGER RESPONSE: Immediate protective action')
-);
-
-await nervous.registerReflex(
-  'opportunity',
-  'opportunity benefit reward gain success',
-  0.8,
-  () => console.log('OPPORTUNITY RESPONSE: Engage approach behavior')
-);
-
-// Continuous sensing
-await nervous.sense("The user seems happy with the progress");
-await nervous.sense("Warning: unusual activity detected"); // Triggers reflex
-```
-
-**Capabilities:**
-- Sensory encoding
-- Reflex thresholds
-- Associative recall
-- Attention routing
-- Continuous geometric regulation
-
-No explicit reasoning. No prompts. Just continuous geometric regulation.
-
-This is where machines stop feeling like tools and start feeling **responsive**.
-
----
-
-## Integration with Agentic-Flow
-
-These patterns integrate naturally with agentic-flow's existing architecture:
-
-```typescript
-import { getOptimizedEmbedder } from 'agentic-flow/embeddings';
-import { ReasoningBank } from 'agentic-flow/reasoningbank';
-
-// Memory Physics + ReasoningBank
-const bank = new ReasoningBank();
-const embedder = getOptimizedEmbedder();
-
-// Store experiences with geometric memory properties
-async function storeExperience(task: string, outcome: string, success: boolean) {
-  const taskEmb = await embedder.embed(task);
-  const outcomeEmb = await embedder.embed(outcome);
-
-  // ReasoningBank stores with embedding metadata
-  await bank.recordOutcome({
-    task,
-    outcome,
-    success,
-    embedding: Array.from(taskEmb), // Geometric signature
-    similarity_threshold: 0.8 // For future retrieval
-  });
-}
-
-// Swarm Coordination via Embeddings
-import { SwarmCoordinator } from 'agentic-flow/swarm';
-
-const swarm = new SwarmCoordinator({
-  topology: 'mesh',
-  coordinationMethod: 'embedding', // New: geometric coordination
-  embedder: getOptimizedEmbedder()
-});
-
-// Agents coordinate via position sharing, not messages
-await swarm.init();
-```
-
----
-
-## The Future
-
-> Intelligence moves from models to geometry.
-
-The embedding manifold becomes:
-- The communication channel
-- The memory substrate
-- The coordination primitive
-- The safety monitor
-- The nervous system
-
-We're building the infrastructure for this shift.