enigma-memory 0.1.0 → 0.1.2

package/docs/sdk-api.md

@@ -0,0 +1,181 @@
+# SDK and API guide
+
+This guide covers the public package imports for `enigma-memory@0.1.2`. The SDK runs locally by default: vaults, passports, context packs, receipts, relay/gateway demo state, storage contracts, metering artifacts, and settlement artifacts are package-level developer surfaces. They are not evidence of hosted Enigma cloud, provider-side deletion, provider model forgetting, token ROI, invoice savings, compliance certification, or benchmark leadership.
+
+## Install and import style
+
+```sh
+npm install enigma-memory
+```
+
+Use ESM imports and explicit subpaths when you know the surface you need:
+
+```js
+import { createVault, remember } from 'enigma-memory/vault';
+import { createPassport, compileContextPack } from 'enigma-memory/passport';
+```
+
+## Package exports
+
+### `enigma-memory`
+
+The package root exports the core proof helpers. Use it for canonical JSON, hashes, signatures, receipt creation, receipt-chain verification, checkpoints, Merkle sets, and deterministic memory addresses.
+
+```js
+import { verifyReceiptChain, receiptHash, MerkleSet } from 'enigma-memory';
+```
+
+### `enigma-memory/vault`
+
+The vault module creates local encrypted vault state and proof-carrying exports. Memory text is local input. Full `exportBundle` output can include a local import keyring, so publish only reviewed public summaries, receipt reports, roots, commitments, or keyring-stripped artifacts; do not use vault exports to claim provider-side deletion or model forgetting.
+
+```js
+import { createVault, remember, exportBundle, importBundle } from 'enigma-memory/vault';
+
+const vault = createVault({ subject_id: 'demo-subject' });
+const remembered = remember({ vault, text: 'Demo project prefers local proof bundles.' });
+const bundle = exportBundle({ vault });
+```
+
+### `enigma-memory/passport`
+
+The passport module describes vault ownership/scope and compiles receipt-backed context packs for authorized local retrieval.
+
+```js
+import { createPassport, compileContextPack, verifyContextPack } from 'enigma-memory/passport';
+
+const passport = createPassport({ vault, display_name: 'Demo Developer' });
+const pack = compileContextPack({ vault, passport, query: 'project preference', limit: 1 });
+const checked = verifyContextPack({ contextPack: pack, passport, vault, publicKey: bundle.keyring.publicKey });
+```
+
+### `enigma-memory/optimizer`
+
+The optimizer module builds deterministic, local memory-selection plans and plaintext-minimized access receipts. Token and cost helpers estimate from explicit inputs only; they do not prove ROI or provider invoice savings.
+
+```js
+import { createMemoryOptimizationPlan, createMemoryAccessReceipt, estimateTextTokens } from 'enigma-memory/optimizer';
+
+const plan = createMemoryOptimizationPlan({
+  candidates: [{ address: remembered.memory_addr, content: 'Demo project prefers local proof bundles.' }],
+  prompt_tokens: estimateTextTokens('Current local app context'),
+});
+const receipt = createMemoryAccessReceipt({ item: plan.items[0], plan });
+```
+
+### `enigma-memory/connectors`
+
+The connectors module renders and manages local MCP client config for supported clients. It uses the `enigma-mcp` command and an `ENIGMA_BUNDLE` environment variable.
+
+```js
+import { supportedClients, renderMcpConfig, doctorConnectors } from 'enigma-memory/connectors';
+
+const config = renderMcpConfig({ env: { ENIGMA_BUNDLE: './enigma-bundle.json' } });
+const report = await doctorConnectors({ clientId: 'generic-mcp' });
+```
+
+### `enigma-memory/mcp-server`
+
+The MCP server module exposes descriptors, handlers, JSON-RPC handling, and a stdio server for local MCP clients.
+
+```js
+import { toolDescriptors, handlers, handleJsonRpcRequest, startStdioServer } from 'enigma-memory/mcp-server';
+
+const initTool = toolDescriptors.find((tool) => tool.name === 'enigma_init');
+const reply = await handleJsonRpcRequest({ jsonrpc: '2.0', id: 1, method: 'tools/list' });
+```
+
+### `enigma-memory/relay`
+
+The relay module exposes a local relay witness service API and demo state helpers. Local relay state is useful for development and review, but it is not hosted-cloud durability evidence.
+
+```js
+import { createRelayState, createRelayServer, runRelayDemo } from 'enigma-memory/relay';
+
+const state = createRelayState({ role: 'relay_witness' });
+const server = createRelayServer({ state });
+```
+
+### `enigma-memory/gateway`
+
+The gateway module exposes a local policy gateway service API and demo state helpers. Local gateway decisions are package/source evidence unless deployed and operated with production storage, monitoring, secrets, and incident-response controls.
+
+```js
+import { createGatewayState, handleGatewayRequest, runGatewayDemo } from 'enigma-memory/gateway';
+
+const state = createGatewayState({ gateway_id: 'local-gateway' });
+const demo = runGatewayDemo();
+```
+
+### `enigma-memory/storage`
+
+The storage module emits PostgreSQL migration and operation contracts for production storage. It is a contract/builder surface; applying migrations requires your own reviewed database environment.
+
+```js
+import { productionStorageContract, buildPostgresMigration, buildRelayRecordUpsert } from 'enigma-memory/storage';
+
+const contract = productionStorageContract({ schema: 'enigma' });
+const migration = buildPostgresMigration({ schema: 'enigma' });
+```
+
+### `enigma-memory/metering`
+
+The metering module creates content-minimized usage events and deterministic aggregates. Inputs are explicit counts and metadata; outputs do not prove provider discounts or ROI.
+
+```js
+import { createUsageEvent, aggregateUsageEvents } from 'enigma-memory/metering';
+
+const event = createUsageEvent({
+  tenant_id: 'demo-tenant',
+  provider: 'local',
+  model: 'demo-model',
+  prompt_tokens: 800,
+  completion_tokens: 120,
+  memory_baseline_tokens: 1200,
+  memory_optimized_tokens: 800,
+});
+const aggregate = aggregateUsageEvents({ events: [event] });
+```
+
+### `enigma-memory/settlement`
+
+The settlement module creates hash-only memory jobs, capacity profiles, quotes, service receipts, receipt verification, and batches for permissionless access/accountability boundaries. It does not decentralize raw memory storage or inference.
+
+```js
+import { createPermissionlessMemoryJob, createOperatorServiceQuote, createServiceSettlementReceipt, verifyServiceSettlementReceipt } from 'enigma-memory/settlement';
+
+const job = createPermissionlessMemoryJob({
+  tenant_id: 'demo-tenant',
+  job_type: 'context.pack',
+  memory_commitment_root: 'sha256:0000000000000000000000000000000000000000000000000000000000000000',
+  policy_hash: 'sha256:1111111111111111111111111111111111111111111111111111111111111111',
+  usage_event_hash: 'sha256:2222222222222222222222222222222222222222222222222222222222222222',
+  requested_at: '2026-01-01T00:00:00.000Z',
+  expires_at: '2026-01-02T00:00:00.000Z',
+  max_price_amount: 10,
+  payment_asset: 'CREDITS',
+});
+```
+
+## Verifying exported proof
+
+Package consumers should verify exported bundles through the CLI or MCP verifier rather than importing source-only verifier internals. Treat full bundles as private unless you have reviewed and removed local import key material before sharing:
+
+```sh
+enigma verify --bundle enigma-export.json
+enigma-verify enigma-export.json
+```
+
+For in-process SDK checks, use exported public keys with core receipt verification:
+
+```js
+import { verifyReceiptChain } from 'enigma-memory';
+
+const report = verifyReceiptChain({
+  receipts: bundle.receipts,
+  publicKey: bundle.keyring.publicKey,
+  expectedReceiptLogRoot: bundle.vault.receipt_log_root,
+  expectedActiveSetRoot: bundle.vault.active_set_root,
+  verifyEmbeddedReceiptLogRoot: true,
+});
+```

