enigma-memory 0.1.18 → 0.1.22

package/packages/sdk/src/middleware/vercel-ai.js

@@ -0,0 +1,112 @@
+// Enigma Vercel AI SDK Middleware & Multi-Hook Lifecycle.
+// Injects sovereign memory context into streamText / generateText functions,
+// tracks tool executions, and applies selective noise filtering.
+import { Enigma } from '../index.js';
+
+/**
+ * Creates a middleware wrapper for Vercel AI SDK streamText / generateText functions.
+ * @param {Enigma} enigma - Connected Enigma instance
+ * @param {Object} [options]
+ * @param {number} [options.maxTokens=1500]
+ * @param {string} [options.scope]
+ * @param {boolean} [options.autoRemember=true]
+ * @param {boolean} [options.selectiveMemory=true]
+ */
+export function createEnigmaContextMiddleware(enigma, options = {}) {
+  if (!enigma || typeof enigma.remember !== 'function') {
+    throw new Error('enigma must be an initialized Enigma instance');
+  }
+
+  const maxTokens = options.maxTokens ?? 1500;
+  const scope = options.scope || enigma.scope;
+  const autoRemember = options.autoRemember !== false;
+  const selectiveMemory = options.selectiveMemory !== false;
+
+  return {
+    /**
+     * Augments user prompt / messages with sovereign memory context.
+     * @param {Object} params
+     * @param {string} [params.prompt]
+     * @param {Array<{ role: string, content: string }>} [params.messages]
+     * @param {string} [params.system]
+     * @returns {Promise<Object>}
+     */
+    async enrichPrompt(params = {}) {
+      const queryText = params.prompt
+        || (params.messages && params.messages.length > 0 ? params.messages[params.messages.length - 1].content : '');
+
+      if (!queryText) return params;
+
+      const pack = await enigma.getContextPack(queryText, { maxTokens, scope });
+      if (!pack.contextText) return params;
+
+      const sovereignSystemHeader = `\n\n[SOVEREIGN MEMORY CONTEXT]\n${pack.contextText}\n[END CONTEXT]\n`;
+
+      return {
+        ...params,
+        system: params.system ? `${params.system}${sovereignSystemHeader}` : sovereignSystemHeader.trim(),
+        sovereignContext: pack.contextText,
+        contextItems: pack.items,
+      };
+    },
+
+    /**
+     * Records completed model response into sovereign encrypted memory.
+     * Filters transient chatter if selectiveMemory is true.
+     * @param {string} prompt
+     * @param {string} completion
+     * @param {Object} [metadata]
+     * @returns {Promise<Object|null>}
+     */
+    async recordTurn(prompt, completion, metadata = {}) {
+      if (!autoRemember || !prompt || !completion) return null;
+      const turnRecord = `User: ${prompt}\nAI: ${completion}`;
+
+      if (selectiveMemory) {
+        const evaluation = enigma.evaluateObservation(turnRecord, { framework: 'vercel_ai_sdk', ...metadata });
+        if (!evaluation.shouldRemember) {
+          return null; // Filtered noise
+        }
+      }
+
+      return await enigma.remember(turnRecord, {
+        scope,
+        metadata: { framework: 'vercel_ai_sdk', recordedAt: Date.now(), ...metadata },
+      });
+    },
+
+    /**
+     * Lifecycle Hook: Records tool invocation and result.
+     * @param {string} toolName
+     * @param {Object} args
+     * @param {Object} result
+     */
+    async onToolExecution(toolName, args, result) {
+      const toolText = `Vercel AI Tool Execution [${toolName}]: Args: ${JSON.stringify(args)} => Result: ${JSON.stringify(result)}`;
+      return await enigma.remember(toolText, {
+        scope,
+        type: 'procedural',
+        importance: 1.2,
+        metadata: { toolName, framework: 'vercel_ai_sdk' },
+      });
+    },
+
+    /**
+     * Registers a user correction and updates supersession graph.
+     * @param {string} priorFact
+     * @param {string} updatedFact
+     */
+    async onCorrection(priorFact, updatedFact) {
+      const matches = await enigma.recall(priorFact, { scope, topK: 3 });
+      const priorId = matches.length > 0 ? matches[0].id : null;
+
+      return await enigma.remember(updatedFact, {
+        scope,
+        type: 'semantic',
+        importance: 2.0,
+        supersedes: priorId ? [priorId] : [],
+        metadata: { framework: 'vercel_ai_sdk', correction: true },
+      });
+    },
+  };
+}

