enigma-memory 0.1.18 → 0.1.22

package/examples/01-quickstart-agent/index.mjs

@@ -0,0 +1,49 @@
+// Example 1: Autonomous Agent Sovereign Memory Quickstart
+import { Enigma } from '../../packages/sdk/src/index.js';
+
+async function main() {
+  console.log('--- [Step 1] Connecting Autonomous Agent to Sovereign Memory ---');
+  const enigma = await Enigma.connect({
+    scope: 'agent.solana_trader',
+    passphrase: 'demo_developer_passphrase_2026',
+    storagePath: './agent_vault.enc.json',
+  });
+  console.log('✓ Agent connected:', enigma.status());
+
+  console.log('\n--- [Step 2] Storing Confidential Project Directives ---');
+  await enigma.remember('Risk Directive: Always enforce 0.5% maximum slippage on Jupiter DEX swaps', {
+    importance: 1.0,
+    metadata: { category: 'risk_management', priority: 'critical' },
+  });
+  await enigma.remember('Routing Directive: Fragment large swap orders (>100 SOL) across Orca and Raydium pools', {
+    importance: 0.8,
+    metadata: { category: 'execution', priority: 'high' },
+  });
+  await enigma.remember('General Rule: Never leak raw private keys, wallet seed phrases, or unencrypted memory', {
+    scope: 'enigma.global',
+    importance: 1.0,
+  });
+  console.log(`✓ Stored ${enigma.status().memoryCount} memory atoms in sovereign encrypted custody`);
+
+  console.log('\n--- [Step 3] Semantic Vector Context Recall ---');
+  const query = 'What are the rules for swap slippage and order routing?';
+  console.log(`Agent Query: "${query}"`);
+  const memories = await enigma.recall(query, { topK: 2 });
+  
+  memories.forEach((mem, idx) => {
+    console.log(`  [Match #${idx + 1}] (${Math.round(mem.score * 100)}% match) [${mem.scope}]: ${mem.text}`);
+  });
+
+  console.log('\n--- [Step 4] Compiling Token-Budgeted Prompt Context Pack ---');
+  const pack = await enigma.getContextPack(query, { maxTokens: 500 });
+  console.log(`✓ Compiled context pack (${pack.estimatedTokens} tokens):\n`);
+  console.log(pack.contextText);
+
+  console.log('\n--- [Step 5] Cleaning Up ---');
+  // Optional cleanup of demo file
+  const fs = await import('node:fs');
+  if (fs.existsSync('./agent_vault.enc.json')) fs.unlinkSync('./agent_vault.enc.json');
+  console.log('✓ Quickstart completed successfully!');
+}
+
+main().catch(console.error);

package/examples/01_agent_memory_quickstart.mjs

@@ -0,0 +1,57 @@
+/**
+ * Example 01: Agent Memory Quickstart
+ * Demonstrates local vault creation, storing memory with tags,
+ * recalling context, and verifying the cryptographic receipt.
+ */
+
+import { createVault, remember, recall, exportBundle } from '../packages/vault/src/index.js';
+
+console.log('=== Enigma Agent Memory Quickstart ===\n');
+
+// 1. Initialize local vault
+const vault = createVault({
+  tenant_id: 'agent_sandbox',
+  policy_id: 'strict_local_v1',
+  subject_id: 'agent_007',
+});
+
+console.log('1. Initialized local vault:');
+console.log('   - Tenant:        ', vault.tenant_id);
+console.log('   - Policy:        ', vault.policy_id);
+console.log('   - Vault Address: ', vault.addressKey ? 'Configured (AES-256)' : 'Unset', '\n');
+
+// 2. Store technical context
+const mem1 = await remember({
+  vault,
+  text: 'Solana Anchor micro-escrow smart contracts settle in slot window < 400ms.',
+  purpose: 'agent_trading_strategy',
+  tags: ['solana', 'anchor', 'escrow', 'defi'],
+  importance: 0.95,
+});
+
+console.log('2. Stored memory atom:');
+console.log('   - Memory Address:', mem1.memory_addr);
+console.log('   - Receipt ID:    ', mem1.receipt.receipt_id);
+console.log('   - Operation:     ', mem1.receipt.operation);
+console.log('   - Signer Key ID: ', mem1.receipt.signer.key_id, '\n');
+
+// 3. Recall memory by address
+const recalled = await recall({
+  vault,
+  memory_addr: mem1.memory_addr,
+  purpose: 'agent_decision_inference',
+});
+
+console.log('3. Recalled memory:');
+console.log('   - Decrypted Content: ', recalled.content);
+console.log('   - Read Receipt ID:   ', recalled.receipt.receipt_id);
+console.log('   - Read Log Root:     ', recalled.receipt.receipt_log_root.slice(0, 32) + '...\n');
+
+// 4. Export proof bundle
+const bundle = await exportBundle({ vault });
+console.log('4. Exported proof bundle:');
+console.log('   - Total active memories:       ', bundle.active_memory_addresses.length);
+console.log('   - Total receipts in audit log: ', bundle.receipts.length);
+console.log('   - Vault Active Set Root:       ', bundle.vault.active_set_root.slice(0, 32) + '...');
+
+console.log('\n✔ All quickstart operations succeeded with signed cryptographic receipts!');

