# Public 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** surfaces are the same relay/gateway service APIs deployed with operator or customer infrastructure. They require deployment credentials, domain/TLS, production durable storage, KMS/secrets, monitoring, backups, incident response, and SIEM/log routing before they can be described as live. 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:

```js
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:

| Package subpath | `package.json` export key | Target | Status | Public exports |
| --- | --- | --- | --- | --- |
| `enigma-memory` | `.` | `packages/core/src/index.js` | stable local/package | Same as `./core`. |
| `enigma-memory/core` | `./core` | `packages/core/src/index.js` | stable local/package | `SHA256_PREFIX`, `EMPTY_MERKLE_ROOT`, `canonicalize`, `sha256Hex`, `hmacSha256Hex`, `generateSigningKeyPair`, `signPayload`, `verifySignature`, `receiptHash`, `createReceipt`, `verifyReceipt`, `verifyReceiptChain`, `MerkleSet`, `createCheckpoint`, `verifyCheckpoint`, `createMemoryAddress`. |
| `enigma-memory/vault` | `./vault` | `packages/vault/src/index.js` | stable local/package | `createVault`, `remember`, `recall`, `updateMemory`, `deleteMemory`, `exportBundle`, `importBundle`. |
| `enigma-memory/passport` | `./passport` | `packages/passport/src/index.js` | stable local/package | `createPassport`, `compileContextPack`, `verifyContextPack`. |
| `enigma-memory/boundary` | `./boundary` | `packages/boundary/src/index.js` | stable local/package | `createBoundaryManifest`, `verifyBoundaryManifest`, `classifyBoundaryPath`, `runBoundarySimulation`, `boundarySurfaces`, `boundaryClassifications`. |
| `enigma-memory/mcp-server` | `./mcp-server` | `packages/mcp-server/src/index.js` | stable local/package | `toolDescriptors`, `resourceDescriptors`, `promptDescriptors`, `handlers`, `enigma_init`, `enigma_remember`, `enigma_search`, `enigma_context_pack`, `enigma_delete`, `enigma_verify_receipts`, `enigma_passport_summary_resource`, `enigma_standard_memory_prompt`, `handleJsonRpcRequest`, `startStdioServer`, `default`. |
| `enigma-memory/connectors` | `./connectors` | `packages/connectors/src/index.js` | stable local/package | `supportedClients`, `platformDefaultConfigPath`, `getClientProfile`, `renderMcpConfig`, `connectClient`, `disconnectClient`, `doctorConnectors`, `runConnectorDemo`. |
| `enigma-memory/importers` | `./importers` | `packages/importers/src/index.js` | stable local/package | `importChatGptExport`, `importClaudeMemory`, `importMem0Export`, `importLettaAgentFile`, `importLangGraphStore`, `importZepGraphitiExport`, `exportEnigmaCapsule`, `importEnigmaCapsule`, `runImporterDemo`, `default`. |
| `enigma-memory/mesh` | `./mesh` | `packages/mesh/src/index.js` | stable local/package | `createMeshNode`, `createCapsuleManifest`, `verifyCapsuleManifest`, `createWitnessCheckpoint`, `verifyWitnessCheckpoint`, `createRelayStore`, `pushRelayRecord`, `pullRelayRecord`, `createFederationGrant`, `verifyFederationGrant`, `runMeshDemo`, `default`. |
| `enigma-memory/enterprise` | `./enterprise` | `packages/enterprise/src/index.js` | stable local/package | `createEnterprisePolicy`, `evaluateEnterprisePolicy`, `minimizeEnterpriseEvaluation`, `minimizeEnterprisePolicy`, `createGatewayDecision`, `verifyGatewayDecision`, `exportSiemEvent`, `runEnterpriseDemo`, `default`. |
| `enigma-memory/relay` | `./relay` | `apps/relay/src/server.mjs` | stable local/package service module | `createRelayState`, `createRelayServer`, `handleRelayRequest`, `serializeRelayState`, `hydrateRelayState`, `loadRelayStateFromFile`, `saveRelayStateToFile`, `runRelayDemo`. |
| `enigma-memory/gateway` | `./gateway` | `apps/gateway/src/server.mjs` | stable local/package service module | `createGatewayState`, `createGatewayServer`, `handleGatewayRequest`, `serializeGatewayState`, `hydrateGatewayState`, `loadGatewayStateFromFile`, `saveGatewayStateToFile`, `runGatewayDemo`, `default`. |
| `enigma-memory/desktop` | `./desktop` | `apps/desktop/src/app.js` | package-included desktop scaffold API | `DESKTOP_SCREENS`, `createDesktopState`, `desktopReducer`, `renderDesktopModel`, `startMcp`, `stopMcp`, `createVault`, `rememberMemory`, `deleteMemory`, `searchMemories`, `verifyReceipts`, `connectClient`, `disconnectClient`, `importBundle`, `exportBundle`, `updateMeshStatus`, `updateEnterpriseStatus`, `selectDesktopScreen`, `setDesktopDraft`, `desktopActions`, `actions`, `startMCP`, `stopMCP`, `remember`, `removeMemory`, `searchMemory`, `verifyReceiptOutput`, `connectDesktopClient`, `importDesktopBundle`, `exportDesktopBundle`, `desktopApi`. Desktop state is operational evidence only; cryptographic proof still comes from receipts and verifier output. |
| `enigma-memory/package.json` | `./package.json` | `package.json` | stable package metadata | Package metadata for tooling. |

`./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`)

| Export | Use | Notes |
| --- | --- | --- |
| `SHA256_PREFIX` | Constant string `sha256:`. | Used for root/address formatting. |
| `EMPTY_MERKLE_ROOT` | Constant empty Merkle root. | Stable empty-set root. |
| `canonicalize(value)` | Stable JSON canonicalization. | Throws on cyclic/unsupported values. |
| `sha256Hex(value)` | SHA-256 hex digest for strings, buffers, or canonicalized values. | Unprefixed hex. |
| `hmacSha256Hex({ key, value })` or `hmacSha256Hex(key, value)` | HMAC-SHA-256 hex digest. | Unprefixed hex. |
| `generateSigningKeyPair(options)` | Creates an Ed25519 key pair. | Returns PEM keys and key id metadata. |
| `signPayload({ payload, privateKey })` or `signPayload(payload, privateKey)` | Signs canonical payload bytes. | Returns base64url signature. |
| `verifySignature({ payload, signature, publicKey })` or positional form | Verifies an Ed25519 signature. | Returns boolean. |
| `receiptHash(receipt)` | Canonical receipt hash. | Returns `sha256:<hex>`. |
| `createReceipt(args)` | Creates `enigma.receipt.v1`. | Requires operation/tenant/subject/sequence/root/signer fields. |
| `verifyReceipt({ receipt, publicKey })` | Verifies receipt shape/signature. | Returns `{ ok, valid, errors }`. |
| `verifyReceiptChain({ receipts, publicKey, ...expectedRoots })` | Verifies sequence, hashes, and roots across receipts. | Returns verifier-style result plus chain metadata. |
| `MerkleSet` | Insert/delete/proof/root helper for deterministic sets. | Used for active/deleted sets and roots. |
| `createCheckpoint(args)` | Creates `enigma.state_checkpoint.v1`. | Signs root metadata; no raw memory required. |
| `verifyCheckpoint(args)` | Verifies checkpoint signature/root fields. | Returns `{ ok, valid, errors }`. |
| `createMemoryAddress(args)` | Creates deterministic memory addresses from secret/value/scope inputs. | Address is commitment-like metadata, not plaintext. |

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

| Export | Use | Notes |
| --- | --- | --- |
| `createVault(args)` | Creates local `enigma.vault.local.v1` state with signing/encryption metadata. | Local canonical state only. |
| `remember({ vault, passport, text/content/plaintext, purpose, purpose_tags, metadata })` | Stores private local memory and appends create receipt. | Returns `memory_addr`, public record, and receipt metadata. |
| `recall({ vault, passport, memory_addr, purpose })` | Reads active local memory and records retrieval evidence. | Provider-native memory remains cache only. |
| `updateMemory({ vault, passport, memory_addr, text/content/plaintext, metadata })` | Supersedes one local memory address with another. | Emits update/supersede receipt evidence. |
| `deleteMemory({ vault, passport, memory_addr, reason })` | Tombstones a local memory address. | Proves Enigma state no longer serves it; not provider deletion proof. |
| `exportBundle({ vault, includePlaintext: false })` | Exports `enigma.vault_bundle.v1` with receipts/checkpoints and encrypted/committed vault state. | Keep `includePlaintext` false for public proof artifacts. |
| `importBundle(args)` | Imports an `enigma.vault_bundle.v1` bundle. | Restores Enigma state from a bundle. |
| `createPassport({ vault, ...owner })` | Builds `enigma.passport.v1` metadata for vault roots and owner scope. | Passport metadata is not raw memory content. |
| `compileContextPack({ vault, passport, query, purpose, limit, memory_addresses })` | Builds `enigma.context_pack.v1` from active local memories and receipts. | Use only for authorized local retrieval. |
| `verifyContextPack({ contextPack, passport, publicKey })` | Verifies context-pack receipts/public shape. | Public-key verification is required for full receipt validation. |

### Boundary, mesh, and enterprise

| Module | Export | Use |
| --- | --- | --- |
| `enigma-memory/boundary` | `createBoundaryManifest(options)` | Creates `enigma.boundary_manifest.v1` path/classification manifest. |
| `enigma-memory/boundary` | `verifyBoundaryManifest(manifest)` | Validates manifest shape, surfaces, and classifications. |
| `enigma-memory/boundary` | `classifyBoundaryPath(manifest, pathRef)` | Classifies one declared path as committed/blocked/out-of-scope/broken. |
| `enigma-memory/boundary` | `runBoundarySimulation(options)` | Local demo harness for boundary classification evidence. |
| `enigma-memory/boundary` | `boundarySurfaces`, `boundaryClassifications` | Enumerations used by manifests. |
| `enigma-memory/mesh` | `createMeshNode(options)` | Creates signed `enigma.mesh_node.v1` descriptor. |
| `enigma-memory/mesh` | `createCapsuleManifest(options)`, `verifyCapsuleManifest(manifest, options)` | Creates/verifies signed capsule root metadata. |
| `enigma-memory/mesh` | `createWitnessCheckpoint(options)`, `verifyWitnessCheckpoint(checkpoint, options)` | Creates/verifies witness checkpoint roots. |
| `enigma-memory/mesh` | `createRelayStore(options)`, `pushRelayRecord(store, record)`, `pullRelayRecord(store, recordRef)` | Local in-memory relay record store for opaque encrypted records. |
| `enigma-memory/mesh` | `createFederationGrant(options)`, `verifyFederationGrant(grant, options)` | Creates/verifies signed federation grants. |
| `enigma-memory/mesh` | `runMeshDemo(options)` | Local mesh demo; not hosted availability evidence. |
| `enigma-memory/enterprise` | `createEnterprisePolicy(options)` | Creates default-deny `enigma.enterprise_policy.v1` with `provider_native_memory: \"cache_only\"`. |
| `enigma-memory/enterprise` | `evaluateEnterprisePolicy(policy, request)` | Evaluates provider/model/region/purpose/sensitivity/legal-hold request metadata. |
| `enigma-memory/enterprise` | `minimizeEnterpriseEvaluation(evaluation)`, `minimizeEnterprisePolicy(policy)` | Produces public/minimized views. |
| `enigma-memory/enterprise` | `createGatewayDecision(args)`, `verifyGatewayDecision(args)` | Creates/verifies signed gateway decisions. |
| `enigma-memory/enterprise` | `exportSiemEvent(args)` | Emits plaintext-minimized SIEM event metadata. |
| `enigma-memory/enterprise` | `runEnterpriseDemo(options)` | Local enterprise policy demo; not hosted/BYOC evidence. |

