enigma-memory 0.1.17 → 0.1.22

package/docs/install-anywhere.md

@@ -1,13 +1,12 @@
 # Install Enigma anywhere
 
 Start with the published npm package path for `enigma-memory`: install once, connect your installed AI clients, then inspect Memory Drive health and passport status. Use a source checkout only when you need source-only docs, Docker assets, browser-extension scaffolding, package development, or release scripts.
-
-Hosted cloud and BYOC operation require real deployment credentials, domains, TLS, durable storage, KMS/secrets, monitoring, backups, and operator/customer infrastructure; they are not activated by installing the package, running setup, or running the test drive.
+Hosted cloud and BYOC operation are waitlist/operator-deploy only; they require real deployment credentials, domains, TLS, durable storage, KMS/secrets, monitoring, backups, and operator/customer infrastructure. The relay and gateway binaries included in the package are local bootstrap probes, not a live hosted service. They are not activated by installing the package, running setup, or running the test drive.
 
 ## Requirements
 
 - Node.js `>=24`
-- A local filesystem path for the Enigma vault bundle
+- A local filesystem path for the Enigma vault bundle and a passphrase supplied through `ENIGMA_PASSPHRASE` or a user-readable-only passphrase file
 - No database, provider credential, cloud credential, npm publishing token, package registry account, or hosted Enigma account for the local test-drive or setup paths
 - Git only for the advanced source-checkout path
 - Optional: Docker for source-checkout containerized relay/gateway operation
@@ -18,17 +17,42 @@ Use the published package as the primary path:
 
 ```sh
 npm install -g enigma-memory
-enigma init
-enigma setup --client auto --connect-installed --overwrite
-enigma drive health
-enigma status
-enigma remember --text-file ./memory.txt
-enigma search --query "project context"
-enigma context --query "project context" --optimize
+PASSPHRASE_FILE="$HOME/.enigma/passphrase"
+test -s "$PASSPHRASE_FILE" || { printf '%s\n' 'Create $HOME/.enigma/passphrase with an approved secret manager or secure editor, then restrict it to the current user.' >&2; exit 1; }
+enigma init --passphrase-file "$PASSPHRASE_FILE"
+enigma setup --passphrase-file "$PASSPHRASE_FILE" --client auto --connect-installed --overwrite
+enigma drive health --passphrase-file "$PASSPHRASE_FILE"
+enigma status --passphrase-file "$PASSPHRASE_FILE"
+enigma remember --passphrase-file "$PASSPHRASE_FILE" --text-file ./memory.txt
+enigma search --passphrase-file "$PASSPHRASE_FILE" --query "project context"
+enigma context --passphrase-file "$PASSPHRASE_FILE" --query "project context" --optimize
 enigma verify --export ./.enigma/export.json
 ```
 