package/packages/sdk/src/rag-client.js

@@ -0,0 +1,85 @@
+// Enigma SDK: Semantic Vector & RAG Client.
+import { EncryptedVectorStore, createEmbeddingProvider } from '../../rag/src/index.js';
+
+export class EnigmaRagClient {
+  /**
+   * @param {Object} [options]
+   * @param {EncryptedVectorStore} [options.vectorStore]
+   * @param {Object} [options.embeddingProvider]
+   * @param {'neural'|'lexical'} [options.embeddingModel='neural']
+   */
+  constructor(options = {}) {
+    if (options.vectorStore) {
+      this.store = options.vectorStore;
+      return;
+    }
+    const embeddingProvider = options.embeddingProvider || createEmbeddingProvider({
+      modelType: options.embeddingModel || 'neural',
+    });
+    this.store = new EncryptedVectorStore({ quantize: true, embeddingProvider });
+  }
+
+  /**
+   * Indexes a memory text string into the local semantic vector store.
+   * @param {string} id
+   * @param {string} text
+   * @param {Object} [metadata={}]
+   */
+  async index(id, text, metadata = {}, options = {}) {
+    return await this.store.add(id, text, metadata, options);
+  }
+
+  /**
+   * Replaces retrieval metadata without treating receipt payloads as embeddable prose.
+   * @param {string} id
+   * @param {Object} metadata
+   */
+  updateMetadata(id, metadata) {
+    return this.store.updateMetadata(id, metadata);
+  }
+
+  /**
+   * Searches for top-k semantically similar memory atoms.
+   * @param {string} query
+   * @param {Object} [options]
+   * @returns {Promise<Array<Object>>}
+   */
+  async search(query, options = {}) {
+    return await this.store.search(query, options);
+  }
+
+  /**
+   * Compiles token-budgeted prompt context for an autonomous agent.
+   * @param {string} query
+   * @param {Object} [options]
+   * @returns {Promise<{ contextText: string, items: Array, totalChars: number, estimatedTokens: number }>}
+   */
+  async compileContext(query, options = {}) {
+    return await this.store.compileContextPack(query, options);
+  }
+
+  /**
+   * Encrypts the vector collection at rest for vault persistence.
+   * @param {Buffer|string} vaultKey
+   */
+  encryptAtRest(vaultKey) {
+    return this.store.encryptForVault(vaultKey);
+  }
+
+  /**
+   * Restores vector store from an encrypted bundle, retaining its recorded
+   * provider semantics. Legacy or adapter-backed bundles require an explicit
+   * embeddingProvider.
+   * @param {Object} bundle
+   * @param {Buffer|string} vaultKey
+   * @param {{ embeddingProvider?: Object }} [options]
+   */
+  static fromEncryptedBundle(bundle, vaultKey, options = {}) {
+    const store = EncryptedVectorStore.decryptFromVault(bundle, vaultKey, options);
+    return new EnigmaRagClient({ vectorStore: store });
+  }
+
+  async dispose() {
+    await this.store.embedder.dispose?.();
+  }
+}

package/packages/sdk/src/swarm-orchestrator.js