### 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`:

| Bin | `package.json` target | Status | Purpose |
| --- | --- | --- | --- |
| `enigma` | `./apps/cli/bin/enigma.mjs` | stable local/package | Main CLI for vault, MCP, connectors, importers, capsule, relay/gateway demos, and local verification. |
| `enigma-verify` | `./apps/verifier/bin/enigma-verify.mjs` | stable local/package | Offline exported-bundle verifier. |
| `enigma-mcp` | `./packages/mcp-server/bin/enigma-mcp.mjs` | stable local/package | MCP stdio server. |
| `enigma-relay` | `./apps/relay/bin/enigma-relay.mjs` | stable local/package local service bin | Local relay demo/server. Hosted use requires deployment infrastructure. |
| `enigma-gateway` | `./apps/gateway/bin/enigma-gateway.mjs` | stable local/package local service bin | Local gateway demo/server. Hosted/BYOC use requires deployment infrastructure. |

`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:

| Command | Inputs | Output boundary |
| --- | --- | --- |
| `enigma init --bundle <path>` | `--subject`/`--subject-id`, `--display-name`/`--name`, `--passphrase` | Creates local `enigma.vault_bundle.v1` state and prints `{ ok, bundle, schema, subject_id }`. |
| `enigma remember --bundle <path> --text <private local text>` | `--purpose`, `--tags`, `--metadata` | Prints `memory_addr` and `receipt_id`. Do not place private memory text in public proof artifacts. |
| `enigma recall --bundle <path> --id <memory_addr>` | `--purpose` | Reads from local vault and emits recall result plus receipt data. |
| `enigma update --bundle <path> --id <memory_addr> --text <private local text>` | `--metadata` | Prints old/new memory address and receipt id. |
| `enigma delete --bundle <path> --id <memory_addr>` | `--reason` | Tombstones the local Enigma memory address and prints receipt id; this is not provider deletion proof. |
| `enigma context --bundle <path>` | `--query`/`--q`, `--purpose`, `--limit`, `--out` | Emits `enigma.context_pack.v1` derived from active local memories and retrieval receipts. |
| `enigma export --bundle <path> --out <file>` | none beyond paths | Writes an exported bundle with encrypted/committed vault state and receipt metadata. |
| `enigma verify --bundle <exported-bundle.json>` | `--file` or `--export` aliases | Prints `enigma.verification_report.v1`. |
| `enigma doctor` | `--client`, connector options | Checks Node version, bins, schemas, MCP command name, and connector state. |
| `enigma install` | `--bundle`, `--client`, `--out`, connector options | Creates bundle if needed and prints MCP config snippets. |
| `enigma connect <client>` / `enigma disconnect <client>` | `--bundle`, `--config`, `--server-name`, `--mcp-command`/`--command`, `--dry-run` | Merges or removes the Enigma MCP server entry without making provider-native memory canonical. |
| `enigma mcp serve` | `ENIGMA_BUNDLE` env or tool-level `bundlePath` | Starts the same stdio MCP server as `enigma-mcp`. |
| `enigma boundary run` | `--scenario` (default `committed_crossing`), `--manifest`, `--trace` | Runs local boundary simulation and returns declared classification evidence. |
| `enigma relay demo` / `enigma gateway demo` | none | Runs local demo results only; not hosted availability evidence. |
| `enigma relay serve` / `enigma gateway serve` | `--host`, `--port`, `--once`, optional `--state-file <path>` | Starts local HTTP services on the requested bind address. `--state-file` persists local demo relay/gateway state across restarts without making the service hosted/BYOC production-ready. |
| `enigma mesh demo` / `enigma enterprise demo` | none | Runs local source/package demos for mesh artifacts and enterprise policy decisions. |

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`:

