agentic-flow 3.0.0-alpha.2 → 3.1.0

package/docs/embeddings/EMBEDDING_GEOMETRY.md

@@ -0,0 +1,935 @@
+# 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.