@@ -0,0 +1,260 @@
+// Enigma Swarm Orchestrator.
+// Coordinates multi-agent sovereign memory swarms with Role-Based Access Control (RBAC),
+// broadcast coordination, real-time memory events, and synchronized rule consensus.
+import crypto from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import { Enigma } from './index.js';
+import { InMemoryBus, InMemoryTransport } from '../../mesh/src/index.js';
+
+export class EnigmaSwarmOrchestrator extends EventEmitter {
+  /**
+   * @param {Object} [options]
+   * @param {string} [options.swarmId]
+   * @param {string} [options.passphrase]
+   * @param {string} [options.storageDir]
+   * @param {Object} [options.bus] - Custom shared mesh bus
+   * @param {(options: Object) => Promise<Enigma>} [options.enigmaFactory] - Optional agent factory
+   */
+  constructor(options = {}) {
+    super();
+    this.swarmId = options.swarmId || `swarm_${crypto.randomBytes(4).toString('hex')}`;
+    this.passphrase = options.passphrase || null;
+    this.storageDir = options.storageDir || null;
+    this.bus = options.bus || new InMemoryBus();
+    this.enigmaFactory = options.enigmaFactory || ((connectOptions) => Enigma.connect(connectOptions));
+    /** @type {Map<string, { enigma: Enigma, role: string, permissions: Set<string>, scope: string, inbox: Array<Object> }>} */
+    this.agents = new Map();
+  }
+
+  /**
+   * Spawns and registers an autonomous agent into the swarm.
+   * @param {string} agentId
+   * @param {Object} [options]
+   * @param {string} [options.role='worker'] - Agent role (e.g. 'coordinator', 'trader', 'auditor', 'worker')
+   * @param {string[]} [options.permissions] - Granular permissions (e.g. ['read', 'write', 'broadcast', 'zk_prove'])
+   * @param {string} [options.scope] - Agent scope (defaults to agentId)
+   * @returns {Promise<Enigma>}
+   */
+  async registerAgent(agentId, options = {}) {
+    if (!agentId || typeof agentId !== 'string') {
+      throw new Error('agentId must be a non-empty string');
+    }
+    if (this.agents.has(agentId)) {
+      return this.agents.get(agentId).enigma;
+    }
+
+    const role = options.role || 'worker';
+    const permissions = new Set(options.permissions || ['read', 'write']);
+    const scope = options.scope || `agent.${agentId}`;
+
+    const storagePath = this.storageDir
+      ? `${this.storageDir}/${agentId}.vault.enc.json`
+      : undefined;
+
+    const enigma = await this.enigmaFactory({
+      agentId,
+      scope,
+      passphrase: this.passphrase,
+      storagePath,
+    });
+
+    // Attach shared in-memory transport to agent's mesh client
+    const transport = new InMemoryTransport(agentId, this.bus);
+    enigma.mesh.addTransport(transport);
+    await enigma.mesh.start();
+    await enigma.mesh.announce({ role, agentId });
+
+    const inbox = [];
+    const agentEntry = {
+      enigma,
+      role,
+      permissions,
+      scope,
+      inbox,
+    };
+
+    // Wire real-time mesh listeners
+    enigma.mesh.onCapsule((capsule) => {
+      inbox.push(capsule);
+      this.emit('capsule:received', {
+        swarmId: this.swarmId,
+        recipientAgentId: agentId,
+        sender: capsule.sender,
+        plaintext: capsule.plaintext,
+        receivedAt: capsule.receivedAt,
+      });
+    });
+
+    this.agents.set(agentId, agentEntry);
+
+    this.emit('agent:registered', {
+      swarmId: this.swarmId,
+      agentId,
+      role,
+      scope,
+    });
+
+    return enigma;
+  }
+
+  /**
+   * Retrieves a registered agent by ID.
+   * @param {string} agentId
+   * @returns {Enigma|undefined}
+   */
+  getAgent(agentId) {
+    const entry = this.agents.get(agentId);
+    return entry ? entry.enigma : undefined;
+  }
+
+  /**
+   * Unregisters an agent from the swarm.
+   * @param {string} agentId
+   * @returns {Promise<boolean>}
+   */
+  async unregisterAgent(agentId) {
+    const entry = this.agents.get(agentId);
+    if (!entry) return false;
+
+    await entry.enigma.mesh.stop();
+    this.agents.delete(agentId);
+    this.emit('agent:unregistered', { swarmId: this.swarmId, agentId });
+    return true;
+  }
+
+  /**
+   * Propagates a global protocol rule across all registered agents in the swarm.
+   * @param {string} ruleText
+   * @param {Object} [metadata]
+   * @returns {Promise<{ ruleId: string, syncedCount: number }>}
+   */
+  async syncGlobalRule(ruleText, metadata = {}) {
+    if (!ruleText || typeof ruleText !== 'string') {
+      throw new Error('Rule text must be a non-empty string');
+    }
+
+    const ruleId = `rule_${Date.now()}_${crypto.randomBytes(3).toString('hex')}`;
+    let syncedCount = 0;
+
+    for (const [agentId, entry] of this.agents.entries()) {
+      if (entry.permissions.has('write')) {
+        await entry.enigma.remember(ruleText, {
+          id: `${ruleId}_${agentId}`,
+          scope: entry.scope,
+          importance: 2.0,
+          metadata: {
+            swarmId: this.swarmId,
+            ruleId,
+            syncedAt: Date.now(),
+            ...metadata,
+          },
+        });
+        syncedCount++;
+      }
+    }
+
+    this.emit('rule:synced', {
+      swarmId: this.swarmId,
+      ruleId,
+      ruleText,
+      syncedCount,
+    });
+
+    return { ruleId, syncedCount };
+  }
+
+  /**
+   * Dispatches an encrypted coordination signal from a sender agent to a target recipient in the swarm.
+   * @param {string} senderAgentId
+   * @param {string} targetAgentId
+   * @param {string} message
+   * @returns {Promise<{ delivered: boolean, packetId: string, receivedPlaintext?: string }>}
+   */
+  async dispatchSignal(senderAgentId, targetAgentId, message) {
+    const sender = this.agents.get(senderAgentId);
+    const target = this.agents.get(targetAgentId);
+
+    if (!sender) throw new Error(`Sender agent "${senderAgentId}" is not registered in swarm`);
+    if (!target) throw new Error(`Target agent "${targetAgentId}" is not registered in swarm`);
+
+    if (!sender.permissions.has('write') && !sender.permissions.has('broadcast')) {
+      throw new Error(`Sender agent "${senderAgentId}" lacks permission to dispatch swarm signals`);
+    }
+
+    // Set up reception listener for exact delivery proof
+    const deliveryPromise = new Promise((resolve) => {
+      const onCapsule = (event) => {
+        if (event.plaintext === message) {
+          target.enigma.mesh.node.off('capsule', onCapsule);
+          resolve(true);
+        }
+      };
+      target.enigma.mesh.node.on('capsule', onCapsule);
+      // Timeout guard
+      setTimeout(() => {
+        target.enigma.mesh.node.off('capsule', onCapsule);
+        resolve(false);
+      }, 500);
+    });
+
+    const targetIdentity = target.enigma.mesh.identity;
+    const sendResult = await sender.enigma.mesh.send(
+      targetIdentity.destinationHex,
+      targetIdentity.encryptionPublicKey,
+      message
+    );
+
+    const received = await deliveryPromise;
+
+    this.emit('signal:dispatched', {
+      swarmId: this.swarmId,
+      senderAgentId,
+      targetAgentId,
+      message,
+      routed: sendResult.routed,
+      delivered: received,
+      packetId: sendResult.packetId,
+    });
+
+    return {
+      delivered: received && sendResult.routed,
+      packetId: sendResult.packetId,
+      receivedPlaintext: received ? message : undefined,
+    };
+  }
+
+  /**
+   * Returns complete swarm topology and agent roster.
+   */
+  getTopology() {
+    const roster = [];
+    for (const [agentId, entry] of this.agents.entries()) {
+      roster.push({
+        agentId,
+        role: entry.role,
+        scope: entry.scope,
+        permissions: Array.from(entry.permissions),
+        memoryCount: entry.enigma.status().memoryCount,
+        vectorCount: entry.enigma.status().vectorCount,
+        destinationHex: entry.enigma.mesh.identity.destinationHex,
+        inboxCount: entry.inbox.length,
+      });
+    }
+    return {
+      swarmId: this.swarmId,
+      agentCount: this.agents.size,
+      roster,
+    };
+  }
+
+  /**
+   * Gracefully shuts down all agents and active mesh nodes in the swarm.
+   */
+  async shutdown() {
+    for (const entry of this.agents.values()) {
+      await entry.enigma.mesh.stop();
+    }
+    this.agents.clear();
+    this.emit('swarm:shutdown', { swarmId: this.swarmId });
+  }
+}