| Tool | Required params | Optional params | Returns |
| --- | --- | --- | --- |
| `enigma_init` | none | `bundlePath`, `tenant_id`, `subject_id`, `actor_id`, `policy_id` | Bundle summary with path, schema, counts, and whether it was created. |
| `enigma_remember` | `text` | `bundlePath`, `purpose`, `tags`, `metadata` | `{ ok: true, memory_addr, receipt_id }`. The local vault stores private memory; public receipts must not contain raw memory plaintext. |
| `enigma_search` | none | `bundlePath`, `query`, `memory_addr`, `purpose`, `limit` (`1..50`) | Search results or recalled memory plus retrieval receipts. |
| `enigma_context_pack` | none | `bundlePath`, `query`, `purpose`, `limit` (`1..50`), `memory_addresses` | Context pack with active local memories and retrieval/injection receipt metadata. |
| `enigma_delete` | `memory_addr` | `bundlePath`, `reason` | `{ ok: true, memory_addr, receipt_id }` for Enigma state tombstone only. |
| `enigma_verify_receipts` | none | `bundlePath`, `bundle` | Same verifier report as `verifyBundle`. |

Resources:

| URI | Name | MIME | Boundary |
| --- | --- | --- | --- |
| `enigma://passport/summary` | `Enigma Passport Summary` | `application/json` | MCP-safe passport and vault metadata. Raw memory plaintext is never exposed. |

