enigma-memory 0.1.17 → 0.1.22

package/packages/adapters/PACKAGE_CONTRACT.md

@@ -1,6 +1,6 @@
 # Production dependency adapters contract
 
-`@enigma-ai/enigma/adapters` is a pure local evidence-normalization package. It does not provision cloud resources, open sockets, read environment variables, or load secrets.
+`enigma-memory/adapters` is a pure local evidence-normalization package. It does not provision cloud resources, open sockets, read environment variables, or load secrets.
 
 ## Purpose
 

package/packages/connectors/src/index.js

@@ -1,12 +1,14 @@
 import { access, copyFile, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { dirname, posix, win32 } from 'node:path';
 import { homedir } from 'node:os';
+import { canonicalize, MerkleSet, sha256Hex } from '../../core/src/index.js';
 
 const PROFILE_SCHEMA = 'enigma.connector_profile.v1';
 const DEFAULT_SERVER_NAME = 'enigma';
 const MCP_COMMAND = 'enigma-mcp';
 const MCP_CONTAINER_PATH = Object.freeze(['mcpServers']);
 const SUPPORTED_PLATFORMS = Object.freeze(['win32', 'darwin', 'linux']);
+const TRUST_CARD_SCHEMA = 'enigma.trust_card.v1';
 
 const CLIENT_DEFINITIONS = Object.freeze({
   'claude-desktop': Object.freeze({
@@ -36,6 +38,15 @@ const CLIENT_DEFINITIONS = Object.freeze({
       linux: '$HOME/.config/kimi-code/mcp.json',
     }),
   }),
+  'kimi-k3': Object.freeze({
+    display_name: 'Kimi K3',
+    description: 'Kimi K3 Autonomous AI MCP configuration.',
+    default_config_paths: Object.freeze({
+      win32: '%APPDATA%\\Kimi K3\\mcp.json',
+      darwin: '$HOME/Library/Application Support/Kimi K3/mcp.json',
+      linux: '$HOME/.config/kimi-k3/mcp.json',
+    }),
+  }),
   'vscode-cline': Object.freeze({
     display_name: 'VS Code Cline',
     description: 'Cline extension MCP settings for VS Code.',
@@ -74,6 +85,74 @@ const CLIENT_DEFINITIONS = Object.freeze({
   }),
 });
 
+const CONNECTOR_CAPABILITY_DEFINITIONS = Object.freeze({
+  'claude-desktop': Object.freeze({
+    integration_kind: 'mcp_client',
+    client_surface: 'claude_desktop',
+    transport: 'mcp_stdio',
+    mcp_tools: true,
+    browser_context_bridge: false,
+    offline_export_import: false,
+  }),
+  cursor: Object.freeze({
+    integration_kind: 'mcp_client',
+    client_surface: 'cursor_editor',
+    transport: 'mcp_stdio',
+    mcp_tools: true,
+    browser_context_bridge: false,
+    offline_export_import: false,
+  }),
+  'browser-extension': Object.freeze({
+    integration_kind: 'browser_context_bridge',
+    client_surface: 'supported_web_ai_pages',
+    transport: 'browser_native_messaging',
+    mcp_tools: false,
+    browser_context_bridge: true,
+    offline_export_import: false,
+  }),
+  'chatgpt-import': Object.freeze({
+    integration_kind: 'offline_export_import',
+    client_surface: 'chatgpt_user_export',
+    transport: 'local_file',
+    mcp_tools: false,
+    browser_context_bridge: false,
+    offline_export_import: true,
+  }),
+  'generic-mcp': Object.freeze({
+    integration_kind: 'mcp_client',
+    client_surface: 'generic_local_model_or_mcp_client',
+    transport: 'mcp_stdio',
+    mcp_tools: true,
+    browser_context_bridge: false,
+    offline_export_import: false,
+  }),
+});
+
+export const connectorCapabilityIds = Object.freeze(Object.keys(CONNECTOR_CAPABILITY_DEFINITIONS));
+
+export function getConnectorCapabilityDescriptor(capabilityId) {
+  const id = String(capabilityId ?? '').trim().toLowerCase();
+  const explicit = CONNECTOR_CAPABILITY_DEFINITIONS[id];
+  const definition = explicit ?? (Object.hasOwn(CLIENT_DEFINITIONS, id)
+    ? {
+        ...CONNECTOR_CAPABILITY_DEFINITIONS['generic-mcp'],
+        client_surface: id,
+      }
+    : undefined);
+  if (!definition) throw new Error(`Unknown connector capability id: ${id || '(empty)'}`);
+  return Object.freeze({
+    schema: 'enigma.connector_capability.v1',
+    capability_id: id,
+    ...definition,
+    native_provider_integration: false,
+    provider_api_access: false,
+    provider_memory_read: false,
+    provider_memory_write: false,
+    provider_memory_delete: false,
+    canonical_storage: 'enigma_local_vault',
+  });
+}
+
 export const supportedClients = Object.freeze(Object.keys(CLIENT_DEFINITIONS));
 
 function isPlainObject(value) {
@@ -187,6 +266,10 @@ function defaultConfigPathFor(clientId, platform, options = {}) {
       return joinForPlatform(platform, appData, 'Claude', 'claude_desktop_config.json');
     case 'cursor':
       return joinForPlatform(platform, home, '.cursor', 'mcp.json');
+    case 'kimi-k3':
+      return platform === 'linux'
+        ? joinForPlatform(platform, appData, 'kimi-k3', 'mcp.json')
+        : joinForPlatform(platform, appData, 'Kimi K3', 'mcp.json');
     case 'kimi-code':
       return platform === 'linux'
         ? joinForPlatform(platform, appData, 'kimi-code', 'mcp.json')
@@ -231,6 +314,7 @@ export function getClientProfile(clientIdOrOptions = 'generic-mcp', maybeOptions
     server_name: DEFAULT_SERVER_NAME,
     command: MCP_COMMAND,
     required_env: Object.freeze(['ENIGMA_BUNDLE']),
+    capabilities: getConnectorCapabilityDescriptor(clientId),
     platform,
   });
 }
@@ -557,6 +641,10 @@ function redactErrorMessage(message, configPath, options = {}) {
 function publicBundlePlaceholder(platform) {
   return platform === 'win32' ? '%USERPROFILE%\\.enigma\\bundle.json' : '$HOME/.enigma/bundle.json';
 }
+function publicPassphrasePlaceholder(platform) {
+  return platform === 'win32' ? '%USERPROFILE%\\.enigma\\passphrase' : '$HOME/.enigma/passphrase';
+}
+
 
 function publicDefaultConfigPath(clientId, platform) {
   return CLIENT_DEFINITIONS[clientId].default_config_paths[platform];
@@ -567,7 +655,7 @@ function connectCommandFor(clientId, platform) {
 }
 
 function setupConnectCommandFor(clientId, platform) {
-  return `enigma setup --client ${clientId} --write-connectors --bundle "${publicBundlePlaceholder(platform)}" --overwrite`;
+  return `enigma setup --client ${clientId} --write-connectors --bundle "${publicBundlePlaceholder(platform)}" --passphrase-file "${publicPassphrasePlaceholder(platform)}" --overwrite`;
 }
 
 function installConnectCommandFor(clientId, platform) {
@@ -589,7 +677,7 @@ function wizardStepsForClient(clientId, platform) {
       id: 'create_local_bundle',
       title: 'Create and verify the local Enigma bundle.',
       commands: [
-        `enigma quickstart --bundle "${publicBundlePlaceholder(platform)}" --overwrite`,
+        `enigma quickstart --bundle "${publicBundlePlaceholder(platform)}" --passphrase-file "${publicPassphrasePlaceholder(platform)}" --overwrite`,
         `enigma verify --bundle "${publicBundlePlaceholder(platform)}"`,
       ],
       writes: 'local_enigma_bundle',
@@ -615,11 +703,11 @@ function wizardStepsForClient(clientId, platform) {
       writes: false,
     },
   ];
-  if (clientId === 'kimi-code') {
+  if (clientId === 'kimi-k3' || clientId === 'kimi-code') {
     steps.splice(4, 0, {
       order: 5,
       id: 'kimi_gui_path_caveat',
-      title: 'If Kimi Code was launched from the GUI and cannot find enigma-mcp, reconnect with an absolute command path.',
+      title: 'If Kimi K3 / Kimi Code was launched from the GUI and cannot find enigma-mcp, reconnect with an absolute command path.',
       command: `${connectCommandFor(clientId, platform)} --mcp-command "/absolute/path/to/enigma-mcp"`,
       writes: 'client_config_when_user_runs_command',
     });
@@ -726,6 +814,110 @@ export async function doctorConnectors(clientIdOrOptions = {}, maybeOptions = {}
   return detectConnectors(clientIdOrOptions, maybeOptions);
 }
 
+function sha256Root(value) {
+  return `sha256:${sha256Hex(typeof value === 'string' ? value : canonicalize(value))}`;
+}
+
+function publicTrustRef(kind, value) {
+  return `ref:${kind}:${sha256Hex(typeof value === 'string' ? value : canonicalize(value)).slice(0, 32)}`;
+}
+
+function uniqueSortedStrings(values) {
+  return [...new Set(values.map(String).filter((value) => value.length > 0))].sort();
+}
+
+function connectorTrustBoundary() {
+  return {
+    public_payload_only: true,
+    raw_memory_included: false,
+    raw_prompt_included: false,
+    raw_transcript_included: false,
+    raw_embedding_included: false,
+    private_key_included: false,
+    credential_included: false,
+    local_path_included: false,
+    provider_deletion_claim: false,
+    model_forgetting_claim: false,
+    hosted_saas_ready_claim: false,
+  };
+}
+
+function connectorTrustEvidenceRefs(clientId, profile) {
+  return uniqueSortedStrings([
+    publicTrustRef('connector_profile', {
+      schema: PROFILE_SCHEMA,
+      client_id: clientId,
+      display_name: profile.display_name,
+      command: profile.command,
+      server_name: profile.server_name,
+      server_container_path: profile.server_container_path,
+    }),
+    publicTrustRef('mcp_command', {
+      command: profile.command,
+      server_name: profile.server_name,
+    }),
+  ]);
+}
+
+export function createConnectorTrustCard(clientIdOrOptions = 'generic-mcp', maybeOptions = {}) {
+  const options = normalizeOptions(clientIdOrOptions, maybeOptions);
+  const clientId = normalizeClientId(options.clientId ?? options.client_id ?? 'generic-mcp');
+  const profile = getClientProfile(clientId, options);
+  const generatedAt = String(options.generated_at ?? options.generatedAt ?? options.now ?? new Date().toISOString());
+  const evidenceRefs = connectorTrustEvidenceRefs(clientId, profile);
+  const claims = [
+    {
+      claim_id: 'claim:connector.local_mcp_profile',
+      claim_type: PROFILE_SCHEMA,
+      status: 'supported',
+      evidence_refs: [evidenceRefs[0]],
+    },
+    {
+      claim_id: 'claim:connector.public_payload_only',
+      claim_type: 'enigma.trust_boundary.v1',
+      status: 'supported',
+      evidence_refs: [evidenceRefs[1]],
+    },
+  ];
+  const claimIds = claims.map((claim) => claim.claim_id);
+  return {
+    schema: TRUST_CARD_SCHEMA,
+    trust_card_id: `trustcard:connector:${clientId}`,
+    generated_at: generatedAt,
+    subject: {
+      subject_type: 'connector',
+      subject_id: `connector:${clientId}`,
+      subject_ref: `ref:connector:${clientId}`,
+      subject_hash: sha256Root({
+        schema: 'enigma.connector_trust_subject.v1',
+        client_id: clientId,
+        command: profile.command,
+        server_name: profile.server_name,
+      }),
+    },
+    posture: options.posture ?? 'reviewed',
+    claim_ids: claimIds,
+    claims,
+    evidence_refs: evidenceRefs,
+    roots: {
+      claim_root: new MerkleSet(claimIds).root(),
+      evidence_root: new MerkleSet(evidenceRefs).root(),
+      receipt_chain_root: options.receipt_chain_root ?? options.receiptChainRoot ?? sha256Root({
+        schema: 'enigma.connector_trust_card.empty_receipt_chain.v1',
+        client_id: clientId,
+      }),
+    },
+    boundary: connectorTrustBoundary(),
+  };
+}
+
+export function createConnectorTrustCards(options = {}) {
+  const selected = options.clientId ?? options.client_id
+    ? [normalizeClientId(options.clientId ?? options.client_id)]
+    : supportedClients;
+  return selected.map((clientId) => createConnectorTrustCard({ ...options, clientId }));
+}
+
 export function runConnectorDemo(input = {}) {
   const options = { ...input, clientId: input.clientId ?? input.client_id ?? 'generic-mcp' };
   const clientId = normalizeClientId(options.clientId);

package/packages/connectors/swarm-router.mjs

@@ -0,0 +1,168 @@
+import { access, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import {
+  createSwarmBridge,
+  projectSwarmCommitmentAtom,
+  SWARM_PERMISSIONS,
+  validateSwarmCommitmentAtom,
+} from '../mcp-server/swarm-bridge.mjs';
+
+const pathQueues = new Map();
+
+async function exists(path) {
+  try { await access(path); return true; } catch { return false; }
+}
+
+function statePathFor(bundlePath) {
+  return `${resolve(bundlePath)}.swarm.json`;
+}
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, 'utf8'));
+}
+
+async function writeJsonAtomic(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  await rename(temporary, path);
+}
+
+function persistenceSafeState(bridge) {
+  const state = bridge.exportState();
+  for (const atoms of Object.values(state.namespaces)) {
+    for (let index = 0; index < atoms.length; index += 1) {
+      atoms[index] = projectSwarmCommitmentAtom(atoms[index]);
+    }
+  }
+  return state;
+}
+
+function enqueue(path, operation) {
+  const prior = pathQueues.get(path) ?? Promise.resolve();
+  const current = prior.catch(() => {}).then(operation);
+  pathQueues.set(path, current);
+  return current.finally(() => { if (pathQueues.get(path) === current) pathQueues.delete(path); });
+}
+
+async function loadBridge(bundlePath, requestedSwarmId) {
+  const statePath = statePathFor(bundlePath);
+  if (await exists(statePath)) {
+    const state = await readJson(statePath);
+    if (state.schema !== 'enigma.swarm_bridge_state.v1') throw new Error(`unsupported swarm state schema: ${state.schema ?? '<missing>'}`);
+    for (const atoms of Object.values(state.namespaces ?? {})) {
+      if (!Array.isArray(atoms)) throw new Error('persisted swarm namespace must contain an atom array');
+      atoms.forEach(validateSwarmCommitmentAtom);
+    }
+    if (requestedSwarmId && requestedSwarmId !== state.swarm_id) throw new Error('swarm domain does not match persisted bundle swarm');
+    return { bridge: createSwarmBridge(state), statePath };
+  }
+  return { bridge: createSwarmBridge(requestedSwarmId ? { swarm_id: requestedSwarmId } : {}), statePath };
+}
+
+async function bundleAtoms(bundlePath) {
+  if (!(await exists(resolve(bundlePath)))) return [];
+  const bundle = await readJson(resolve(bundlePath));
+  if (bundle.schema !== 'enigma.vault_bundle.v1') throw new Error(`unsupported Enigma bundle schema: ${bundle.schema ?? '<missing>'}`);
+  const active = new Set(Array.isArray(bundle.active_memory_addresses) ? bundle.active_memory_addresses : []);
+  return (Array.isArray(bundle.memory_objects) ? bundle.memory_objects : []).filter((atom) => active.has(atom.memory_addr));
+}
+
+async function runPersisted(bundlePath, swarmId, operation) {
+  const statePath = statePathFor(bundlePath);
+  return enqueue(statePath, async () => {
+    const loaded = await loadBridge(bundlePath, swarmId);
+    const result = await operation(loaded.bridge);
+    await writeJsonAtomic(loaded.statePath, persistenceSafeState(loaded.bridge));
+    return result;
+  });
+}
+
+function hydrateSuppliedAtoms(bridge, input, permission) {
+  const atoms = input.atoms ?? input.memories;
+  if (!Array.isArray(atoms) || atoms.length === 0) return;
+  const { namespace } = bridge.requireAgent(input.agent_id, permission, input.namespace);
+  bridge.hydrateCanonicalMemories(namespace, atoms);
+}
+
+export async function enigma_swarm_register_agent(input = {}) {
+  const bundlePath = input.bundlePath ?? input.bundle_path ?? '.enigma/bundle.json';
+  return runPersisted(bundlePath, input.swarm_id ?? input.swarmId, (bridge) => ({
+    ok: true,
+    agent: bridge.registerAgent(input),
+    status: bridge.status(),
+  }));
+}
+
+export async function enigma_graph_query(input = {}) {
+  const bundlePath = input.bundlePath ?? input.bundle_path ?? '.enigma/bundle.json';
+  return runPersisted(bundlePath, input.swarm_id ?? input.swarmId, (bridge) => {
+    hydrateSuppliedAtoms(bridge, input, SWARM_PERMISSIONS.GRAPH);
+    return bridge.graphQuery(input);
+  });
+}
+
+export const enigma_graph_search = enigma_graph_query;
+
+export async function enigma_cluster_memories(input = {}) {
+  const bundlePath = input.bundlePath ?? input.bundle_path ?? '.enigma/bundle.json';
+  return runPersisted(bundlePath, input.swarm_id ?? input.swarmId, (bridge) => {
+    hydrateSuppliedAtoms(bridge, input, SWARM_PERMISSIONS.CLUSTER);
+    return bridge.clusterMemories(input);
+  });
+}
+
+export async function enigma_swarm_sync(input = {}) {
+  const bundlePath = input.bundlePath ?? input.bundle_path ?? '.enigma/bundle.json';
+  return runPersisted(bundlePath, input.swarm_id ?? input.swarmId, (bridge) => {
+    hydrateSuppliedAtoms(bridge, input, SWARM_PERMISSIONS.SYNC);
+    if (input.snapshot ?? input.peer_snapshot ?? input.peerSnapshot) return bridge.sync(input);
+    return bridge.createSnapshot(input);
+  });
+}
+
+export async function routeSwarmTool(name, input = {}) {
+  const handlers = { enigma_swarm_register_agent, enigma_graph_query, enigma_graph_search, enigma_cluster_memories, enigma_swarm_sync };
+  const handler = handlers[name];
+  if (!handler) throw new Error(`unknown swarm tool: ${name}`);
+  return handler(input);
+}
+
+export async function swarmStatusFromBundle(bundlePath = '.enigma/bundle.json') {
+  const resolved = resolve(bundlePath);
+  const { bridge } = await loadBridge(resolved);
+  const status = bridge.status();
+  const atoms = await bundleAtoms(resolved);
+  return {
+    ...status,
+    bundle: resolved,
+    active_bundle_memory_count: atoms.length,
+    state_path: statePathFor(resolved),
+    claim_boundaries: {
+      local_simulator_only: true,
+      network_transmission: false,
+      decentralized_network_claim: false,
+      raw_memory_replicated_by_default: false,
+    },
+  };
+}
+
+export async function swarmGraphFromBundle(bundlePath = '.enigma/bundle.json') {
+  const resolved = resolve(bundlePath);
+  const loaded = await loadBridge(resolved);
+  const bridge = loaded.bridge;
+  const atoms = await bundleAtoms(resolved);
+  const inspectorId = '__enigma_cli_swarm_inspector__';
+  const namespace = '__enigma_bundle_active_set__';
+  bridge.registerAgent({ agent_id: inspectorId, namespace, permission_mask: SWARM_PERMISSIONS.ADMIN });
+  if (atoms.length > 0) bridge.ingestMemories({ agent_id: inspectorId, namespace, atoms });
+  const query = bridge.graphQuery({ agent_id: inspectorId, namespace, max_depth: 12, limit: 500 });
+  return {
+    ...query,
+    bundle: resolved,
+    active_bundle_memory_count: atoms.length,
+    content_redacted: true,
+    local_only: true,
+    network_transmission: false,
+  };
+}