enigma-memory 0.1.1 → 0.1.3

package/apps/desktop/src/tray.js

@@ -0,0 +1,231 @@
+export const TRAY_MODEL_SCHEMA = 'enigma.desktop.tray_model.v1';
+export const TRAY_MENU_SCHEMA = 'enigma.desktop.tray_menu.v1';
+
+export const TRAY_ACTION_TYPES = Object.freeze({
+  STATUS: 'tray/status',
+  QUICKSTART: 'tray/quickstart',
+  CONNECT_CLIENTS: 'tray/connect-clients',
+  OPEN_DOCS: 'tray/open-docs',
+  RUN_DIAGNOSTICS: 'tray/run-diagnostics',
+  QUIT: 'tray/quit',
+});
+
+const DEFAULT_DOCS_URL = 'https://docs.enigmaprotocol.net/docs/install';
+const STATUS_VALUES = Object.freeze(new Set(['not-installed', 'ready', 'needs-setup', 'running', 'degraded', 'offline']));
+const DIAGNOSTIC_VALUES = Object.freeze(new Set(['idle', 'queued', 'running', 'passed', 'failed']));
+const CLIENTS = Object.freeze([
+  Object.freeze({ id: 'claude-desktop', label: 'Claude Desktop', kind: 'mcp-client' }),
+  Object.freeze({ id: 'cursor', label: 'Cursor', kind: 'mcp-client' }),
+  Object.freeze({ id: 'vscode', label: 'VS Code', kind: 'mcp-client' }),
+  Object.freeze({ id: 'browser-bridge', label: 'Browser bridge', kind: 'extension' }),
+]);
+
+function cleanString(value) {
+  return String(value ?? '').trim();
+}
+
+function normalizeStatus(value) {
+  const status = cleanString(value);
+  return STATUS_VALUES.has(status) ? status : 'needs-setup';
+}
+
+function normalizeDiagnostics(value) {
+  const status = cleanString(value);
+  return DIAGNOSTIC_VALUES.has(status) ? status : 'idle';
+}
+
+function normalizeClients(value) {
+  const requested = Array.isArray(value) ? value : [];
+  const seen = new Set();
+  const known = new Map(CLIENTS.map((client) => [client.id, client]));
+  const clients = [];
+  for (const item of requested) {
+    const id = cleanString(typeof item === 'string' ? item : item?.id);
+    const connected = typeof item === 'string' || item?.connected === true;
+    if (!known.has(id) || seen.has(id) || !connected) continue;
+    seen.add(id);
+    clients.push({ ...known.get(id), connected: true });
+  }
+  for (const client of CLIENTS) {
+    if (!seen.has(client.id)) clients.push({ ...client, connected: false });
+  }
+  return clients;
+}
+
+function menuItem(id, label, action, options = {}) {
+  return Object.freeze({
+    id,
+    label,
+    action,
+    enabled: options.enabled !== false,
+    checked: options.checked === true,
+    role: cleanString(options.role) || 'item',
+    honest_boundary: cleanString(options.honest_boundary),
+  });
+}
+
+function action(type, payload = {}) {
+  return Object.freeze({ type, ...payload });
+}
+
+export function createTrayState(options = {}) {
+  const status = normalizeStatus(options.status);
+  const clients = normalizeClients(options.connectedClients ?? options.clients);
+  const connectedCount = clients.filter((client) => client.connected).length;
+  return Object.freeze({
+    schema: TRAY_MODEL_SCHEMA,
+    model_only: true,
+    native_tray_started: false,
+    status,
+    status_label: statusLabel(status),
+    quickstart_available: options.quickstartAvailable !== false,
+    clients: Object.freeze(clients.map((client) => Object.freeze({ ...client }))),
+    connected_client_count: connectedCount,
+    docs_url: cleanString(options.docsUrl) || DEFAULT_DOCS_URL,
+    diagnostics: Object.freeze({
+      status: normalizeDiagnostics(options.diagnosticsStatus),
+      last_result: cleanString(options.diagnosticsResult),
+    }),
+    quit_requested: options.quitRequested === true,
+  });
+}
+
+export function statusLabel(status) {
+  switch (normalizeStatus(status)) {
+    case 'ready':
+      return 'Ready';
+    case 'running':
+      return 'Running';
+    case 'degraded':
+      return 'Needs attention';
+    case 'offline':
+      return 'Offline';
+    case 'not-installed':
+      return 'Not installed';
+    default:
+      return 'Needs setup';
+  }
+}
+
+export function createTrayMenu(state = createTrayState()) {
+  const model = state?.schema === TRAY_MODEL_SCHEMA ? state : createTrayState(state);
+  return Object.freeze({
+    schema: TRAY_MENU_SCHEMA,
+    model_only: true,
+    native_tray_started: false,
+    status: model.status,
+    items: Object.freeze([
+      menuItem('status', `Status: ${model.status_label}`, TRAY_ACTION_TYPES.STATUS, {
+        enabled: false,
+        honest_boundary: 'Local tray status is an application model snapshot, not cryptographic proof.',
+      }),
+      menuItem('quickstart', 'Run quickstart', TRAY_ACTION_TYPES.QUICKSTART, {
+        enabled: model.quickstart_available && model.status !== 'running',
+        honest_boundary: 'Emits an intent to run the existing quickstart command; this module does not execute commands.',
+      }),
+      menuItem('connect-clients', `Connect clients (${model.connected_client_count})`, TRAY_ACTION_TYPES.CONNECT_CLIENTS, {
+        honest_boundary: 'Opens client-connection intent only; no MCP client is configured by this pure model.',
+      }),
+      menuItem('open-docs', 'Open install docs', TRAY_ACTION_TYPES.OPEN_DOCS, {
+        honest_boundary: 'Emits a docs URL intent only; this module does not launch a browser.',
+      }),
+      menuItem('run-diagnostics', diagnosticsLabel(model.diagnostics.status), TRAY_ACTION_TYPES.RUN_DIAGNOSTICS, {
+        enabled: model.diagnostics.status !== 'running',
+        honest_boundary: 'Emits diagnostics intent only; the caller owns command execution and evidence capture.',
+      }),
+      menuItem('separator-before-quit', '—', '', { enabled: false, role: 'separator' }),
+      menuItem('quit', 'Quit Enigma tray', TRAY_ACTION_TYPES.QUIT, {
+        honest_boundary: 'Emits quit intent only; host application owns process shutdown.',
+      }),
+    ]),
+  });
+}
+
+function diagnosticsLabel(status) {
+  switch (normalizeDiagnostics(status)) {
+    case 'queued':
+      return 'Diagnostics queued';
+    case 'running':
+      return 'Diagnostics running';
+    case 'passed':
+      return 'Run diagnostics (last passed)';
+    case 'failed':
+      return 'Run diagnostics (last failed)';
+    default:
+      return 'Run diagnostics';
+  }
+}
+
+export function trayStatus(status) {
+  return action(TRAY_ACTION_TYPES.STATUS, { status: normalizeStatus(status) });
+}
+
+export function runQuickstart(options = {}) {
+  return action(TRAY_ACTION_TYPES.QUICKSTART, { bundle: cleanString(options.bundle) || '<bundle-path>', overwrite: options.overwrite !== false });
+}
+
+export function connectClients(clientIds = []) {
+  return action(TRAY_ACTION_TYPES.CONNECT_CLIENTS, { clients: normalizeClients(clientIds).filter((client) => client.connected).map((client) => client.id) });
+}
+
+export function openDocs(url = DEFAULT_DOCS_URL) {
+  return action(TRAY_ACTION_TYPES.OPEN_DOCS, { url: cleanString(url) || DEFAULT_DOCS_URL });
+}
+
+export function runDiagnostics(scope = 'local') {
+  return action(TRAY_ACTION_TYPES.RUN_DIAGNOSTICS, { scope: cleanString(scope) || 'local' });
+}
+
+export function quitTray() {
+  return action(TRAY_ACTION_TYPES.QUIT, { quit_requested: true });
+}
+
+export function reduceTrayState(state = createTrayState(), requestedAction = {}) {
+  const model = state?.schema === TRAY_MODEL_SCHEMA ? state : createTrayState(state);
+  const type = cleanString(requestedAction.type);
+  switch (type) {
+    case TRAY_ACTION_TYPES.STATUS:
+      return createTrayState({ ...model, status: requestedAction.status });
+    case TRAY_ACTION_TYPES.QUICKSTART:
+      return createTrayState({ ...model, status: 'running', diagnosticsStatus: model.diagnostics.status });
+    case TRAY_ACTION_TYPES.CONNECT_CLIENTS:
+      return createTrayState({ ...model, connectedClients: requestedAction.clients });
+    case TRAY_ACTION_TYPES.OPEN_DOCS:
+      return createTrayState({ ...model, docsUrl: requestedAction.url });
+    case TRAY_ACTION_TYPES.RUN_DIAGNOSTICS:
+      return createTrayState({ ...model, diagnosticsStatus: 'queued' });
+    case TRAY_ACTION_TYPES.QUIT:
+      return createTrayState({ ...model, quitRequested: true });
+    default:
+      return model;
+  }
+}
+
+export function trayActionIntent(requestedAction = {}) {
+  const type = cleanString(requestedAction.type);
+  switch (type) {
+    case TRAY_ACTION_TYPES.STATUS:
+      return Object.freeze({ kind: 'status', status: normalizeStatus(requestedAction.status), side_effect: false });
+    case TRAY_ACTION_TYPES.QUICKSTART:
+      return Object.freeze({ kind: 'quickstart', command: 'enigma', args: ['quickstart', '--bundle', '<bundle-path>', '--overwrite'], side_effect: 'caller-owned' });
+    case TRAY_ACTION_TYPES.CONNECT_CLIENTS:
+      return Object.freeze({ kind: 'connect_clients', clients: normalizeClients(requestedAction.clients).filter((client) => client.connected).map((client) => client.id), side_effect: 'caller-owned' });
+    case TRAY_ACTION_TYPES.OPEN_DOCS:
+      return Object.freeze({ kind: 'open_docs', url: cleanString(requestedAction.url) || DEFAULT_DOCS_URL, side_effect: 'caller-owned' });
+    case TRAY_ACTION_TYPES.RUN_DIAGNOSTICS:
+      return Object.freeze({ kind: 'run_diagnostics', command: 'enigma', args: ['doctor'], side_effect: 'caller-owned' });
+    case TRAY_ACTION_TYPES.QUIT:
+      return Object.freeze({ kind: 'quit', side_effect: 'caller-owned' });
+    default:
+      return Object.freeze({ kind: 'unknown', side_effect: false });
+  }
+}
+
+export const trayActions = Object.freeze({
+  trayStatus,
+  runQuickstart,
+  connectClients,
+  openDocs,
+  runDiagnostics,
+  quitTray,
+});