package/examples/02-multi-agent-swarm/index.mjs

@@ -0,0 +1,57 @@
+// Example 2: Multi-Agent Sovereign Memory Swarm Orchestration
+import { EnigmaSwarmOrchestrator } from '../../packages/sdk/src/index.js';
+
+async function main() {
+  console.log('--- [Step 1] Initializing Swarm Orchestrator ---');
+  const swarm = new EnigmaSwarmOrchestrator({
+    swarmId: 'alpha_swarm_2026',
+    passphrase: 'swarm_master_passphrase',
+  });
+
+  // Listen to swarm-wide events
+  swarm.on('agent:registered', (evt) => {
+    console.log(`[EVENT] Registered Agent: ${evt.agentId} (Role: ${evt.role}, Scope: ${evt.scope})`);
+  });
+  swarm.on('signal:dispatched', (evt) => {
+    console.log(`[EVENT] Signal Dispatched: ${evt.senderAgentId} -> ${evt.targetAgentId} (Routed: ${evt.routed})`);
+  });
+
+  console.log('\n--- [Step 2] Spawning Autonomous Agent Team ---');
+  const coordinator = await swarm.registerAgent('coordinator_agent', {
+    role: 'coordinator',
+    permissions: ['read', 'write', 'broadcast'],
+  });
+  const trader = await swarm.registerAgent('solana_trader', {
+    role: 'trader',
+    permissions: ['read', 'write'],
+  });
+  const auditor = await swarm.registerAgent('security_auditor', {
+    role: 'auditor',
+    permissions: ['read'],
+  });
+
+  console.log('\nSwarm Topology:');
+  console.log(JSON.stringify(swarm.getTopology(), null, 2));
+
+  console.log('\n--- [Step 3] Synchronizing Swarm-Wide Protocol Rules ---');
+  await swarm.syncGlobalRule('Swarm Consensus Rule 1: Always verify zero-knowledge proofs before state transition');
+  console.log('✓ Rule synchronized across all swarm agents with write permissions');
+
+  console.log('\n--- [Step 4] Dispatching Encrypted Coordination Signals ---');
+  await swarm.dispatchSignal(
+    'coordinator_agent',
+    'solana_trader',
+    'DISPATCH_ORDER: Execute 15 SOL buy on Raydium with max 0.25% slippage'
+  );
+
+  console.log('\n--- [Step 5] Recalling Swarm Knowledge from Trader Agent ---');
+  const traderRecall = await trader.recall('Swarm Consensus Rule');
+  console.log(`Trader recalled ${traderRecall.length} global consensus rules:`);
+  traderRecall.forEach(r => console.log(`  - [${r.scope}] ${r.text}`));
+
+  console.log('\n--- [Step 6] Shutting Down Swarm ---');
+  await swarm.shutdown();
+  console.log('✓ Swarm shutdown complete!');
+}
+
+main().catch(console.error);

package/examples/02_cross_model_passport.mjs