package/packages/settlement/PACKAGE_CONTRACT.md

@@ -1,4 +1,4 @@
-# `@enigma-ai/enigma/settlement`
+# `enigma-memory/settlement`
 
 Permissionless access and service-settlement protocol for Enigma memory jobs.
 

package/packages/snapcompact/THIRD_PARTY_LICENSES.txt

@@ -0,0 +1,40 @@
+X.ORG MISC-FIXED 8x13 FONT
+===========================
+Asset: assets/8x13-latin1.bdf
+Upstream: https://gitlab.freedesktop.org/xorg/font/misc-misc/-/blob/master/8x13.bdf
+The bundled asset is a Latin-1 subset of the upstream X.Org 8x13 ISO10646-1
+BDF. The upstream BDF declares:
+
+  "Public domain font. Share and enjoy."
+
+
+@OH-MY-PI/SNAPCOMPACT STRATEGY
+==============================
+This package is an independent Node implementation inspired by the dense
+bitmap context strategy in @oh-my-pi/snapcompact. It does not copy or import
+that package, its Bun/native runtime, or its implementation.
+Upstream: https://github.com/can1357/oh-my-pi/tree/main/packages/snapcompact
+
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+Copyright (c) 2025-2026 Can Bölük
+Copyright (c) 2026 Stencil Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.