Prompts:

| Prompt | Arguments | Purpose |
| --- | --- | --- |
| `enigma_standard_memory_prompt` | `question`, `purpose` | Instructs an assistant to use Enigma as canonical memory/proof state and treat provider-native memory as cache only. |

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:

| Method/path | Auth | Request | Response |
| --- | --- | --- | --- |
| `GET /health` | none | none | `{ ok: true, health }` where `health` includes service schema, node id, store id, record count, witness checkpoint count, and pairing count. |
| `POST /pairing/challenge` | none | JSON with `client_public_key` or `clientPublicKey`/`public_key` | `{ ok: true, challenge }`; challenge schema is `enigma.pairing_challenge.v1`. |
| `POST /pairing/complete` | none | `challenge_id`, client public key, and `client_signature`/`clientSignature`/`signature` over the challenge | `{ ok: true, pairing }`; pairing schema is `enigma.pairing_completion.v1`. |
| `POST /relay/push` | paired client signature unless server state explicitly sets `allowUnauthenticated` for local demos | Relay record object or `{ record }` envelope. Allowed fields include `capsule_id`, `encrypted_payload_hash`, `opaque_encrypted_record`, `received_at`, `expires_at`, and id aliases. | `201 { ok: true, record, authorization }`; record schema is `enigma.relay_record.v1`. |
| `GET /relay/pull?id=<record_id>` | paired client signature unless local demo auth is enabled | Query string `id` | `{ ok: true, record, authorization }`, `404` when missing. |
| `POST /witness/checkpoint` | paired client signature unless local demo auth is enabled | Witness checkpoint roots/metadata object or `{ checkpoint }` envelope; accepted root fields include `checkpoint_root`, `receipt_log_root`, `active_set_root`, `previous_witness_hash`, and camelCase aliases. | `201 { ok: true, checkpoint, verification, authorization }`; checkpoint schema is `enigma.witness_checkpoint.v1`. |
| `GET /witness/log` | none | none | `{ ok: true, checkpoints }`. |

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:

| Method/path | Request | Response |
| --- | --- | --- |
| `GET /health` | none | `{ ok: true, service: 'enigma-gateway', gateway_id, policy_id, policy_hash }`. |
| `GET /policy` | none | `{ ok: true, policy, internal }`; minimized policy by default, internal policy only when state opts into internal exposure. |
| `PUT /policy` | Policy object or `{ policy }` | `{ ok: true, policy, policy_hash, internal }` or `400 { ok: false, error: { code: 'POLICY_INVALID', reason_codes } }`. |
| `POST /gateway/evaluate` | `enigma.gateway_request.v1` fields: `operation`, `provider`, `model`, `region`, `purpose`, `sensitivity`, optional `memory_addr`, `memory_id`, `subject_id`, `legal_hold_delete` | `{ ok: true, evaluation, siem_event }`; evaluation is minimized unless internal exposure is enabled. |
| `POST /gateway/decision` | Same as `/gateway/evaluate` | `{ ok: true, evaluation, decision, verification, siem_event }`; decision schema is `enigma.gateway_decision.v1`. |
| `GET /siem/export` | none | `{ ok: true, schema: 'enigma.gateway_siem_export.v1', gateway_id, event_count, events }`. |

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`.

| Client id | Display name | Default config paths |
| --- | --- | --- |
| `claude-desktop` | Claude Desktop | Windows `%APPDATA%\\Claude\\claude_desktop_config.json`; macOS `$HOME/Library/Application Support/Claude/claude_desktop_config.json`; Linux `$HOME/.config/Claude/claude_desktop_config.json`. |
| `cursor` | Cursor | Windows `%USERPROFILE%\\.cursor\\mcp.json`; macOS/Linux `$HOME/.cursor/mcp.json`. |
| `kimi-code` | Kimi Code | Windows `%APPDATA%\\Kimi Code\\mcp.json`; macOS `$HOME/Library/Application Support/Kimi Code/mcp.json`; Linux `$HOME/.config/kimi-code/mcp.json`. |
| `vscode-cline` | VS Code Cline | Windows `%APPDATA%\\Code\\User\\globalStorage\\saoudrizwan.claude-dev\\settings\\cline_mcp_settings.json`; macOS `$HOME/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`; Linux `$HOME/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`. |
| `roo` | Roo Code | Windows `%APPDATA%\\Code\\User\\globalStorage\\rooveterinaryinc.roo-cline\\settings\\mcp_settings.json`; macOS `$HOME/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json`; Linux `$HOME/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json`. |
| `opencode` | OpenCode | Windows `%APPDATA%\\opencode\\opencode.json`; macOS `$HOME/Library/Application Support/opencode/opencode.json`; Linux `$HOME/.config/opencode/opencode.json`. |
| `generic-mcp` | Generic MCP Client | Windows `%APPDATA%\\Enigma\\mcp.json`; macOS `$HOME/Library/Application Support/Enigma/mcp.json`; Linux `$HOME/.config/enigma/mcp.json`. |

`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.