@@ -0,0 +1,64 @@
+/**
+ * Example 02: Cross-Model Memory Passport
+ * Demonstrates creating a portable passport bundle and compiling
+ * scoped context packs for downstream AI model injection.
+ */
+
+import { createVault, remember } from '../packages/vault/src/index.js';
+import { createPassport, compileContextPack } from '../packages/passport/src/index.js';
+
+console.log('=== Enigma Cross-Model Memory Passport ===\n');
+
+// 1. Setup vault with cross-domain knowledge
+const vault = createVault({
+  subject_id: 'developer_101',
+  policy_id: 'cross_model_passport_v1',
+});
+
+await remember({
+  vault,
+  text: 'Always write TypeScript with strict types and zero any.',
+  tags: ['typescript', 'coding_standards'],
+  importance: 1.0,
+});
+
+await remember({
+  vault,
+  text: 'Production API endpoints use rate limiting of 100 req/min per IP.',
+  tags: ['api', 'architecture', 'security'],
+  importance: 0.85,
+});
+
+// 2. Create standardized Memory Passport
+const passport = createPassport({
+  vault,
+  passport_id: 'passport_dev_101',
+  owner: {
+    subject_id: 'developer_101',
+    display_name: 'Lead AI Engineer',
+  },
+});
+
+console.log('1. Generated Standard Memory Passport:');
+console.log('   - Schema:          ', passport.schema);
+console.log('   - Passport ID:     ', passport.passport_id);
+console.log('   - Owner Subject:   ', passport.owner.subject_id);
+console.log('   - Active Set Root: ', passport.vault.active_set_root.slice(0, 32) + '...');
+console.log('   - Active Addresses:', passport.active_memory_addresses.length, 'atoms\n');
+
+// 3. Compile scoped context pack for model consumption
+const contextPack = await compileContextPack({
+  vault,
+  passport,
+  query: 'TypeScript guidelines',
+  purpose: 'code_generation_prompt',
+  max_estimated_tokens: 500,
+});
+
+console.log('2. Compiled Scoped Context Pack:');
+console.log('   - Context Pack ID:  ', contextPack.context_pack_id);
+console.log('   - Memories included:', contextPack.memories.length);
+console.log('   - Model Target:     ', contextPack.model);
+console.log('   - Active Set Root:  ', contextPack.active_set_root.slice(0, 32) + '...');
+
+console.log('\n✔ Successfully created portable passport and compiled scoped context pack!');

package/examples/03-langchain-memory/index.mjs

@@ -0,0 +1,41 @@
+// Example 3: LangChain Sovereign Memory Integration
+import { Enigma, EnigmaLangChainMemory } from '../../packages/sdk/src/index.js';
+
+async function main() {
+  console.log('--- [Step 1] Connecting Enigma Agent Instance ---');
+  const enigma = await Enigma.connect({
+    scope: 'langchain.assistant',
+    passphrase: 'langchain_demo_passphrase',
+  });
+
+  // Pre-seed agent with domain knowledge
+  await enigma.remember('System Guidelines: The assistant always answers in concise technical bullet points.');
+  await enigma.remember('User Preference: The user prefers TypeScript over Python for smart contract bridges.');
+
+  console.log('\n--- [Step 2] Initializing EnigmaLangChainMemory Adapter ---');
+  const memory = new EnigmaLangChainMemory({
+    enigma,
+    memoryKey: 'chat_history',
+    maxTokens: 1000,
+  });
+
+  console.log('\n--- [Step 3] Loading Memory Variables for Incoming Prompt ---');
+  const memoryVars = await memory.loadMemoryVariables({
+    input: 'What language should we use for our contract bridge?',
+  });
+  console.log('Loaded Context for LLM System Prompt:\n', memoryVars.chat_history);
+
+  console.log('\n--- [Step 4] Saving Conversational Dialogue Turn ---');
+  await memory.saveContext(
+    { input: 'What language should we use for our contract bridge?' },
+    { output: 'We should use TypeScript based on your configured project preference.' }
+  );
+  console.log('✓ Dialogue turn saved to sovereign encrypted memory');
+
+  console.log('\n--- [Step 5] Recalling Conversation History ---');
+  const recallResults = await enigma.recall('contract bridge language preference');
+  console.log('Recall Results:');
+  recallResults.forEach(r => console.log(`  [${r.score * 100}% match]: ${r.text}`));
+}
+
+main().catch(console.error);