package/docs/benchmark-reproducibility.md

@@ -0,0 +1,113 @@
+# Benchmark reproducibility
+
+This guide explains how to reproduce the current local Enigma memory benchmark, save the public-safe JSON report, cite the external benchmark standards it is modeled after, and understand what is still required before publishing live third-party comparisons.
+
+## What is reproducible today
+
+The current package is `enigma-memory@0.1.3`. The local benchmark is available through the package script and the script file it wraps:
+
+```sh
+cd enigma
+npm run benchmark:memory-suite
+npm run benchmark:memory-suite -- --out benchmark-report.json
+node scripts/run-memory-benchmarks.mjs --out benchmark-report.json
+```
+
+The `--out` form writes the report to the requested path and prints only a small status object. Without `--out`, the command writes the full JSON report to stdout.
+
+The report schema is `enigma.memory_benchmark_suite.v1`. It is designed to be public-safe: it contains aggregate metrics, commitments, citations, cross-provider profile labels, and claim boundaries. It does not include raw fixture memory, private question text, private answer text, provider transcripts, credentials, account ids, or local absolute paths.
+
+## Reproduce and save JSON
+
+1. Use a clean checkout containing `enigma-memory@0.1.3`.
+2. From a repository root that contains `enigma/package.json`, enter the package directory:
+
+   ```sh
+   cd enigma
+   ```
+
+   If your checkout already has `package.json` for `enigma-memory` at the current directory, skip this `cd`.
+
+3. Install the package dependencies with the reviewed package command:
+
+   ```sh
+   npm install
+   ```
+
+4. Run the benchmark and save the public-safe JSON report:
+
+   ```sh
+   npm run benchmark:memory-suite -- --out benchmark-report.json
+   ```
+
+5. Preserve the JSON file with the command, package version, operating system/runtime, and review context that produced it.
+6. When sharing the result publicly, share the generated JSON report only after confirming it still has `public_safe: true` and `schema: "enigma.memory_benchmark_suite.v1"`.
+
+The local fixture measures Enigma-controlled operations only: vault remember/update, vault export/import, passport context-pack retrieval, optimizer token estimates and duplicate removal, bundle/context-pack verification, abstention behavior, exact-answer recall over the deterministic fixture, and p50/p95 operation latency from `performance.now`.
+
+## Local baseline rows in the report
+
+The report now includes `metrics.local_baseline_comparisons`, which compares deterministic local baselines over the same private fixture questions. These rows are local package evidence only: they do not call hosted providers, use provider APIs, or support invoice savings, ROI, compliance, model-forgetting, or benchmark-leadership claims.
+
+| Row | Local boundary |
+| --- | --- |
+| `full_context` | Supplies every active fixture memory without optimization or deduplication. |
+| `recency_last_n` | Supplies the three most recently updated active fixture memories. |
+| `keyword_filter` | Supplies active fixture memories whose content or tags match deterministic query terms. |
+| `enigma_context_pack` | Uses the Enigma passport context-pack compiler and optimizer boundary. |
+
+The report also includes `public_claims_allowed`; keep public copy within those local-fixture boundaries unless separate reviewed external evidence exists.
+
+## How to cite external benchmark standards
+
+Use these standards as citations and task-category references, not as claimed Enigma results unless the exact external benchmark has been run and reviewed:
+
+- LoCoMo: https://snap-research.github.io/locomo/ — cite for long-term conversational-memory QA, event summarization, and multimodal generation over long conversations.
+- LongMemEval: https://arxiv.org/abs/2410.10813 — cite for information extraction, multi-session reasoning, temporal reasoning, knowledge updates, and abstention.
+
+The current local report mirrors some task categories from those benchmarks, but it does not download LoCoMo or LongMemEval data, run their official evaluation pipelines, or claim leaderboard-equivalent results.
+
+## Why live third-party comparisons are not claimed yet
+
+The current benchmark does not call external provider APIs, external SDKs, hosted memory services, ChatGPT native memory, Claude memory tooling, or third-party agent loops. Cross-provider rows in the report are profile labels that reuse the same Enigma context-pack boundary; they do not call or compare live provider models and are not live provider rankings.
+
+Real comparisons require fixed adapters, fixed datasets, fixed agent/tool loops, explicit provider terms review, and reviewed handling of secrets and raw benchmark data. Memory quality can change with the surrounding agent framework and tool loop, so a fair comparison must document more than the memory store.
+
+The current report must not be used as evidence of provider-side deletion, model forgetting, compliance certification, token ROI, provider invoice savings, benchmark leadership, hosted-cloud readiness, or “best in world” superiority.
+
+## External comparison requirements
+
+Use placeholder environment names only. Do not commit real tokens, API keys, account ids, provider transcripts, raw benchmark conversations, or private memory.
+
+The report field `external_competitor_adapters` is a requirements matrix, not a score table. External rows are expected to remain requirements-only until credentials, runtimes, and datasets are supplied and reviewed: `can_run_in_this_harness: false`, `scores_included: false`, and no recall, abstention, token, latency, or ranking scores.
+
+| Target | Runtime or SDK needed | Placeholder secrets and local inputs | Dataset requirement | Adapter boundary before results can be claimed |
+| --- | --- | --- | --- | --- |
+| Letta | Letta SDK/runtime; documented SDK packages include `@letta-ai/letta-client` and `letta-client`; API-key-backed service access may be required. | `LETTA_API_KEY`, `LETTA_BASE_URL`, `LETTA_PROJECT_ID`, `BENCHMARK_DATASET_PATH` | Local reviewed LoCoMo/LongMemEval split or another reviewed local dataset file with license, version, split, and checksum metadata. | Build a Letta adapter that fixes the agent loop, memory write/read policy, model settings, and scoring path. Results may describe that configured Letta run only, not generic provider deletion or model forgetting. |
+| LangGraph memory | LangGraph runtime with short-term checkpointer memory and long-term namespaced store. | `LANGGRAPH_CHECKPOINTER_URI`, `LANGGRAPH_STORE_URI`, `BENCHMARK_DATASET_PATH` | Same local dataset file and split used for Enigma and every competitor. | Fix graph topology, checkpoint scope, namespace policy, retrieval policy, model/tool loop, and scorer. Do not attribute graph/tool behavior solely to the memory store. |
+| Zep | Zep service/runtime positioned around temporal Context Graph and Context Lake retrieval. | `ZEP_API_KEY`, `ZEP_PROJECT_ID`, `ZEP_BASE_URL`, `BENCHMARK_DATASET_PATH` | Same local dataset file and split; include source checksum and whether any provider-side graph state is reused or reset. | Build a Zep adapter that records ingest, session, retrieval, reset, and scoring policy. Zep’s sub-200ms retrieval positioning is a vendor/source fact, not an Enigma-measured claim until measured in the same harness. |
+| Mem0 | Mem0 platform or open-source stack; positioned as a universal self-improving memory layer. | `MEM0_API_KEY`, `MEM0_BASE_URL`, `MEM0_PROJECT_ID`, `BENCHMARK_DATASET_PATH` | Same local dataset file and split; record Mem0 deployment flavor/version. | Build a Mem0 adapter with fixed extraction, update, retrieval, reset, and scorer behavior. Self-improving or platform behavior must be bounded to the configured run. |
+| OpenAI native ChatGPT memory | ChatGPT consumer-app/native memory environment. It is not directly available through a public API in this harness. | No usable harness secret; `OPENAI_API_KEY` alone is not sufficient to exercise ChatGPT native memory. | No fair automated dataset run until an approved interface can load/reset/query native memory reproducibly. | Do not claim live native ChatGPT memory comparison from this repository. A future adapter would need an approved public interface, reproducible memory reset/load semantics, and provider-policy review. |
+| Claude memory tool | Client-side/provider-specific memory tool environment. | `CLAUDE_MEMORY_TOOL_CONFIG`, `ANTHROPIC_API_KEY`, `BENCHMARK_DATASET_PATH` | Same local dataset file and split, plus reviewed tool-state reset/export rules. | Build an adapter around the exact client/tool environment, not generic Claude model behavior. Results can only cover that configured memory-tool setup. |
+
+## Source references for adapter planning
+
+- Letta MemGPT concepts: https://docs.letta.com/concepts/memgpt/
+- Zep documentation: https://help.getzep.com/
+- Mem0 documentation: https://docs.mem0.ai/
+- LangGraph memory documentation: https://docs.langchain.com/oss/python/langgraph/memory
+- OpenAI ChatGPT memory FAQ: https://help.openai.com/en/articles/8590148-memory-faq
+- Claude memory tool support article: https://support.anthropic.com/en/articles/11145838-using-claude-memory
+
+## Minimum evidence for a future live comparison
+
+Before publishing external comparison language, capture all of the following in the benchmark report or an adjacent reviewed evidence file:
+
+1. Package version, benchmark schema, command, timestamp, OS/runtime, and adapter version.
+2. Dataset name, source URL, license review status, local file checksum, split, and record count.
+3. Secret names used as placeholders, with confirmation that no secret values are printed or persisted.
+4. Adapter configuration: SDK/runtime version, model where applicable, memory write/read policy, reset policy, context limits, retry policy, and scoring code.
+5. Per-target raw scoring inputs retained privately when license permits, with public reports limited to safe aggregates.
+6. Explicit boundaries separating memory-store behavior, agent-loop behavior, model behavior, provider-hosted state, and Enigma receipt verification.
+
+Until that evidence exists, use only the local benchmark claim: Enigma can reproduce deterministic local memory-fixture operations and emit a public-safe `enigma.memory_benchmark_suite.v1` JSON report.

