API reference

This reference lists the public surfaces currently exposed by the enigma-memory package and source checkout. It is intentionally boundary-aware:

• Stable local/package surfaces are declared in package.json bin or exports, run locally, and do not require hosted Enigma cloud.
• Demo/source-only surfaces are useful for review, local demos, or source checkout operation, but are not evidence of a hosted production service.
• Hosted/BYOC deployment is waitlist/operator-deploy only. The relay and gateway binaries included in the package are local bootstrap probes, not a live hosted service. Production hosted/BYOC operation requires deployment credentials, domain/TLS, production durable storage, KMS/secrets, monitoring, backups, incident response, and SIEM/log routing. Local file-backed demo state does not satisfy hosted/BYOC durability.

Enigma proofs cover Enigma-controlled or Enigma-mediated vault state, receipts, checkpoints, relay records, gateway decisions, and documented boundary operations. They do not prove provider-side deletion, provider model forgetting, token ROI, compliance status, tamper-proof hardware, or raw compute superiority.

Package entry points

Import from the package root or explicit subpath after installing the source checkout or the published package:

import { createVault, remember, exportBundle } from 'enigma-memory/vault';
import { verifyReceiptChain } from 'enigma-memory/core';

The verifier's verifyBundle(bundle) helper is implemented in the enigma-verify bin source; package consumers should prefer the enigma-verify bin, enigma verify, or the MCP enigma_verify_receipts tool unless working from a source checkout.

Use package subpath exports for public module imports:

./relay, ./gateway, and ./desktop expose local modules and demos. Running them locally does not make hosted Enigma cloud or a customer BYOC deployment live.

Module API quick reference

Use object-style arguments for forward compatibility where supported by the implementation. Functions that accept private memory text (remember, updateMemory, enigma_remember, and matching CLI commands) should receive it only from local/private inputs; public proof artifacts should contain addresses, hashes, roots, receipt ids, counts, encrypted envelopes, or commitments instead.

Core (enigma-memory/core)

Vault and passport (enigma-memory/vault, enigma-memory/passport)

Boundary, mesh, and enterprise

Desktop scaffold (enigma-memory/desktop)

The desktop export is a state/model scaffold. createDesktopState, desktopReducer, and renderDesktopModel drive state and view models. Action creators return reducer actions: startMcp, stopMcp, createVault, rememberMemory, deleteMemory, searchMemories, verifyReceipts, connectClient, disconnectClient, importBundle, exportBundle, updateMeshStatus, updateEnterpriseStatus, selectDesktopScreen, and setDesktopDraft. Aliases (startMCP, stopMCP, remember, removeMemory, searchMemory, verifyReceiptOutput, connectDesktopClient, importDesktopBundle, exportDesktopBundle) are also exported. desktopActions, actions, and desktopApi group the same functions. Desktop output is operational UI evidence only, not cryptographic proof.

CLI bins and commands

Package bins declared in package.json:

enigma command names:

• enigma init
• enigma doctor
• enigma install
• enigma connect <client>
• enigma disconnect <client>
• enigma remember
• enigma recall
• enigma update
• enigma delete
• enigma context
• enigma export
• enigma import <source>
• enigma capsule export
• enigma capsule import
• enigma verify
• enigma boundary run
• enigma mcp serve
• enigma relay demo
• enigma relay serve
• enigma gateway demo
• enigma gateway serve
• enigma mesh demo
• enigma enterprise demo

Common local options and outputs:

Importer source names accepted by enigma import <source>:

• chatgpt, chatgpt-export, chatgpt_export
• claude, claude-memory, claude_memory
• mem0, mem0-export, mem0_export
• letta, letta-agent, letta_agent, letta_agent_file
• langgraph, langgraph-store, langgraph_store
• zep, graphiti, zep-graphiti, zep_graphiti, zep_graphiti_export

enigma import <source> requires --file/--source-file/--path or a positional file, accepts --out and --now, and writes candidates into a local vault only when --write-vault --bundle <path> is supplied.

Capsule commands:

• enigma capsule export --file <import-report.json> --out <capsule.json> creates an enigma.import_capsule.v1 object with public verifier metadata, public artifacts, and payload commitments.
• enigma capsule import --file <capsule.json> --bundle <bundle> verifies capsule metadata and may write candidates into a local vault only when --write-vault is supplied.

Direct service bins:

• enigma-verify <exported-bundle.json> prints an enigma.verification_report.v1 JSON report and exits 0 when ok is true, 1 when verification fails, and 2 on CLI errors.
• enigma-mcp starts the MCP server over stdio. Set ENIGMA_BUNDLE to the local bundle path or pass bundlePath in tool calls.
• enigma-relay [demo|serve] [--host <host>] [--port <port>] [--once] [--state-file <path>]; default direct-bin command is serve when no demo or serve subcommand is supplied. Default port is 8787.
• enigma-gateway [demo|serve] [--host <host>] [--port <port>] [--once] [--state-file <path>]; default direct-bin command is serve when no demo or serve subcommand is supplied. Default port is 8797.