-`enigma init` is the credential-free first run that creates the local `.enigma` workspace, bundle, and proof artifacts. `enigma setup --client auto --connect-installed --overwrite` then configures the drive and writes the `mcpServers.enigma` entry into every installed/config-present client it detects; it skips clients that are not installed and never creates configs from scratch. Preview with `--dry-run` first to see which clients will be written. Both commands emit deterministic, public-safe JSON without printing raw memory plaintext, and both run on Windows PowerShell via the `enigma.cmd` shim the npm global install adds.
+`enigma init` is the encrypted first run: it requires `ENIGMA_PASSPHRASE` or `--passphrase-file`, then creates the local `.enigma` workspace, encrypted bundle, and proof artifacts. `enigma setup --passphrase-file "$HOME/.enigma/passphrase" --client auto --connect-installed --overwrite` configures the drive and writes the `mcpServers.enigma` entry into every installed/config-present client it detects; it skips clients that are not installed and never creates configs from scratch. Preview with `--dry-run` first to see which clients will be written. Both commands emit deterministic, public-safe JSON without printing raw memory plaintext, and both run on Windows PowerShell via the `enigma.cmd` shim the npm global install adds.
+
+### Keyring Security & At-Rest Confidentiality Note
+
+- **Encrypted default (`local_secret_encrypted`)**: Normal `enigma init`, `enigma setup`, and `enigma quickstart` require `ENIGMA_PASSPHRASE` or `--passphrase-file <path>`. Prefer a user-readable-only file created through an approved secret manager or secure editor; never put the passphrase itself in command arguments.
+- **Insecure evaluation mode (`local_secret`)**: `--insecure-dev` is an explicit, **INSECURE, EVALUATION-ONLY** escape hatch for disposable data. It stores an unencrypted keyring (`unencrypted: true`), provides no at-rest confidentiality, and must not be used for normal or persistent data.
+
+Encrypted + Solana-connected package path:
+
+```sh
+npm install -g enigma-memory
+PASSPHRASE_FILE="$HOME/.enigma/passphrase"
+test -s "$PASSPHRASE_FILE" || { printf '%s\n' 'Create $HOME/.enigma/passphrase securely before continuing.' >&2; exit 1; }
+enigma quickstart --bundle "$HOME/.enigma/bundle.json" --passphrase-file "$PASSPHRASE_FILE" --overwrite
+enigma-terminal --exec "solana status --cluster devnet"
+enigma chain anchor-bundle --bundle "$HOME/.enigma/bundle.json" --cluster devnet --out "$HOME/.enigma/anchor-batch.json"
+enigma chain submit-solana --file "$HOME/.enigma/anchor-batch.json" --cluster devnet
+```
+
+The final command is a Solana Memo dry-run by default. To write on-chain, pass `--execute --keypair <funded-solana-cli-keypair.json>`. The memo payload is a compact public proof reference derived from local bundle commitment roots; raw memory, prompts, key material, passphrases, and bundle ciphertext are never placed on-chain.
+
+Run setup or quickstart before treating `enigma doctor` as a fully green install check. Doctor checks Node/package state, local paths, schemas, MCP command naming, and connector configs. On a fresh install it can return `ok:false` when an existing MCP client config points at a bundle that has not been initialized yet, or at a different bundle than the one you are checking. That is expected first-run state, not a package install failure. After securely creating `./.enigma/passphrase`, run `enigma quickstart --bundle ./.enigma/bundle.json --passphrase-file ./.enigma/passphrase --overwrite` or `enigma setup --bundle ./.enigma/bundle.json --passphrase-file ./.enigma/passphrase --overwrite`, then `enigma doctor --bundle ./.enigma/bundle.json`.
+
+For the one-off npm path, create the same protected passphrase file, then run `npx --yes --package enigma-memory enigma quickstart --bundle ./.enigma/bundle.json --passphrase-file ./.enigma/passphrase --overwrite` before `npx --yes --package enigma-memory enigma doctor --bundle ./.enigma/bundle.json`. Running npx doctor first can report a red generic-MCP connector if an existing client config names a not-yet-created bundle.
 
 `enigma drive health` reports a SMART-style memory-drive health packet — freshness, duplicate rate, tombstone backlog, stale derived artifacts, receipt coverage, and connector health — from local metadata only, with no network calls or private payloads. It is part of the Memory Drive surface in this release; `enigma status` and `enigma doctor` cover local passport counts, roots, and connector readiness in every build.
 
@@ -37,8 +61,9 @@ The local Enigma vault is the canonical memory passport. Provider-native memory
 Optional public test drive without a global install:
 
 ```sh
-npx --yes --package enigma-memory enigma test-drive --overwrite
+npx --yes --package enigma-memory enigma test-drive --insecure-dev --overwrite
 ```
+This command is **INSECURE, EVALUATION ONLY**: the isolated test drive is disposable and has no at-rest confidentiality. Normal setup uses an encrypted passphrase file as shown above.
 
 ## Source checkout versus package install
 
@@ -52,7 +77,7 @@ From the repository root, use the local installer in preview mode first:
 
 ```sh
 npm run install:local
-npm run install:local -- --init-vault --bundle ./.enigma/bundle.json
+npm run install:local -- --init-vault --bundle ./.enigma/bundle.json --passphrase-file ./.enigma/passphrase
 ```
 
 `install:local` is dry-run by default. It validates Node.js `>=24`, resolves the local bundle path, previews `npm install -g .`, and emits public-safe JSON without printing local absolute paths, credentials, account IDs, or memory plaintext. It does not mutate global npm state or create a vault unless you explicitly request execute mode.
@@ -60,8 +85,9 @@ npm run install:local -- --init-vault --bundle ./.enigma/bundle.json
 To perform the local global install from the checkout and initialize a local vault bundle:
 
 ```sh
-npm run install:local -- --execute --init-vault --bundle ./.enigma/bundle.json
-enigma doctor
+test -s ./.enigma/passphrase || { printf '%s\n' 'Create ./.enigma/passphrase securely before continuing.' >&2; exit 1; }
+npm run install:local -- --execute --init-vault --bundle ./.enigma/bundle.json --passphrase-file ./.enigma/passphrase
+enigma doctor --bundle ./.enigma/bundle.json
 enigma --help
 enigma demo cross-model
 enigma-verify --help
@@ -73,8 +99,8 @@ Equivalent explicit source-checkout steps:
 
 ```sh
 npm install -g .