package/examples/03_poseidon_commitment_verification.mjs

@@ -0,0 +1,71 @@
+/**
+ * Example 03: Poseidon Commitment & Enclave Zeroization
+ * Demonstrates canonical Circomlib Poseidon hashing, generating algebraic
+ * commitments, zeroizing keys in hardware enclave simulation, and verifying attestations.
+ */
+
+import {
+  poseidon,
+  createPoseidonCommitment,
+  verifyPoseidonCommitment,
+  SimulatedEnclaveProvider,
+  AttestationVerifier,
+} from '../packages/vault/src/index.js';
+
+console.log('=== Enigma Poseidon & Enclave Zeroization ===\n');
+
+// 1. Canonical Circomlib Poseidon Hash
+const input1 = 1n;
+const input2 = 2n;
+const hashOutput = poseidon([input1, input2]);
+
+console.log('1. Canonical Poseidon Hash for [1, 2]:');
+console.log('   - Output BigInt:', hashOutput.toString());
+console.log('   - Output Hex:   ', '0x' + hashOutput.toString(16));
+console.log('   - Circomlib Match:', hashOutput.toString(16) === '115cc0f5e7d690413df64c6b9662e9cf2a3617f2743245519e19607a4417189a', '\n');
+
+// 2. Algebraic Commitment
+const recordKey = '0x4a81f3e9c2049182393278913988636902269926943896585145788461521946';
+const { commitment, salt } = createPoseidonCommitment(recordKey);
+
+console.log('2. Generated Algebraic Poseidon Commitment:');
+console.log('   - Commitment C:', commitment);
+console.log('   - Salt (CSPRNG):', salt);
+console.log('   - Verified:     ', verifyPoseidonCommitment(commitment, recordKey, salt), '\n');
+
+// 3. Hardware Enclave Key Zeroization
+const enclave = new SimulatedEnclaveProvider({ simulationLabel: 'enigma_example' });
+const secretRecord = await enclave.createRecord('CONFIDENTIAL_HEALTH_DATA_123', { tag: 'biomed' });
+
+console.log('3. Stored Encrypted Record in Enclave:');
+console.log('   - Record ID:   ', secretRecord.recordId);
+console.log('   - Commitment:  ', secretRecord.commitment);
+console.log('   - Ciphertext:  ', secretRecord.ciphertext.slice(0, 32) + '...\n');
+
+// Decrypt while active
+const decrypted = await enclave.decryptRecord(
+  secretRecord.recordId,
+  secretRecord.ciphertext,
+  secretRecord.iv,
+  secretRecord.authTag
+);
+console.log('4. Decrypted while active:', decrypted);
+
+// Zeroize key in memory
+const attestation = await enclave.zeroizeRecord(secretRecord.recordId);
+console.log('5. Zeroized key in enclave:');
+console.log('   - Action:        ', attestation.payload.action);
+console.log('   - Nullifier Hash:', attestation.payload.nullifierHash);
+console.log('   - Signed Quote:  ', attestation.signature.slice(0, 32) + '...\n');
+
+// Verify attestation
+const verifyResult = AttestationVerifier.verify(attestation, {
+  allowSimulated: true,
+  allowlistedSimulatedKeyPem: enclave.publicKeyPem,
+});
+
+console.log('6. Verified Deletion Attestation:');
+console.log('   - Valid:         ', verifyResult.valid);
+console.log('   - Nullifier Hash:', verifyResult.nullifierHash);
+
+console.log('\n✔ All Poseidon commitments and enclave zeroizations verified successfully!');

package/examples/04-python-trading-agent/trader.py