| Function | Source type | CLI sources | Output |
| --- | --- | --- | --- |
| `importChatGptExport(input, options)` | `chatgpt_export` | `chatgpt`, `chatgpt-export`, `chatgpt_export` | `enigma.import_report.v1` with source refs, limitations, confidence, completeness flags, candidates, and optional vault writes. |
| `importClaudeMemory(input, options)` | `claude_memory` | `claude`, `claude-memory`, `claude_memory` | Same import report shape. |
| `importMem0Export(input, options)` | `mem0_export` | `mem0`, `mem0-export`, `mem0_export` | Same import report shape. |
| `importLettaAgentFile(input, options)` | `letta_agent_file` | `letta`, `letta-agent`, `letta_agent`, `letta_agent_file` | Same import report shape. |
| `importLangGraphStore(input, options)` | `langgraph_store` | `langgraph`, `langgraph-store`, `langgraph_store` | Same import report shape. |
| `importZepGraphitiExport(input, options)` | `zep_graphiti_export` | `zep`, `graphiti`, `zep-graphiti`, `zep_graphiti`, `zep_graphiti_export` | Same import report shape. |
| `exportEnigmaCapsule(args)` | Enigma import reports/candidates | `enigma capsule export` | `enigma.import_capsule.v1` with public artifacts and verifier metadata. |
| `importEnigmaCapsule(capsule, options)` | Enigma import capsule | `enigma capsule import` | Verification/import result, with vault writes only when a vault is supplied. |
| `runImporterDemo(options)` | local demo | module demo | Demo result for local review only. |

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:

```json
{
  "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.

| File | `$id` | Primary `schema` const / surface |
| --- | --- | --- |
| `specs/receipt-v1.schema.json` | `https://schemas.enigma.ai/receipt-v1.schema.json` | `enigma.receipt.v1`; receipt lifecycle events. |
| `specs/memory-event-v1.schema.json` | `https://schemas.enigma.ai/memory-event-v1.schema.json` | `enigma.memory_event.v1`; vault event metadata. |
| `specs/passport-v1.schema.json` | `https://schemas.enigma.ai/passport-v1.schema.json` | `enigma.passport.v1`; passport/vault roots. |
| `specs/state-checkpoint-v1.schema.json` | `https://schemas.enigma.ai/state-checkpoint-v1.schema.json` | `enigma.state_checkpoint.v1`; signed state checkpoints. |
| `specs/boundary-manifest-v1.schema.json` | `https://schemas.enigma.ai/boundary-manifest-v1.schema.json` | `enigma.boundary_manifest.v1`; declared boundary paths and classifications. |
| `specs/claim-boundary-manifest-v1.schema.json` | `https://schemas.enigma.ai/claim-boundary-manifest-v1.schema.json` | `enigma.claim_boundary_manifest.v1`; public claim scope and non-claims. |
| `specs/deletion-tombstone-v1.schema.json` | `https://schemas.enigma.ai/deletion-tombstone-v1.schema.json` | `enigma.deletion_tombstone.v1`; Enigma tombstone evidence and explicit non-proofs. |
| `specs/import-report-v1.schema.json` | `https://schemas.enigma.ai/import-report-v1.schema.json` | `enigma.import_report.v1`; importer report with limitations/completeness. |
| `specs/capsule-v1.schema.json` | `https://schemas.enigma.ai/capsule-v1.schema.json` | `enigma.capsule.v1`; generic capsule schema. Importer code currently emits `enigma.import_capsule.v1` capsules with verifier metadata. |
| `specs/trust-bundle-v1.schema.json` | `https://schemas.enigma.ai/trust-bundle-v1.schema.json` | `enigma.trust_bundle.v1`; trusted issuers/witnesses and import capsule policy. |
| `specs/relay-record-v1.schema.json` | `https://schemas.enigma.ai/relay-record-v1.schema.json` | `enigma.relay_record.v1`; opaque encrypted relay record. |
| `specs/connector-profile-v1.schema.json` | `https://schemas.enigma.ai/connector-profile-v1.schema.json` | `enigma.connector_profile.v1`; connector profile metadata. |
| `specs/gateway-request-v1.schema.json` | `https://schemas.enigma.ai/gateway-request-v1.schema.json` | `enigma.gateway_request.v1`; plaintext-free gateway request. |
| `specs/mesh-node-v1.schema.json` | `https://schemas.enigma.ai/mesh-node-v1.schema.json` | `enigma.mesh_node.v1`, `enigma.capsule_manifest.v1`, `enigma.witness_checkpoint.v1`, `enigma.relay_record.v1`, `enigma.federation_grant.v1`; mesh artifacts. |
| `specs/enterprise-policy-v1.schema.json` | `https://schemas.enigma.ai/enterprise-policy-v1.schema.json` | `enigma.enterprise_policy.v1`; default-deny hosted/BYOC/on-prem policy with `provider_native_memory: "cache_only"`. |

## 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.