-enigma init --bundle ./.enigma/bundle.json --subject local-user --display-name "Local user"
-enigma doctor
+enigma init --bundle ./.enigma/bundle.json --passphrase-file ./.enigma/passphrase --subject local-user --display-name "Local user"
+enigma doctor --bundle ./.enigma/bundle.json
 enigma --help
 enigma demo cross-model
 enigma-verify --help
@@ -100,10 +126,12 @@ Use this when you want to inspect each step behind the setup-first path:
 mkdir -p .enigma
 ENIGMA_DEMO_MEMORY_FILE=/absolute/path/to/tenant-approved-smoke-memory.txt
 test -f "$ENIGMA_DEMO_MEMORY_FILE"
-enigma init --bundle ./.enigma/bundle.json --subject local-user --display-name "Local user"
-enigma remember --bundle ./.enigma/bundle.json --text-file "$ENIGMA_DEMO_MEMORY_FILE" --purpose user_memory --tags local
-enigma context --bundle ./.enigma/bundle.json --query "local context" --purpose local_context --out ./.enigma/context-pack.json
-enigma export --bundle ./.enigma/bundle.json --out ./.enigma/export.json
+ENIGMA_PASSPHRASE_FILE=./.enigma/passphrase
+test -s "$ENIGMA_PASSPHRASE_FILE" || { printf '%s\n' 'Create ./.enigma/passphrase securely before continuing.' >&2; exit 1; }
+enigma init --bundle ./.enigma/bundle.json --passphrase-file "$ENIGMA_PASSPHRASE_FILE" --subject local-user --display-name "Local user"
+enigma remember --bundle ./.enigma/bundle.json --passphrase-file "$ENIGMA_PASSPHRASE_FILE" --text-file "$ENIGMA_DEMO_MEMORY_FILE" --purpose user_memory --tags local
+enigma context --bundle ./.enigma/bundle.json --passphrase-file "$ENIGMA_PASSPHRASE_FILE" --query "local context" --purpose local_context --out ./.enigma/context-pack.json
+enigma export --bundle ./.enigma/bundle.json --passphrase-file "$ENIGMA_PASSPHRASE_FILE" --out ./.enigma/export.json
 enigma verify --export ./.enigma/export.json
 ```
 
@@ -113,10 +141,12 @@ Windows PowerShell equivalent:
 New-Item -ItemType Directory -Force .enigma
 $env:ENIGMA_DEMO_MEMORY_FILE='C:\path\to\tenant-approved-smoke-memory.txt'
 if (-not (Test-Path $env:ENIGMA_DEMO_MEMORY_FILE)) { throw 'Set ENIGMA_DEMO_MEMORY_FILE to a tenant-approved smoke file first.' }
-enigma init --bundle .\.enigma\bundle.json --subject local-user --display-name "Local user"
-enigma remember --bundle .\.enigma\bundle.json --text-file $env:ENIGMA_DEMO_MEMORY_FILE --purpose user_memory --tags local
-enigma context --bundle .\.enigma\bundle.json --query "local context" --purpose local_context --out .\.enigma\context-pack.json
-enigma export --bundle .\.enigma\bundle.json --out .\.enigma\export.json
+$env:ENIGMA_PASSPHRASE_FILE='.\.enigma\passphrase'
+if (-not (Test-Path -LiteralPath $env:ENIGMA_PASSPHRASE_FILE -PathType Leaf)) { throw 'Create the passphrase file securely before continuing.' }
+enigma init --bundle .\.enigma\bundle.json --passphrase-file $env:ENIGMA_PASSPHRASE_FILE --subject local-user --display-name "Local user"
+enigma remember --bundle .\.enigma\bundle.json --passphrase-file $env:ENIGMA_PASSPHRASE_FILE --text-file $env:ENIGMA_DEMO_MEMORY_FILE --purpose user_memory --tags local
+enigma context --bundle .\.enigma\bundle.json --passphrase-file $env:ENIGMA_PASSPHRASE_FILE --query "local context" --purpose local_context --out .\.enigma\context-pack.json
+enigma export --bundle .\.enigma\bundle.json --passphrase-file $env:ENIGMA_PASSPHRASE_FILE --out .\.enigma\export.json
 enigma verify --export .\.enigma\export.json
 ```
 