@@ -0,0 +1,49 @@
+"""
+Example 4: Python Autonomous Solana Trading Agent with Enigma Sovereign Memory
+"""
+import sys
+import os
+from enigma_sdk import EnigmaPythonSDK
+
+def main():
+    print("--- [Step 1] Connecting Python Trading Agent to Sovereign Vault ---")
+    vault_file = os.path.abspath("./trader_vault.enc.json")
+    passphrase = "trader_secret_passphrase_2026"
+
+    trader = EnigmaPythonSDK.connect(
+        scope="agent.solana_arb",
+        storage_path=vault_file,
+        passphrase=passphrase
+    )
+    print(f"✓ Connected Python Agent: {trader.status()}")
+
+    print("\n--- [Step 2] Storing Trading Execution Rules in Encrypted Vault ---")
+    trader.remember("Arbitrage Directive: Minimum profit threshold is 18 bps net of priority fees", importance=1.0)
+    trader.remember("Execution Rule: Route DEX swaps via Jupiter aggregator to minimize price impact", importance=0.9)
+    trader.remember("Risk Limit: Maximum daily portfolio exposure is capped at 50 SOL", importance=1.0)
+    print(f"✓ Stored {len(trader._local_memories)} memory atoms encrypted at rest")
+
+    print("\n--- [Step 3] Recalling Trading Directives Before Execution ---")
+    query = "What is our minimum profit threshold for arbitrage swaps?"
+    print(f"Query: '{query}'")
+    results = trader.recall(query, top_k=2)
+    for idx, r in enumerate(results):
+        print(f"  [Match #{idx + 1}] (Score: {r['score']}) [{r['scope']}]: {r['text']}")
+
+    print("\n--- [Step 4] Simulating Agent Restart ---")
+    trader_restart = EnigmaPythonSDK.connect(
+        scope="agent.solana_arb",
+        storage_path=vault_file,
+        passphrase=passphrase
+    )
+    recalled_after_restart = trader_restart.recall("portfolio exposure limits", top_k=1)
+    if recalled_after_restart:
+        print(f"✓ Successfully recalled across session restart: {recalled_after_restart[0]['text']}")
+
+    # Cleanup demo file
+    if os.path.exists(vault_file):
+        os.remove(vault_file)
+    print("✓ Python Trader Example completed successfully!")
+
+if __name__ == "__main__":
+    main()

package/examples/README.md

@@ -0,0 +1,27 @@
+# Enigma Sovereign AI Memory — Developer Examples
+
+Runnable developer examples demonstrating the **Enigma Sovereign AI Memory Architecture**, including TypeScript SDK, Python client, Multi-Agent Swarms, and LangChain memory adapters.
+
+---
+
+### Examples Directory
+
+1. **`01-quickstart-agent`**: 3-line quickstart connecting an autonomous agent, storing encrypted directives, performing vector recall, and compiling token-budgeted prompt context.
+   ```bash
+   node examples/01-quickstart-agent/index.mjs
+   ```
+
+2. **`02-multi-agent-swarm`**: Multi-agent team orchestration using `EnigmaSwarmOrchestrator` with Role-Based Access Control (RBAC), global rule consensus, and encrypted GhostMesh signal dispatching.
+   ```bash
+   node examples/02-multi-agent-swarm/index.mjs
+   ```
+
+3. **`03-langchain-memory`**: Using `EnigmaLangChainMemory` to connect LangChain conversational chains directly to sovereign encrypted custody.
+   ```bash
+   node examples/03-langchain-memory/index.mjs
+   ```
+
+4. **`04-python-trading-agent`**: Python autonomous trading agent remembering on-chain liquidity constraints and risk parameters with AES-256-GCM encrypted persistence.
+   ```bash
+   PYTHONPATH=packages/sdk/python python examples/04-python-trading-agent/trader.py
+   ```

package/examples/ci/github-actions.yml

@@ -21,6 +21,9 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
+    env:
+      # Deterministic, disposable CI-only credential; never reuse for real data.
+      ENIGMA_PASSPHRASE: enigma-ci-test-only-not-for-real-data
     steps:
       - name: Set up Node 24
         uses: actions/setup-node@v4
@@ -46,8 +49,10 @@ jobs:
 
       - name: Run public installer smoke path
         run: |
-          npx enigma test-drive --dry-run
-          npx enigma setup --overwrite
+          PASSPHRASE_FILE="$RUNNER_TEMP/enigma-ci-passphrase"
+          (umask 077; printf '%s\n' "$ENIGMA_PASSPHRASE" > "$PASSPHRASE_FILE")
+          npx enigma test-drive --dry-run --passphrase-file "$PASSPHRASE_FILE"
+          npx enigma setup --passphrase-file "$PASSPHRASE_FILE" --overwrite
           npx enigma doctor
           echo "Next client-connect preview: npx enigma connect <client> --dry-run"