MCP server surface

Transport: stdio JSON-RPC through enigma-mcp or enigma mcp serve. Protocol version advertised by the server is 2024-11-05; server info is enigma-mcp-server version 0.1.0.

Supported JSON-RPC methods are initialize, notifications/initialized, ping, tools/list, tools/call, resources/list, resources/templates/list, resources/read, prompts/list, and prompts/get. Unknown methods return JSON-RPC method-not-found errors; request ids must be strings/numbers/null matching the server's id validation.

Tools from toolDescriptors and handlers:

Resources:

Prompts:

Programmatic MCP helpers are available from enigma-memory/mcp-server: handleJsonRpcRequest(request) and startStdioServer(io).

Relay HTTP API

Module: enigma-memory/relay. Local bin: enigma-relay serve --host 127.0.0.1 --port 8787.

Programmatic relay API: createRelayState(options) creates relay state; createRelayServer(options) returns a Node HTTP server with server.relayState; handleRelayRequest(state, req, res) handles one Node HTTP request; serializeRelayState(state) and hydrateRelayState(snapshot) convert local state-file snapshots; loadRelayStateFromFile(path) and saveRelayStateToFile(state, path) load/save the optional file-backed demo state; runRelayDemo(options) returns a local demo result.

Status boundaries:

• Stable local/package: local relay server, demo, and module handlers. Without --state-file, service state is in-memory. With --state-file <path>, relay state is local file-backed demo state.
• Hosted/BYOC: same endpoints when deployed with real TLS, production durable storage, secrets/KMS, monitoring, backups, incident response, and tenant policy. Package install or local --state-file alone is not hosted availability.
• Relay accepts opaque encrypted records and root/checkpoint metadata. It rejects plaintext-looking memory fields such as memory bodies, prompts, transcripts, or raw conversation content.

Endpoints:

Authenticated relay clients sign this authorization payload with their paired key: { schema: 'enigma.relay_client_authorization.v1', relay_node_id, pairing_id, operation, request_hash }, then send headers x-enigma-pairing-id and x-enigma-client-signature.

Relay --state-file persistence stores only local demo state needed to resume relay operation, such as relay node signing/trust metadata, store metadata, hash-only/opaque relay records, witness checkpoints, completed pairings, authorization mode, and generation metadata. Treat relay signing material as a local demo secret. It does not store raw memory plaintext, prompts, transcripts, decrypted capsules, raw request bodies, or pending pairing challenges. Unknown, malformed, or plaintext-looking snapshots fail closed.

Gateway HTTP API

Module: enigma-memory/gateway. Local bin: enigma-gateway serve --host 127.0.0.1 --port 8797.

Programmatic gateway API: createGatewayState(options) creates gateway policy/SIEM state; createGatewayServer(options) returns a Node HTTP server with server.gatewayState; handleGatewayRequest(state, request, response?) handles one Node HTTP request or returns a response object; serializeGatewayState(state) and hydrateGatewayState(snapshot, options?) convert local state-file snapshots; loadGatewayStateFromFile(path, options?) and saveGatewayStateToFile(state, path) load/save the optional file-backed demo state; runGatewayDemo() returns a local demo result.

Status boundaries:

• Stable local/package: local gateway server, demo, and module handlers. Without --state-file, service state is in-memory. With --state-file <path>, gateway policy/SIEM state is local file-backed demo state.
• Hosted/BYOC: same endpoints when deployed with production credentials, TLS, production durable policy/storage, KMS/secrets, monitoring, backups, and SIEM/log routing. Local --state-file is not production database readiness.
• Gateway evaluates Enigma enterprise policy and emits plaintext-minimized decisions/SIEM events. It does not call model providers and does not prove provider deletion or model forgetting.

Endpoints:

Gateway requests must identify memory by committed address/id and metadata, not raw memory plaintext. enigma.gateway_request.v1 explicitly excludes plaintext-like fields such as memory, memory_text, memory_plaintext, plaintext, raw_memory, content, and value.

Gateway --state-file persistence stores only local demo state needed to resume gateway operation, such as gateway_id, active_root, active enterprise policy, demo Ed25519 public/private signing key material, plaintext-minimized siem_events, expose_internal, schema/version, and generation metadata. Treat gateway private signing material as a local demo secret. It does not store raw memory plaintext, prompts, completions, transcripts, provider response bodies, decrypted capsules, embeddings, tenant secrets, KMS material, or hidden-provider-state claims. Unknown, malformed, or plaintext-looking snapshots fail closed; allowDemoReset is the explicit demo reset option for helper callers.