@@ -181,7 +211,7 @@ Npm-first connector flow — one command connects every installed/config-present
 
 ```sh
 npm install -g enigma-memory
-enigma setup --client auto --connect-installed --overwrite
+enigma setup --passphrase-file "$HOME/.enigma/passphrase" --client auto --connect-installed --overwrite
 ```
 
 `--connect-installed` detects installed/config-present clients (Claude Desktop, Cursor, Kimi Code, VS Code/Cline, Roo, OpenCode, generic MCP) and writes only those existing client configs; missing client configs are reported and skipped. To preview a single client without writing, or to connect just one client later, use `enigma connect <client> --dry-run` and then drop `--dry-run`.
@@ -473,6 +503,8 @@ Run it from the public-site package/artifact root after building or obtaining `_
 
 ## Enterprise hosted and BYOC modes
 
+Both modes are waitlist/operator-deploy only. The relay and gateway binaries are local bootstrap probes; production hosted or BYOC operation requires real deployment credentials, domain/TLS, durable storage, KMS/secrets, monitoring, backups, incident response, and operator acceptance.
+
 Hosted mode:
 
 - Enigma operator deploys relay/gateway for the tenant.
@@ -501,9 +533,11 @@ CLI/verifier:
 ```sh
 ENIGMA_DEMO_MEMORY_FILE=/absolute/path/to/tenant-approved-smoke-memory.txt
 test -f "$ENIGMA_DEMO_MEMORY_FILE"
-enigma init --bundle ./.enigma/bundle.json
-enigma remember --bundle ./.enigma/bundle.json --text-file "$ENIGMA_DEMO_MEMORY_FILE" --purpose verification
-enigma export --bundle ./.enigma/bundle.json --out ./.enigma/export.json
+ENIGMA_PASSPHRASE_FILE=./.enigma/passphrase
+test -s "$ENIGMA_PASSPHRASE_FILE" || { printf '%s\n' 'Create ./.enigma/passphrase securely before continuing.' >&2; exit 1; }
+enigma init --bundle ./.enigma/bundle.json --passphrase-file "$ENIGMA_PASSPHRASE_FILE"
+enigma remember --bundle ./.enigma/bundle.json --passphrase-file "$ENIGMA_PASSPHRASE_FILE" --text-file "$ENIGMA_DEMO_MEMORY_FILE" --purpose verification
+enigma export --bundle ./.enigma/bundle.json --passphrase-file "$ENIGMA_PASSPHRASE_FILE" --out ./.enigma/export.json
 enigma verify --export ./.enigma/export.json
 ```
 
@@ -516,7 +550,7 @@ printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion
 Connector/importer/relay/gateway checks:
 
 ```sh
-enigma doctor
+enigma doctor --bundle ./.enigma/bundle.json
 enigma import chatgpt --file ./chatgpt-export.json --out ./enigma-import-report.json
 enigma capsule export --file ./enigma-import-report.json --out ./enigma-capsule.json
 enigma capsule import --file ./enigma-capsule.json --bundle "$PWD/.enigma/bundle.json"

package/docs/installers-and-desktop.md

@@ -8,13 +8,14 @@ Use the published package path when you want the current supported local install
 
 ```sh
 npm install -g enigma-memory
-enigma test-drive --dry-run
-enigma setup --overwrite
+test -s "$HOME/.enigma/passphrase" || { printf '%s\n' 'Create the protected passphrase file before setup.' >&2; exit 1; }
+enigma test-drive --dry-run --insecure-dev # INSECURE, EVALUATION ONLY
+enigma setup --passphrase-file "$HOME/.enigma/passphrase" --overwrite
 enigma doctor
 enigma connect <client> --dry-run
 ```
 
-The package exposes the CLI bins `enigma`, `enigma-verify`, `enigma-mcp`, `enigma-relay`, `enigma-gateway`, and `enigma-native-host`. Node.js `>=24` is required. The installer smoke path keeps `enigma test-drive --dry-run` and `enigma connect <client> --dry-run` non-mutating; `enigma setup --overwrite` writes Enigma-controlled local artifacts only and does not write third-party app configs. It does not prove provider deletion, model forgetting, hosted availability, compliance certification, savings, or provider-native memory removal.
+The package exposes the CLI bins `enigma`, `enigma-verify`, `enigma-mcp`, `enigma-relay`, `enigma-gateway`, and `enigma-native-host`. Node.js `>=24` is required. The installer smoke path labels `enigma test-drive --dry-run --insecure-dev` as **INSECURE, EVALUATION ONLY**; normal `enigma setup --passphrase-file "$HOME/.enigma/passphrase" --overwrite` writes an encrypted Enigma-controlled bundle and does not write third-party app configs. It does not prove provider deletion, model forgetting, hosted availability, compliance certification, savings, or provider-native memory removal.
 
 ## Tier 2: generated source installer assets
 