package/docs/browser-extension-install.md

@@ -0,0 +1,169 @@
+# Browser extension local install
+
+This guide is for local developer installation only. It does not submit Enigma to Chrome Web Store, Microsoft Edge Add-ons, Mozilla Add-ons, or any external account.
+
+## Boundaries
+
+- The extension is loaded by the user as an unpacked or temporary local extension.
+- The native host is installed by the user and runs on the local machine as `com.enigma.native_host`.
+- Context insertion requires two user clicks: request context, then approve insertion.
+- The extension must not auto-inject context into a provider page.
+- The extension does not use browser sync storage and must not store raw memory in browser storage.
+- Provider-native memory is cache only. The local Enigma bundle/native host remains canonical.
+
+## Package preflight
+
+From the package root, validate the extension before loading or zipping it:
+
+```sh
+node scripts/package-browser-extension.mjs
+```
+
+The command emits public-safe JSON with a deterministic file list, SHA-256 checksums, and safety fields. To also write a deterministic local ZIP for manual inspection or enterprise review:
+
+```sh
+node scripts/package-browser-extension.mjs --zip ./dist/enigma-browser-extension.zip
+```
+
+The ZIP command does not publish, sign, upload, or submit the extension.
+
+## Install the native host first
+
+Install the npm package so both `enigma` and `enigma-native-host` are available:
+
+```sh
+npm install -g enigma-memory
+```
+
+Create or select a local bundle:
+
+```sh
+enigma init --bundle <absolute-bundle-path> --subject local-user --display-name "Local user"
+```
+
+Set `ENIGMA_BUNDLE` for the browser-launched host process, or point the native-host manifest at a small local wrapper that sets `ENIGMA_BUNDLE=<absolute-bundle-path>` before launching `enigma-native-host`. Native messaging manifests require an absolute executable path; they do not expand shell aliases, `~`, `$HOME`, `%USERPROFILE%`, or command arguments.
+
+Resolve the absolute host executable path:
+
+```sh
+command -v enigma-native-host
+```
+
+Windows PowerShell:
+
+```powershell
+(Get-Command enigma-native-host.cmd).Source
+```
+
+## Load the extension locally
+
+### Chrome
+
+1. Open `chrome://extensions`.
+2. Enable **Developer mode**.
+3. Select **Load unpacked**.
+4. Choose `enigma/apps/browser-extension`.
+5. Open the Enigma extension details and copy the 32-character extension ID.
+
+### Microsoft Edge
+
+1. Open `edge://extensions`.
+2. Enable **Developer mode**.
+3. Select **Load unpacked**.
+4. Choose `enigma/apps/browser-extension`.
+5. Open the Enigma extension details and copy the 32-character extension ID.
+
+### Firefox
+
+1. Open `about:debugging#/runtime/this-firefox`.
+2. Select **Load Temporary Add-on**.
+3. Choose `enigma/apps/browser-extension/manifest.json`.
+4. Copy the temporary extension ID shown by Firefox. For repeatable development, use a stable development add-on ID and pass the same value to the native-host manifest generator.
+
+## Generate the browser native-host manifest
+
+Generate a manifest after you know the extension ID and absolute host path.
+
+Chrome:
+
+```sh
+enigma native-host manifest \
+  --browser chrome \
+  --host-path <absolute-enigma-native-host-path> \
+  --extension-id <chrome-extension-id> \
+  --out ./com.enigma.native_host.json
+```
+
+Edge:
+
+```sh
+enigma native-host manifest \
+  --browser edge \
+  --host-path <absolute-enigma-native-host-path> \
+  --extension-id <edge-extension-id> \
+  --out ./com.enigma.native_host.json
+```
+
+Firefox:
+
+```sh
+enigma native-host manifest \
+  --browser firefox \
+  --host-path <absolute-enigma-native-host-path> \
+  --extension-id <firefox-extension-id> \
+  --out ./com.enigma.native_host.json
+```
+
+Preview browser-specific install locations without mutating registry or profile state:
+
+```sh
+enigma native-host install-plan \
+  --browser chrome \
+  --manifest <absolute-path-to-com.enigma.native_host.json>
+```
+
+Use `--browser edge` or `--browser firefox` for the other browsers. The install plan is a checklist: it does not copy manifests, write registry keys, or change browser profiles. Copy the generated manifest to the listed native messaging host location yourself, and on Windows review and run the listed registry command only when you are ready to register `com.enigma.native_host`.
+
+## Register the native-host manifest locally
+
+Use the paths from `enigma native-host install-plan` as the source of truth. These are the common manual targets:
+
+### Chrome native host
+
+- macOS per-user: `<home>/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.enigma.native_host.json`
+- Linux per-user: `<home>/.config/google-chrome/NativeMessagingHosts/com.enigma.native_host.json`
+- Windows per-user: copy the manifest to an operator-chosen local file, then set `HKCU\Software\Google\Chrome\NativeMessagingHosts\com.enigma.native_host` to that manifest path.
+
+### Microsoft Edge native host
+
+- macOS per-user: `<home>/Library/Application Support/Microsoft Edge/NativeMessagingHosts/com.enigma.native_host.json`
+- Linux per-user: `<home>/.config/microsoft-edge/NativeMessagingHosts/com.enigma.native_host.json`
+- Windows per-user: copy the manifest to an operator-chosen local file, then set `HKCU\Software\Microsoft\Edge\NativeMessagingHosts\com.enigma.native_host` to that manifest path.
+
+### Firefox native host
+
+- macOS per-user: `<home>/Library/Application Support/Mozilla/NativeMessagingHosts/com.enigma.native_host.json`
+- Linux per-user: `<home>/.mozilla/native-messaging-hosts/com.enigma.native_host.json`
+- Windows per-user: copy the manifest to an operator-chosen local file, then set `HKCU\Software\Mozilla\NativeMessagingHosts\com.enigma.native_host` to that manifest path.
+
+All-users locations and registry hives are operator-managed deployment choices. Local developer install should prefer per-user targets unless an enterprise policy requires otherwise.
+
+## Local insertion demo flow
+
+1. Confirm the native-host manifest allowlist uses the extension ID from the local browser profile.
+2. Restart the browser after native-host registration so it can discover `com.enigma.native_host`.
+3. Visit a supported HTTPS provider page: ChatGPT, Claude, Kimi, or Perplexity.
+4. Open the Enigma control shown by the content script.
+5. Click **Request context**. The extension asks the local native host for a transient context pack; selected page text is included only if the user explicitly enables it for that request.
+6. Review the returned context in the panel.
+7. Click **Approve and insert** to insert plain text into the active prompt surface.
+8. Submit to the provider only if you choose to. Enigma does not submit prompts for you.
+
+After insertion, the extension records only target metadata, insertion timestamp, receipt metadata, and insertion counts. It must not write raw memory, context plaintext, or receipt plaintext into browser sync storage or public artifacts.
+
+## Troubleshooting
+
+- **Host not found**: confirm the manifest filename is `com.enigma.native_host.json`, the manifest `name` is `com.enigma.native_host`, and the browser-specific install location or registry key points to the manifest.
+- **Host exits immediately**: confirm `ENIGMA_BUNDLE` is visible to the browser-launched process or use a local wrapper that sets it before launching `enigma-native-host`.
+- **Extension cannot connect**: confirm the extension ID in the native-host manifest matches the locally loaded extension.
+- **No insertion happens**: confirm you clicked both **Request context** and **Approve and insert**. The extension intentionally does not auto-inject.