package/examples/ci/github-actions.yml

@@ -0,0 +1,63 @@
+name: Enigma Memory smoke
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  enigma-memory-smoke:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Set up Node 24
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+
+      - name: Create disposable npm project
+        run: npm init -y
+
+      - name: Install Enigma Memory
+        run: npm install enigma-memory@0.1.1
+
+      - name: Run Enigma quickstart
+        run: npx enigma quickstart --overwrite
+
+      - name: Run Enigma doctor
+        run: npx enigma doctor
+
+      - name: Smoke test package imports
+        run: |
+          node --input-type=module <<'JS'
+          import { createVault, remember, exportBundle } from 'enigma-memory/vault';
+          import { createPassport, compileContextPack } from 'enigma-memory/passport';
+          import { verifyReceiptChain } from 'enigma-memory';
+
+          const vault = createVault({ subject_id: 'ci-demo-subject' });
+          const passport = createPassport({ vault, display_name: 'CI Demo' });
+          const remembered = remember({
+            vault,
+            text: 'CI smoke uses a generic non-private Enigma Memory fact.',
+            purpose_tags: ['ci-smoke'],
+          });
+          const pack = compileContextPack({
+            vault,
+            passport,
+            memory_addresses: [remembered.memory_addr],
+            limit: 1,
+          });
+          const bundle = exportBundle({ vault, includePlaintext: false });
+          const report = verifyReceiptChain({
+            receipts: bundle.receipts,
+            publicKey: bundle.keyring.publicKey,
+            expectedReceiptLogRoot: bundle.vault.receipt_log_root,
+            expectedActiveSetRoot: bundle.vault.active_set_root,
+            verifyEmbeddedReceiptLogRoot: true,
+          });
+          if (!report.valid) throw new Error(`receipt verification failed: ${report.errors.join('; ')}`);
+          console.log(JSON.stringify({ ok: true, memory_count: pack.memory_addresses.length, receipt_count: bundle.receipts.length }));
+          JS

