enigma-memory 0.1.17 → 0.1.22

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

@@ -0,0 +1,123 @@
+// Enigma Memory Intelligence: Temporal Validity & Observation Windows.
+// Handles time-bounded validity, observation provenance, and exponential decay models.
+import { MEMORY_TYPES } from './ontology.js';
+
+/**
+ * Constructs normalized temporal metadata for a memory atom.
+ * @param {Object} [options]
+ * @param {number|string|Date} [options.validFrom] - Start of validity window (defaults to now)
+ * @param {number|string|Date|null} [options.validUntil] - End of validity (null = indefinitely valid)
+ * @param {number|string|Date} [options.observedAt] - Time observation was recorded
+ * @param {number} [options.ttlMs] - Time-to-live in milliseconds
+ * @returns {{ validFrom: number, validUntil: number|null, observedAt: number, isPermanent: boolean }}
+ */
+export function createTemporalMetadata(options = {}) {
+  const now = Date.now();
+  const observedAt = parseRequiredTimestamp(options.observedAt, now, 'observedAt');
+  const validFrom = parseRequiredTimestamp(options.validFrom, observedAt, 'validFrom');
+
+  let validUntil = null;
+  if (options.validUntil !== undefined && options.validUntil !== null) {
+    validUntil = parseRequiredTimestamp(options.validUntil, null, 'validUntil');
+  } else if (options.ttlMs !== undefined) {
+    if (typeof options.ttlMs !== 'number' || !Number.isFinite(options.ttlMs) || options.ttlMs < 0) {
+      throw new TypeError('ttlMs must be a finite non-negative number');
+    }
+    validUntil = validFrom + options.ttlMs;
+  }
+  if (validUntil !== null && validUntil < validFrom) {
+    throw new RangeError('validUntil must be greater than or equal to validFrom');
+  }
+
+  return {
+    validFrom,
+    validUntil,
+    observedAt,
+    isPermanent: validUntil === null,
+  };
+}
+
+function parseRequiredTimestamp(value, fallback, fieldName) {
+  if (value === null || value === undefined) {
+    if (fallback === null) throw new TypeError(`${fieldName} must be a valid timestamp`);
+    return fallback;
+  }
+  const parsed = parseTimestamp(value, null);
+  if (parsed === null) throw new TypeError(`${fieldName} must be a valid timestamp`);
+  return parsed;
+}
+
+/**
+ * Safely parses timestamps from number, string, or Date.
+ * @param {number|string|Date|undefined|null} val
+ * @param {number|null} fallback
+ * @returns {number|null}
+ */
+export function parseTimestamp(val, fallback = Date.now()) {
+  if (val === null || val === undefined) return fallback;
+  if (typeof val === 'number') return Number.isFinite(val) ? val : fallback;
+  if (val instanceof Date) {
+    const parsed = val.getTime();
+    return Number.isFinite(parsed) ? parsed : fallback;
+  }
+  if (typeof val === 'string' && val.trim().length > 0) {
+    const parsed = Date.parse(val);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return fallback;
+}
+
+/**
+ * Checks whether a memory atom is currently active and valid at a target query timestamp.
+ * @param {Object} atom - Memory atom with metadata or temporal fields
+ * @param {number|string|Date} [queryTime=Date.now()]
+ * @returns {boolean}
+ */
+export function isTemporallyActive(atom, queryTime = Date.now()) {
+  if (!atom) return false;
+  const targetTime = parseTimestamp(queryTime, null);
+  if (targetTime === null) return false;
+  const meta = atom.temporal || atom.metadata?.temporal || atom.metadata || {};
+
+  const validFromSource = meta.validFrom ?? atom.createdAt ?? 0;
+  const validFrom = parseTimestamp(validFromSource, null);
+  const validUntil = meta.validUntil !== undefined && meta.validUntil !== null
+    ? parseTimestamp(meta.validUntil, null)
+    : null;
+  if (validFrom === null) return false;
+  if (meta.validUntil !== undefined && meta.validUntil !== null && validUntil === null) return false;
+  if (validUntil !== null && validUntil < validFrom) return false;
+  if (targetTime < validFrom) return false;
+  if (validUntil !== null && targetTime > validUntil) return false;
+  return true;
+}
+
+/**
+ * Computes exponential recency/decay score multiplier (0.0 to 1.0) based on age and memory type.
+ * Policy and identity memories do not decay (multiplier = 1.0).
+ * Episodic memories decay over a half-life of 30 days.
+ * @param {Object} atom
+ * @param {number} [queryTime=Date.now()]
+ * @param {number} [halfLifeDays=30]
+ * @returns {number} Multiplier between 0.1 and 1.0
+ */
+export function computeTemporalDecay(atom, queryTime = Date.now(), halfLifeDays = 30) {
+  const type = atom.type || atom.metadata?.type || MEMORY_TYPES.SEMANTIC;
+  if (type === MEMORY_TYPES.POLICY || type === MEMORY_TYPES.IDENTITY) {
+    return 1.0;
+  }
+
+  const targetTime = parseTimestamp(queryTime, Date.now());
+  const observedAt = parseTimestamp(
+    atom.observedAt ?? atom.temporal?.observedAt ?? atom.createdAt,
+    targetTime
+  );
+  const ageMs = Math.max(0, targetTime - observedAt);
+  const ageDays = ageMs / (1000 * 60 * 60 * 24);
+
+  const effectiveHalfLife = type === MEMORY_TYPES.EPISODIC ? halfLifeDays : halfLifeDays * 3;
+  const decayFactor = Math.pow(0.5, ageDays / effectiveHalfLife);
+
+  // Floor at 0.2 so historic memories remain recallable
+  return Math.max(0.2, Math.min(1.0, decayFactor));
+}

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

@@ -0,0 +1,142 @@
+// Enigma SDK: ZKCP Sealed Sale Marketplace Client.
+import crypto from 'node:crypto';
+
+export class EnigmaMarketClient {
+  /**
+   * @param {Object} [options]
+   * @param {string} [options.apiBase] - Local daemon or proxy endpoint
+   * @param {string} [options.authToken] - Local IPC auth token
+   */
+  constructor(options = {}) {
+    this.apiBase = options.apiBase || 'http://127.0.0.1:8787';
+    this.authToken = options.authToken || null;
+  }
+
+  /**
+   * Internal authenticated API helper.
+   */
+  async _request(path, method = 'GET', body = null) {
+    const headers = { 'Accept': 'application/json' };
+    if (this.authToken) headers['X-Enigma-Auth-Token'] = this.authToken;
+    if (body) headers['Content-Type'] = 'application/json';
+
+    const res = await fetch(`${this.apiBase}${path}`, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    const data = await res.json().catch(() => null);
+    if (!res.ok || (data && data.ok === false)) {
+      throw new Error(data?.error || `HTTP ${res.status}`);
+    }
+    return data;
+  }
+
+  /**
+   * Retrieves marketplace circuit parameters and local state status.
+   */
+  async getStatus() {
+    return await this._request('/api/zk/status');
+  }
+
+  /**
+   * Retrieves or derives the buyer's local BabyJubJub identity and escrow address.
+   */
+  async getBuyerIdentity() {
+    return await this._request('/api/zk/sale/buyer-identity');
+  }
+
+  /**
+   * Prepares and proves a sealed sale listing for a confidential memory atom.
+   * @param {Object} params
+   * @param {number} params.noteIndex - Index of the appended note in the sovereign note tree
+   * @param {string|number} params.priceLamports - Price in lamports
+   * @param {number} [params.expirySlots=4000] - Expiry slots
+   * @param {string} params.buyerPubkeyX - Buyer's BabyJub public key X coordinate
+   * @param {string} params.buyerPubkeyY - Buyer's BabyJub public key Y coordinate
+   */
+  async prepareListing(params) {
+    return await this._request('/api/zk/sale/prepare-listing', 'POST', params);
+  }
+  /**
+   * Submits a prepared Groth16 listing proof to the settlement program.
+   * Only the public proof, public inputs, and optional predecessor receipt refs
+   * traverse the submission endpoint.
+   * @param {Object} prepared
+   * @param {Object} prepared.proofBytes
+   * @param {string[]} prepared.publicInputs
+   * @param {string[]} [prepared.predecessorReceiptRefs]
+   */
+  async submitListing(prepared) {
+    if (!prepared || typeof prepared !== 'object' || Array.isArray(prepared)) {
+      throw new TypeError('prepared listing must be an object');
+    }
+    return await this._request('/api/zk/sale/submit-listing', 'POST', {
+      proofBytes: prepared.proofBytes,
+      publicInputs: prepared.publicInputs,
+      predecessorReceiptRefs: prepared.predecessorReceiptRefs || [],
+    });
+  }
+
+  /**
+   * Runs the complete seller listing sequence against the real desktop routes:
+   * prepare/prove locally, then submit the resulting public proof on-chain.
+   * @param {Object} params
+   * @param {string[]} [params.predecessorReceiptRefs]
+   */
+  async createListing(params) {
+    if (!params || typeof params !== 'object' || Array.isArray(params)) {
+      throw new TypeError('listing params must be an object');
+    }
+    const { predecessorReceiptRefs = [], ...prepareParams } = params;
+    const prepared = await this.prepareListing(prepareParams);
+    const submitted = await this.submitListing({
+      proofBytes: prepared.proofBytes,
+      publicInputs: prepared.publicInputs,
+      predecessorReceiptRefs,
+    });
+    return {
+      ok: true,
+      listing: {
+        ...prepared,
+        receiptPda: submitted.receiptPda,
+        receiptRef: submitted.receiptRef,
+        settlementReceipt: submitted.settlementReceipt,
+      },
+      submission: submitted,
+    };
+  }
+
+  /**
+   * Performs offline and on-chain verification of a seller's sealed listing.
+   * Verifies Poseidon-CTR cipher fold and BabyJub recipient binding before paying.
+   * @param {Object} listing
+   */
+  async verifyListing(listing) {
+    return await this._request('/api/zk/sale/verify', 'POST', listing);
+  }
+
+  /**
+   * Funds an on-chain escrow account on Solana locked to a verified receipt PDA.
+   * @param {Object} listing
+   */
+  async fundEscrow(listing) {
+    return await this._request('/api/zk/sale/escrow', 'POST', listing);
+  }
+
+  /**
+   * Seller: Atomically claims a funded escrow, revealing the encrypted key envelope on-chain.
+   * @param {Object} params
+   */
+  async claim(params) {
+    return await this._request('/api/zk/sale/claim', 'POST', params);
+  }
+
+  /**
+   * Buyer: Reads the revealed envelope on-chain and decrypts the off-chain ciphertext chunks.
+   * @param {Object} params
+   */
+  async open(params) {
+    return await this._request('/api/zk/sale/open', 'POST', params);
+  }
+}

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

@@ -0,0 +1,110 @@
+// Enigma SDK: GhostMesh P2P Swarm Client.
+import { EventEmitter } from 'node:events';
+import { MeshGossipNode, generateMeshIdentity, sealPayload, unsealPayload } from '../../mesh/src/index.js';
+
+export class EnigmaMeshClient extends EventEmitter {
+  /**
+   * @param {Object} [options]
+   * @param {Object} [options.identity] - Pre-generated mesh identity or auto-generated
+   * @param {string} [options.nodeId] - Human-readable agent node ID
+   * @param {string} [options.scope='enigma.agents']
+   */
+  constructor(options = {}) {
+    super();
+    this.scope = options.scope || 'enigma.agents';
+    this.identity = options.identity || generateMeshIdentity(this.scope);
+    this.nodeId = options.nodeId || `agent_${this.identity.destinationHex.slice(0, 8)}`;
+
+    this.node = new MeshGossipNode({
+      identity: this.identity,
+      nodeId: this.nodeId,
+      scope: this.scope,
+    });
+
+    // Forward internal events
+    this.node.on('capsule', (capsule) => this.emit('capsule', capsule));
+    this.node.on('sale:offer', (offer) => this.emit('sale:offer', offer));
+    this.node.on('zk:proof', (proof) => this.emit('zk:proof', proof));
+    this.node.on('peer:discovered', (peer) => this.emit('peer:discovered', peer));
+  }
+
+  /**
+   * Starts the mesh node and begins background route discovery.
+   */
+  async start() {
+    await this.node.start();
+    return this.status();
+  }
+
+  /**
+   * Stops the mesh node and tears down active transports.
+   */
+  async stop() {
+    await this.node.stop();
+  }
+
+  /**
+   * Broadcasts an announce beacon with agent metadata across all active transports.
+   * @param {Object} [metadata={}]
+   */
+  async announce(metadata = {}) {
+    const payload = {
+      agentName: this.nodeId,
+      encryptionPublicKeyHex: this.identity.encryptionPublicKey ? this.identity.encryptionPublicKey.toString('hex') : null,
+      ...metadata,
+    };
+    return await this.node.announce(payload);
+  }
+
+  /**
+   * Sends an end-to-end encrypted memory capsule to a target destination peer.
+   * @param {string|Buffer} destination - 32-byte destination hash
+   * @param {string|Buffer} recipientX25519Pub - Recipient's 32-byte X25519 public key
+   * @param {string|Buffer} payload - Confidential memory string or buffer
+   * @param {Object} [options]
+   * @returns {Promise<{ packetId: string, routed: boolean, deliveredLocally: boolean }>}
+   */
+  async send(destination, recipientX25519Pub, payload, options = {}) {
+    const destHex = Buffer.isBuffer(destination) ? destination.toString('hex') : destination;
+    const xPubBuf = Buffer.isBuffer(recipientX25519Pub) ? recipientX25519Pub : Buffer.from(recipientX25519Pub, 'hex');
+    return await this.node.sendEncryptedCapsule(destHex, xPubBuf, payload, options);
+  }
+
+  /**
+   * Discovers and returns all active peer agents.
+   * @returns {Array<Object>}
+   */
+  getPeers() {
+    return this.node.getPeers();
+  }
+
+  /**
+   * Subscribes to incoming decrypted memory capsules.
+   * @param {Function} listener
+   */
+  onCapsule(listener) {
+    this.node.on('capsule', listener);
+  }
+
+  /**
+   * @param {Object} transport
+   */
+  addTransport(transport) {
+    return this.node.addTransport(transport);
+  }
+
+  /**
+   * Returns current node status and public identity hashes.
+   * @returns {Object}
+   */
+  status() {
+    return {
+      nodeId: this.nodeId,
+      scope: this.scope,
+      destinationHex: this.identity.destinationHex,
+      publicKeyHex: this.identity.publicKey.toString('hex'),
+      encryptionPublicKeyHex: this.identity.encryptionPublicKey ? this.identity.encryptionPublicKey.toString('hex') : null,
+      peersCount: this.node.getPeers().length,
+    };
+  }
+}

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

@@ -0,0 +1,3 @@
+export { EnigmaLangChainMemory } from './langchain.js';
+export { createEnigmaContextMiddleware } from './vercel-ai.js';
+export { EnigmaLlamaIndexRetriever } from './llamaindex.js';

package/packages/sdk/src/middleware/langchain.js

@@ -0,0 +1,159 @@
+// Enigma LangChain Memory & Lifecycle Adapter.
+// Connects LangChain agents and chains to Enigma sovereign encrypted memory
+// with automated decision filtering, tool execution tracking, and contradiction handling.
+import { Enigma } from '../index.js';
+
+export class EnigmaLangChainMemory {
+  /**
+   * @param {Object} options
+   * @param {Enigma} options.enigma - Connected Enigma instance
+   * @param {string} [options.memoryKey='history'] - Output key for formatted context
+   * @param {string} [options.inputKey='input']
+   * @param {string} [options.outputKey='output']
+   * @param {number} [options.maxTokens=2000] - Token budget for context compilation
+   * @param {string} [options.scope]
+   * @param {boolean} [options.selectiveMemory=true] - Uses DecisionEngine to filter low-signal noise
+   */
+  constructor(options = {}) {
+    if (!options.enigma || typeof options.enigma.remember !== 'function') {
+      throw new Error('options.enigma must be an initialized Enigma instance');
+    }
+    this.enigma = options.enigma;
+    this.memoryKey = options.memoryKey || 'history';
+    this.inputKey = options.inputKey || 'input';
+    this.outputKey = options.outputKey || 'output';
+    this.maxTokens = options.maxTokens ?? 2000;
+    this.scope = options.scope || this.enigma.scope;
+    this.selectiveMemory = options.selectiveMemory !== false;
+  }
+
+  get memoryKeys() {
+    return [this.memoryKey];
+  }
+
+  /**
+   * Loads relevant memory context for the incoming prompt values.
+   * @param {Record<string, unknown>} [values={}]
+   * @returns {Promise<Record<string, string>>}
+   */
+  async loadMemoryVariables(values = {}) {
+    const query = typeof values[this.inputKey] === 'string'
+      ? values[this.inputKey]
+      : (typeof values.prompt === 'string' ? values.prompt : '');
+
+    if (!query) {
+      return { [this.memoryKey]: '' };
+    }
+
+    const pack = await this.enigma.getContextPack(query, {
+      maxTokens: this.maxTokens,
+      scope: this.scope,
+    });
+
+    return {
+      [this.memoryKey]: pack.contextText,
+    };
+  }
+
+  /**
+   * Stores a conversational turn or observation into sovereign encrypted memory.
+   * Evaluates novelty and importance if selectiveMemory is enabled.
+   * @param {Record<string, unknown>} inputValues
+   * @param {Record<string, unknown>} outputValues
+   * @returns {Promise<void>}
+   */
+  async saveContext(inputValues = {}, outputValues = {}) {
+    const input = inputValues[this.inputKey] || inputValues.prompt || '';
+    const output = outputValues[this.outputKey] || outputValues.response || outputValues.text || '';
+
+    if (!input && !output) return;
+
+    const memoryText = input && output ? `User: ${input}\nAssistant: ${output}` : String(input || output);
+
+    if (this.selectiveMemory) {
+      const evaluation = this.enigma.evaluateObservation(memoryText, { framework: 'langchain' });
+      if (!evaluation.shouldRemember) {
+        return; // Filtered low-signal chat chatter
+      }
+    }
+
+    await this.enigma.remember(memoryText, {
+      scope: this.scope,
+      metadata: { framework: 'langchain', turnType: 'dialogue' },
+    });
+  }
+
+  /**
+   * Lifecycle Hook: Executed before an LLM invocation to inject sovereign context.
+   * @param {Array<Object>|string} promptOrMessages
+   * @returns {Promise<{ sovereignContext: string, items: Array }>}
+   */
+  async beforeModel(promptOrMessages) {
+    const queryText = typeof promptOrMessages === 'string'
+      ? promptOrMessages
+      : Array.isArray(promptOrMessages) && promptOrMessages.length > 0
+        ? promptOrMessages[promptOrMessages.length - 1].content || promptOrMessages[promptOrMessages.length - 1].text || ''
+        : '';
+
+    const pack = await this.enigma.getContextPack(queryText, {
+      maxTokens: this.maxTokens,
+      scope: this.scope,
+    });
+
+    return {
+      sovereignContext: pack.contextText,
+      items: pack.items,
+    };
+  }
+
+  /**
+   * Lifecycle Hook: Executed after a tool execution to record procedural execution receipts.
+   * @param {string} toolName
+   * @param {Object} toolInput
+   * @param {Object} toolOutput
+   */
+  async afterTool(toolName, toolInput, toolOutput) {
+    const recordText = `Tool Execution [${toolName}]: Input: ${JSON.stringify(toolInput)} => Output: ${JSON.stringify(toolOutput)}`;
+    await this.enigma.remember(recordText, {
+      scope: this.scope,
+      type: 'procedural',
+      importance: 1.2,
+      metadata: { toolName, framework: 'langchain' },
+    });
+  }
+
+  /**
+   * Records a user correction and registers supersession in the contradiction DAG.
+   * @param {string} priorFact
+   * @param {string} updatedFact
+   * @param {string} [reason='user_correction']
+   */
+  async onCorrection(priorFact, updatedFact, reason = 'user_correction') {
+    const candidates = await this.enigma.recall(priorFact, { scope: this.scope, topK: 3 });
+    const priorId = candidates.length > 0 ? candidates[0].id : null;
+
+    const newAtom = await this.enigma.remember(updatedFact, {
+      scope: this.scope,
+      type: 'semantic',
+      importance: 2.0,
+      supersedes: priorId ? [priorId] : [],
+      metadata: { reason, framework: 'langchain' },
+    });
+
+    return newAtom;
+  }
+
+  /**
+   * Clears all memory atoms recorded under this memory scope.
+   * @returns {Promise<number>} Count of forgotten memories
+   */
+  async clear() {
+    let count = 0;
+    const scopedMemories = Array.from(this.enigma._memories.values()).filter(m => m.scope === this.scope);
+    for (const mem of scopedMemories) {
+      await this.enigma.forget(mem.id);
+      count++;
+    }
+    return count;
+  }
+}

package/packages/sdk/src/middleware/llamaindex.js

@@ -0,0 +1,101 @@
+// Enigma LlamaIndex Retriever Adapter & Node Store.
+// Connects LlamaIndex node indexers, synthesizers, and query engines to sovereign encrypted vector memory.
+import { Enigma } from '../index.js';
+
+export class EnigmaLlamaIndexRetriever {
+  /**
+   * @param {Object} options
+   * @param {Enigma} options.enigma - Connected Enigma instance
+   * @param {number} [options.similarityTopK=5]
+   * @param {string} [options.scope]
+   */
+  constructor(options = {}) {
+    if (!options.enigma || typeof options.enigma.recall !== 'function') {
+      throw new Error('options.enigma must be an initialized Enigma instance');
+    }
+    this.enigma = options.enigma;
+    this.similarityTopK = options.similarityTopK || 5;
+    this.scope = options.scope || this.enigma.scope;
+  }
+
+  /**
+   * Retrieves nodes matching the query string.
+   * @param {string} query
+   * @returns {Promise<Array<{ node: { id_: string, text: string, metadata: Record<string, unknown> }, score: number }>>}
+   */
+  async retrieve(query) {
+    if (!query || typeof query !== 'string') return [];
+
+    const results = await this.enigma.recall(query, {
+      topK: this.similarityTopK,
+      scope: this.scope,
+    });
+
+    return results.map((r) => ({
+      node: {
+        id_: r.id,
+        text: r.text,
+        metadata: {
+          scope: r.scope,
+          type: r.type,
+          superseded: r.superseded,
+          createdAt: r.createdAt,
+          ...r.metadata,
+        },
+      },
+      score: r.score,
+    }));
+  }
+
+  /**
+   * Batch inserts LlamaIndex nodes into sovereign memory.
+   * @param {Array<{ id_?: string, text: string, metadata?: Object }>} nodes
+   * @returns {Promise<number>}
+   */
+  async insertNodes(nodes = []) {
+    let count = 0;
+    for (const n of nodes) {
+      if (n.text) {
+        await this.enigma.remember(n.text, {
+          id: n.id_,
+          scope: this.scope,
+          metadata: { framework: 'llamaindex', ...(n.metadata || {}) },
+        });
+        count++;
+      }
+    }
+    return count;
+  }
+
+  /**
+   * Deletes nodes by ID.
+   * @param {string[]} nodeIds
+   * @returns {Promise<number>}
+   */
+  async deleteNodes(nodeIds = []) {
+    let count = 0;
+    for (const id of nodeIds) {
+      const ok = await this.enigma.forget(id);
+      if (ok) count++;
+    }
+    return count;
+  }
+
+  /**
+   * Records a factual correction in the knowledge base.
+   * @param {string} priorFact
+   * @param {string} updatedFact
+   */
+  async onCorrection(priorFact, updatedFact) {
+    const matches = await this.enigma.recall(priorFact, { scope: this.scope, topK: 3 });
+    const priorId = matches.length > 0 ? matches[0].id : null;
+
+    return await this.enigma.remember(updatedFact, {
+      scope: this.scope,
+      type: 'semantic',
+      importance: 2.0,
+      supersedes: priorId ? [priorId] : [],
+      metadata: { framework: 'llamaindex', correction: true },
+    });
+  }
+}