package/docs/developer-ecosystem.md

@@ -0,0 +1,76 @@
+# Developer ecosystem
+
+Enigma Memory is a local-first SDK, CLI, MCP server, and service-contract package. The developer surfaces are designed to be copied without secrets, cloud credentials, hidden local paths, or account identifiers.
+
+## Copyable starting points
+
+- SDK/API guide: [`docs/sdk-api.md`](./sdk-api.md)
+- Node example app: [`examples/node-basic-memory.mjs`](../examples/node-basic-memory.mjs)
+- GitHub Actions example: [`examples/ci/github-actions.yml`](../examples/ci/github-actions.yml)
+- Benchmark reproducibility guide: [`docs/benchmark-reproducibility.md`](./benchmark-reproducibility.md)
+- Generic MCP client template: [`templates/mcp-client-config.json`](../templates/mcp-client-config.json)
+
+## Local SDK loop
+
+Use the SDK when you want an app-owned vault and receipt-backed proof loop:
+
+1. Create a local vault with `createVault`.
+2. Add a generic, non-private memory with `remember`.
+3. Create a passport with `createPassport`.
+4. Compile a receipt-backed context pack with `compileContextPack`.
+5. Export a proof-carrying bundle with `exportBundle`; keep full bundles private unless local import key material has been reviewed and removed.
+6. Verify receipts with `verifyReceiptChain`, `enigma verify`, `enigma-verify`, or MCP `enigma_verify_receipts`.
+
+The example app prints ids, counts, roots, and verification status only. It does not print raw memory text, generated key material, credentials, provider transcripts, or local absolute paths.
+
+## CLI and CI loop
+
+The CI example installs Node 24, installs the published `enigma-memory@0.1.3` package, runs:
+
+```sh
+npx enigma quickstart --overwrite
+npx enigma doctor
+npm run benchmark:memory-suite -- --out benchmark-report.json
+```
+
+and then runs a small ESM import smoke. It does not require GitHub secrets, cloud provider credentials, npm tokens, private bundles, or local path assumptions. The benchmark step writes a public-safe local JSON report using schema `enigma.memory_benchmark_suite.v1`; see the benchmark reproducibility guide for claim boundaries and the requirements for any future live third-party comparison.
+
+Use the workflow as a template in a consumer repository. It is intentionally limited to install/import/doctor smoke coverage, local proof generation, and deterministic local benchmark evidence; it does not publish packages, deploy infrastructure, contact hosted Enigma cloud, or call external memory providers.
+
+## MCP client loop
+
+The generic MCP template uses the installed `enigma-mcp` command and exactly one environment placeholder:
+
+```json
+{
+  "mcpServers": {
+    "enigma": {
+      "command": "enigma-mcp",
+      "env": {
+        "ENIGMA_BUNDLE": "<ENIGMA_BUNDLE>"
+      }
+    }
+  }
+}
+```
+
+Replace `<ENIGMA_BUNDLE>` with the bundle file you control, or with the client-specific environment expansion syntax if your MCP client supports it. Do not commit private bundle paths if they reveal local usernames, workspace names, account ids, or other personal details.
+
+## Claim boundaries for developers
+
+Enigma proof artifacts cover Enigma-controlled or Enigma-mediated state: local vault events, receipts, active/tombstoned memory addresses, context-pack retrieval/injection receipts, relay/gateway records, usage events, and settlement receipts.
+
+They do not prove:
+
+- provider-side deletion;
+- model forgetting;
+- compliance certification;
+- token ROI, investment outcome, or provider invoice savings;
+- hosted-cloud readiness from a local demo;
+- benchmark leadership from SDK mechanics alone.
+
+Benchmark claims require benchmark-specific evidence. LoCoMo covers long-term conversational memory QA, event summarization, and multimodal generation across long conversations. LongMemEval covers extraction, multi-session reasoning, temporal reasoning, knowledge updates, and abstention. Agent-memory benchmark results can depend heavily on the agent/framework/tool loop, not only on the memory store. Keep those distinctions when writing integrations or public copy.
+
+## What to keep out of examples
+
+Do not add secrets, tokens, 2FA codes, cloud account ids, personal data, provider transcripts, raw private memory, absolute local paths, or unreviewed hosted endpoints to examples/templates. Public-safe examples should use generic ids, relative paths, placeholders, hashes, commitments, counts, receipt ids, and roots.