Connector profiles

Module: enigma-memory/connectors. CLI: enigma install, enigma doctor, enigma connect <client>, enigma disconnect <client>.

Connector profiles render JSON under mcpServers, use server name enigma, command enigma-mcp, and require env key ENIGMA_BUNDLE.

connectClient and disconnectClient preserve unrelated JSON settings and sibling MCP servers. Existing configs are backed up only when a changed write is needed. Connector setup does not delete provider-native memory or make provider-native memory canonical.

Importer and capsule API

Module: enigma-memory/importers. These functions normalize local export files or parsed JSON; they do not call provider services.

Completeness is claimed only when the source explicitly asserts it and the importer preserves that evidence. A source export becomes canonical Enigma memory only after a candidate is written through a local vault and receives Enigma receipts. Public capsule verifier metadata contains hashes, roots, counts, report hashes, limitation roots, completeness summary, and trust descriptor; it must not expose raw memory plaintext.

Verifier outputs

Verifier APIs:

• CLI: enigma verify --bundle <exported-bundle.json> or enigma-verify <exported-bundle.json>.
• Module from verifier bin source: verifyBundle(bundle), readBundle(path), main(argv, io).
• MCP: enigma_verify_receipts calls the same verifier.

verifyBundle(bundle) returns:

{
  "ok": true,
  "schema": "enigma.verification_report.v1",
  "checked_at": "<ISO timestamp>",
  "receipt_count": 0,
  "checkpoint_count": 0,
  "errors": []
}

Error entries use { code, message, details? }. Known verifier error codes include BUNDLE_INVALID, RECEIPTS_MISSING, PUBLIC_KEY_MISSING, RECEIPT_CHAIN_INVALID, RECEIPT_INVALID, CHECKPOINT_INVALID, STALE_CHECKPOINT, COMMITTED_ROOT_MISMATCH, COMMITTED_SEQUENCE_MISMATCH, and VERIFY_CLI_ERROR.

Verifier success means the supplied Enigma bundle's receipts/checkpoints and committed roots verify against included or supplied Enigma public keys. It does not prove the truth of a memory statement, provider deletion, or model forgetting.

Schemas

Schemas are package-included under specs/ and are reviewable from a source checkout.

Demo/source-only surfaces

These are public review surfaces in the source checkout, not hosted production interfaces by themselves:

• docs/, including this file, install guide, deployment runbook, release checklist, and release evidence.
• Dockerfile and docker-compose.yml local relay/gateway demos.
• apps/browser-extension unpacked Manifest V3 scaffold and native messaging host name com.enigma.native_host. Source-only bridge module exports in apps/browser-extension/src/native-bridge.js are SUPPORTED_PROVIDERS, detectProviderFromUrl(url), requestContextPack(input), recordInsertionReceipt(input), and serializeError(error). Supported provider ids are chatgpt, claude, kimi, and perplexity. The extension requires explicit user action before requesting or inserting context and must not store raw memory in browser sync storage.
• Module demo helpers: runConnectorDemo, runImporterDemo, runMeshDemo, runEnterpriseDemo, runRelayDemo, runGatewayDemo, and runBoundarySimulation.
• apps/desktop/src/index.html static desktop scaffold; package export enigma-memory/desktop exposes its state/model API, but UI state remains operational evidence only.

Local file-backed state boundary

--state-file <path> is a practical local durability option for relay/gateway source or package demos. Use separate files for relay and gateway, keep them outside the repository, restrict permissions to the local user/service account, and encrypt any backup because snapshots can contain local demo signing key material. A state file can help a reviewer restart a laptop demo without losing relay records, pairings, witness checkpoints, gateway policy, or minimized SIEM evidence.

It is not a production storage API. It has no hosted durability SLA, multi-writer coordination, online migration contract, database isolation, KMS-backed secret custody, cross-region replication, tenant backup policy, legal hold workflow, monitoring, or disaster-recovery proof. Hosted and BYOC deployments still require real durable storage plus KMS/secrets and completed operator acceptance.

Hosted/BYOC deployment boundary

Hosted and BYOC deployments may expose the relay and gateway HTTP APIs above, but only after infrastructure acceptance is complete:

• Hosted: Enigma operator owns deployment credentials, domain/TLS, durable storage, KMS/secrets, monitoring, backups, incident response, tenant policy lifecycle, and SIEM/log routing.
• BYOC: the customer runs relay/gateway in its own cloud, VPC, cluster, or private network and controls deployment credentials, KMS/secrets, network policy, logs, data residency, backups, and incident response.

Until those prerequisites exist and are reviewed, public docs should describe enigma-relay, enigma-gateway, Docker, and HTTP routes as local/package/source demos or deployment-ready interfaces, not as live hosted service evidence.