@@ -32,9 +33,9 @@ node scripts/build-installer-assets.mjs --out-dir dist/installer-assets --write
 
 Generated asset paths are listed in deterministic code-point lexical order:
 
-- `homebrew/enigma-memory.rb` — Homebrew formula draft. It is not submitted to a tap by the generator; release engineering must replace the source archive URL and SHA before any tap workflow. Its test metadata exercises `enigma test-drive --dry-run`, `enigma setup --dry-run`, and `enigma doctor`, then prints the next client-connect preview command.
-- `install-linux.sh` — POSIX shell source installer. It previews by default and only mutates global npm/local setup files when called with `--execute`. Its preview includes package install, `enigma test-drive --dry-run`, `enigma setup --bundle <bundle> --overwrite`, `enigma doctor`, and `enigma connect <client> --dry-run` as the next client-connect command.
-- `install-windows.ps1` — PowerShell source installer. It previews by default and only runs `npm install -g enigma-memory`, `enigma test-drive --dry-run`, `enigma setup --bundle <bundle> --overwrite`, and `enigma doctor` when called with `-Execute`; it then prints `enigma connect <client> --dry-run` as the next client-connect command.
+- `homebrew/enigma-memory.rb` — Homebrew formula draft. Its disposable test metadata uses explicit `--insecure-dev` and labels it **INSECURE, EVALUATION ONLY**; normal setup documentation requires a passphrase file.
+- `install-linux.sh` — POSIX shell source installer. It previews by default and only mutates global npm/local setup files when called with `--execute`. Execute mode requires `--passphrase-file <path>` (default `./.enigma/passphrase`) and passes it explicitly to encrypted setup.
+- `install-windows.ps1` — PowerShell source installer. It previews by default and only runs setup with `-Execute`; execute mode requires a non-empty `-PassphraseFile` (default `.\.enigma\passphrase`) and passes it explicitly to encrypted setup.
 - `installer-assets-manifest.json` — deterministic public manifest with checksums for the generated source assets.
 - `macos-pkgbuild/README.md` — macOS package source plan and blockers, not a signed package.
 - `macos-pkgbuild/manifest.json` — macOS package source metadata and blockers, not a signed package.
@@ -62,7 +63,7 @@ Until those blockers are cleared, use npm or generated source scripts only.
 
 ## Homebrew path
 
-The formula generated under `homebrew/enigma-memory.rb` is a draft for a future tap workflow. It records the intended package name, license, Node dependency, command shims, and installer smoke test shape: `enigma test-drive --dry-run`, `enigma setup --dry-run`, `enigma doctor`, and the printed next command `enigma connect <client> --dry-run`. Before publication, release engineering must replace the placeholder tarball URL and SHA with a real release archive and confirm the formula installs only the intended package files.
+The formula generated under `homebrew/enigma-memory.rb` is a draft for a future tap workflow. It records the intended package name, license, Node dependency, command shims, and installer smoke shape. Formula-only dry runs use explicit `--insecure-dev` and are labeled **INSECURE, EVALUATION ONLY**; normal setup uses `--passphrase-file "$HOME/.enigma/passphrase"`. Before publication, release engineering must replace the placeholder tarball URL and SHA with a real release archive and confirm the formula installs only the intended package files.
 
 ## Desktop tray model boundary
 

package/docs/memory-benchmarks.md

@@ -35,7 +35,7 @@ The fixture harness does not download or run LoCoMo, LongMemEval, provider APIs,
 
 The fixture creates multiple sessions with facts, a knowledge update, temporal questions, an abstention question, duplicate memory candidates, and provider profile labels for `chatgpt`, `claude`, `kimi`, `cursor`, and `local-llm`.
 
-The harness measures local Enigma operations only:
+The harness measures local Enigma operations only. The runtime `enigma search` and context-pack retrieval in this release use deterministic keyword token overlap only; no embedding model, vector index, or LLM is called.
 
 - vault remember/update operations;
 - vault export and import;