package/examples/node-basic-memory.mjs

@@ -0,0 +1,84 @@
+import { createVault, remember, exportBundle } from 'enigma-memory/vault';
+import { createPassport, compileContextPack, verifyContextPack } from 'enigma-memory/passport';
+import { verifyReceiptChain } from 'enigma-memory';
+
+const now = '2026-01-01T00:00:00.000Z';
+
+const vault = createVault({
+  tenant_id: 'demo-tenant',
+  subject_id: 'demo-subject',
+  actor_id: 'demo-app',
+  policy_id: 'demo-local-policy',
+  now,
+});
+
+const remembered = remember({
+  vault,
+  text: 'Demo project prefers short context packs and local receipt verification.',
+  kind: 'preference',
+  sensitivity: 'normal',
+  purpose_tags: ['demo', 'local-proof'],
+  metadata: { demo_id: 'node-basic-memory' },
+  now: '2026-01-01T00:00:01.000Z',
+});
+
+const passport = createPassport({
+  vault,
+  display_name: 'Demo Developer',
+  now: '2026-01-01T00:00:01.500Z',
+});
+
+const contextPack = compileContextPack({
+  vault,
+  passport,
+  query: 'How should this demo handle memory context?',
+  purpose: 'demo_context',
+  provider: 'local',
+  model: 'local-demo',
+  memory_addresses: [remembered.memory_addr],
+  limit: 1,
+  now: '2026-01-01T00:00:02.000Z',
+});
+
+const proofBundle = exportBundle({
+  vault,
+  includePlaintext: false,
+  now: '2026-01-01T00:00:03.000Z',
+});
+
+const publicKey = proofBundle.keyring.publicKey;
+
+const contextVerification = verifyContextPack({
+  contextPack,
+  passport,
+  vault,
+  publicKey,
+});
+
+const receiptVerification = verifyReceiptChain({
+  receipts: proofBundle.receipts,
+  publicKey,
+  expectedReceiptLogRoot: proofBundle.vault.receipt_log_root,
+  expectedActiveSetRoot: proofBundle.vault.active_set_root,
+  verifyEmbeddedReceiptLogRoot: true,
+});
+
+const summary = {
+  ok: contextVerification.valid === true && receiptVerification.valid === true,
+  vault_id: proofBundle.vault.vault_id,
+  passport_id: passport.passport_id,
+  context_pack_id: contextPack.context_pack_id,
+  active_memory_count: proofBundle.active_memory_addresses.length,
+  receipt_count: proofBundle.receipts.length,
+  active_set_root: proofBundle.vault.active_set_root,
+  receipt_log_root: proofBundle.vault.receipt_log_root,
+  remembered_memory_addr: remembered.memory_addr,
+  context_pack_memory_count: contextPack.memory_addresses.length,
+  verification: {
+    context_pack_valid: contextVerification.valid,
+    receipt_chain_valid: receiptVerification.valid,
+    receipt_errors: receiptVerification.errors,
+  },
+};
+
+console.log(JSON.stringify(summary, null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "enigma-memory",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "Provider-agnostic AI memory passport and offline-verifiable proof layer.",
   "license": "Apache-2.0",
@@ -28,6 +28,8 @@
     "apps/native-host/README.md",
     "apps/native-host/manifests/",
     "apps/desktop/src/",
+    "apps/browser-extension/manifest.json",
+    "apps/browser-extension/src/",
     "apps/gateway/bin/",
     "apps/gateway/src/",
     "apps/relay/src/",
@@ -39,6 +41,7 @@
     "packages/connectors/src/",
     "packages/core/src/",
     "packages/enterprise/src/",
+    "packages/hosted-cloud/src/",
     "packages/importers/src/",
     "packages/optimizer/src/",
     "packages/mcp-server/bin/",
@@ -56,6 +59,10 @@
     "deploy/kubernetes/enigma-backend.example.yaml",
     "scripts/check.mjs",
     "scripts/install-enigma-local.mjs",
+    "scripts/verify-registry-install.mjs",
+    "scripts/run-memory-benchmarks.mjs",
+    "scripts/build-installer-assets.mjs",
+    "scripts/package-browser-extension.mjs",
     "scripts/build-production-readiness-manifest.mjs",
     "scripts/build-production-backend-env-kit.mjs",
     "scripts/cloudflare-secret-env.mjs",
@@ -102,6 +109,14 @@
     "scripts/release-provenance.mjs",
     "scripts/build-review-packet.mjs",
     "scripts/build-demo-assets.mjs",
+    "docs/sdk-api.md",
+    "docs/developer-ecosystem.md",
+    "docs/memory-benchmarks.md",
+    "docs/installers-and-desktop.md",
+    "docs/browser-extension-install.md",
+    "docs/hosted-cloud-product.md",
+    "examples/",
+    "templates/",
     "specs/"
   ],
   "bin": {
@@ -116,6 +131,7 @@
     "check": "node scripts/check.mjs",
     "test": "node --test test/*.test.mjs",
     "install:local": "node scripts/install-enigma-local.mjs",
+    "registry:verify": "node scripts/verify-registry-install.mjs",
     "boundary": "node harnesses/boundary-sim/boundary_harness.mjs",
     "release:audit": "node scripts/release-audit.mjs",
     "provenance:local": "node scripts/release-provenance.mjs",
@@ -127,6 +143,9 @@
     "cloudflare:token-request": "node scripts/build-cloudflare-token-request.mjs",
     "infrastructure:readiness": "node scripts/infrastructure-readiness.mjs",
     "memory:benchmark": "node scripts/memory-optimization-benchmark.mjs",
+    "benchmark:memory-suite": "node scripts/run-memory-benchmarks.mjs",
+    "installer:assets": "node scripts/build-installer-assets.mjs",
+    "browser:extension:package": "node scripts/package-browser-extension.mjs",
     "production:manifest": "node scripts/build-production-readiness-manifest.mjs",
     "production:backend-env": "node scripts/build-production-backend-env-kit.mjs",
     "production:storage": "node scripts/build-production-storage-migration.mjs",
@@ -179,7 +198,9 @@
     "./connectors": "./packages/connectors/src/index.js",
     "./core": "./packages/core/src/index.js",
     "./desktop": "./apps/desktop/src/app.js",
+    "./desktop/tray": "./apps/desktop/src/tray.js",
     "./enterprise": "./packages/enterprise/src/index.js",
+    "./hosted-cloud": "./packages/hosted-cloud/src/index.js",
     "./gateway": "./apps/gateway/src/server.mjs",
     "./importers": "./packages/importers/src/index.js",
     "./mcp-server": "./packages/mcp-server/src/index.js",