package/docs/hosted-cloud-product.md

@@ -0,0 +1,68 @@
+# Hosted cloud product contract
+
+This document separates the hosted-cloud product contract surface from the external systems still required before Enigma can sell or operate a hosted cloud service.
+
+## Production contract-ready now
+
+The source package now has pure contract builders and validators in `packages/hosted-cloud/src/index.js` for:
+
+- user account records;
+- tenant records;
+- hosted vault records;
+- API key metadata records;
+- usage billing records;
+- dashboard summaries;
+- backup drill records;
+- incident and SLA reference records.
+
+These functions are contract and validation code only. They do not call an auth provider, billing provider, cloud deployment, KMS, backup target, support desk, status page, SIEM, or model provider. They are safe to import as package code because they do not start servers, read user files, mutate deployment state, publish packages, or contact external accounts.
+
+The validators enforce hosted-cloud boundaries:
+
+- contract artifacts must include `operator_evidence_refs` for auth provider, billing provider, legal docs, data processing terms, support ownership, and external security review;
+- missing operator evidence references are rejected;
+- raw memory, plaintext prompts, provider responses, transcripts, credential-looking values, token values, private keys, and API key secret material are rejected;
+- financial outcome claims, token ROI/profit claims, provider-side deletion claims, and model-forgetting claims are rejected;
+- API key contracts store identifiers, fingerprints, scopes, rotation refs, and timestamps only, not key material;
+- hosted vault contracts are opaque-record and plaintext-minimized contracts only;
+- billing records remain contract records until an external billing provider invoice flow is wired.
+
+Every builder emits `readiness.contract_ready: true` and `readiness.integration_kind: "contract_validator_only"`. It also emits `readiness.hosted_cloud_sellable: false` because contract readiness is not provider wiring, legal approval, security review, or operator go-live approval.
+
+## Externally blocked before hosted cloud can be sold
+
+Hosted cloud remains blocked until an operator wires and records evidence for all of the following:
+
+| Blocker | Required before selling hosted cloud |
+| --- | --- |
+| Auth provider | A real auth provider, tenant/user lifecycle, access-control rules, session/token handling, rotation, revocation, and audit evidence. |
+| Billing provider | A real billing provider, customer/subscription mapping, invoice lifecycle, tax/legal handling, dunning/refund policy, and reconciliation evidence. |
+| Legal docs | Approved hosted terms, privacy notice, service descriptions, acceptable-use terms, retention/deletion language, and claim review. |
+| Data processing terms | Approved DPA or equivalent data-processing terms, subprocessors, data residency, retention, deletion, legal hold, and customer notice process. |
+| Support ownership | Named support owner, escalation policy, incident owner, response process, status communication process, and support tooling. |
+| External security review | External security review or audit scope, remediation tracking, approval record, and release sign-off. |
+
+A `provided` operator evidence ref means the contract can point to external evidence. It still does not by itself make hosted cloud sellable; an operator must complete the release checklist and issue go-live approval. A `blocked_external_dependency` ref is an explicit blocker, not fake evidence.
+
+## Non-claims
+
+Hosted cloud collateral must not say or imply:
+
+- Enigma has live hosted cloud tenants before provider wiring and operator acceptance exist;
+- Enigma has made any model or provider forget data;
+- Enigma has provider-side deletion proof;
+- Enigma guarantees ROI, profit, investment return, token price movement, or invoice savings;
+- Enigma has SOC 2, HIPAA, GDPR, or other compliance certification unless separately audited and approved;
+- local/package evidence, contract validation, static docs, or dashboard summaries are live service evidence.
+
+Safe wording:
+
+```text
+Enigma has hosted-cloud contract builders and validators for account, tenant, vault, API key, billing, dashboard, backup drill, and incident/SLA records. Hosted cloud remains blocked until auth, billing, legal/data-processing terms, support ownership, external security review, and operator go-live evidence are complete.
+```
+
+Avoid wording:
+
+```text
+Enigma hosted cloud is ready to sell because the contracts exist.
+```