memory-crystal 0.2.0

package/ai/plan/memory-crystal-phase2-plan.md

@@ -0,0 +1,192 @@
+# ~~Memory Crystal Phase 2 — Cloudflare Worker + Multi-Agent Setup~~
+
+> **SUPERSEDED** — This plan was replaced by the ephemeral relay architecture on 2026-02-25.
+> See `phase2-ephemeral-relay.md` for the current design.
+> The cloud-mirror approach (D1 + Vectorize + search on Worker) was abandoned in favor of
+> a blind dead drop with client-side encryption. The Worker has no database, no search,
+> no ability to read the data it holds.
+
+**Date:** 2026-02-25
+**Agent:** cc-mba (Claude Code on MacBook Air)
+**Repo:** `memory-crystal` → branch `cc-mba/phase2-worker` (superseded by `cc-air/phase2-relay`)
+
+## The Problem
+
+Three agents need shared memory:
+- **cc-a** — Claude Code on MacBook Air (this machine)
+- **cc** — Claude Code on Mac Mini
+- **Lesa** — OpenClaw agent on Mac Mini
+
+Today, memory-crystal runs locally on the Mac Mini. cc and Lesa share `crystal.db` directly. cc-a (me) has no access to that database. The bridge (`lesa-bridge`) only works localhost — it can't reach across machines.
+
+## The Solution
+
+Build the Cloudflare Worker mirror that's already specced in `PLAN.md`. This gives all three agents a shared memory layer via HTTPS, with the Mac Mini remaining source of truth.
+
+```
+cc-a (MacBook Air)  ──HTTPS──→  Cloudflare Worker  ←──HTTPS──  cc (Mac Mini)
+                                      ↕
+                                 Lesa (Mac Mini)
+                                      ↕
+                              Mac Mini pulls daily
+                              (source of truth)
+```
+
+## Architecture
+
+### Cloudflare Stack
+- **Worker** — REST API (`/search`, `/remember`, `/ingest`, `/health`, `/status`)
+- **D1** — SQLite database (chunks, memories, metadata)
+- **Vectorize** — Vector index for semantic search
+- **R2** — Snapshot storage for daily sync from Mini
+
+### Sync Model
+1. **04:00 daily** — Mini exports `crystal.db` snapshot → R2
+2. **04:05** — Worker rebuilds D1 + Vectorize from snapshot
+3. **All day** — All agents read/write via Worker
+4. **Every 4-6h** — Mini pulls new remote writes
+5. **Breach protocol** — `wrangler delete` nukes everything. Mini untouched.
+
+### Auth
+- Bearer token per agent (stored in 1Password)
+- Tokens: `cc-a`, `cc`, `lesa` — each identified in requests
+- Worker validates token + extracts agent_id
+
+### Security
+- Worker → Mini: NEVER (Mini pulls, Worker never pushes)
+- Mini → Worker: HTTPS only
+- R2: private, Worker-binding only
+- All tokens in 1Password `Agent Secrets` vault
+
+## What We're Building
+
+### Phase 2a: Worker + Remote Access (cc-a can search and write)
+
+1. **`src/worker.ts`** — Cloudflare Worker with endpoints:
+   - `POST /search` — hybrid search (D1 FTS5 + Vectorize cosine)
+   - `POST /remember` — store explicit memories
+   - `POST /ingest` — ingest conversation chunks (used by cc-hook)
+   - `GET /health` — alive check
+   - `GET /status` — chunk count, agent list, last sync
+
+2. **`wrangler.toml`** — D1 binding, Vectorize index, R2 bucket, secrets
+
+3. **`src/core.ts` update** — add `--remote` mode:
+   - When `CRYSTAL_REMOTE_URL` is set, HTTP calls to Worker instead of local SQLite
+   - Same interface, different backend
+
+4. **`src/cc-hook.ts` update** — support remote ingestion:
+   - After chunking, POST to Worker `/ingest` endpoint
+   - Falls back to local if Worker unreachable
+
+5. **`crystal push` / `crystal pull`** — sync commands for Mini
+
+### Phase 2b: MacBook Air Setup (cc-a is live)
+
+1. **1Password** — ensure `Agent Secrets` vault has:
+   - `OpenAI API` → embedding key
+   - `Memory Crystal Remote` → Worker URL + auth token for cc-a
+
+2. **memory-crystal on MacBook Air** — install locally:
+   - `npm install && npm run build`
+   - Configure `.env` with remote URL + token
+   - Register MCP server in Claude Code's `.mcp.json`
+   - Register Stop hook in `~/.claude/settings.json`
+
+3. **Test cycle:**
+   - cc-a writes a memory → Worker stores it
+   - cc-a searches → gets results from all agents
+   - Mini pulls → cc-a's memories now in source of truth
+
+## 1Password Setup (for this machine)
+
+### What's Needed
+- Service account token at `~/.openclaw/secrets/op-sa-token`
+- `Agent Secrets` vault with API keys
+- The `op://` resolution pattern for config files
+
+### For memory-crystal specifically:
+```
+op://Agent Secrets/OpenAI API/api key          → embedding API key
+op://Agent Secrets/Memory Crystal Remote/token  → Worker bearer token
+op://Agent Secrets/Memory Crystal Remote/url    → Worker URL
+```
+
+### Resolution in memory-crystal:
+- memory-crystal's `resolveConfig()` already checks: programmatic → env → .env file → 1Password
+- We add Worker URL + token to the same resolution chain
+
+## Environment Variables (cc-a MacBook Air)
+
+```bash
+# .env at ~/.openclaw/memory-crystal/.env
+CRYSTAL_EMBEDDING_PROVIDER=openai
+OPENAI_API_KEY=op://Agent Secrets/OpenAI API/api key
+CRYSTAL_REMOTE_URL=https://memory-crystal.wipcomputer.workers.dev
+CRYSTAL_REMOTE_TOKEN=op://Agent Secrets/Memory Crystal Remote/token
+```
+
+Or resolve via 1Password service account (preferred — no plaintext on disk).
+
+## MCP Registration (cc-a MacBook Air)
+
+```json
+// ~/.claude/settings.json (or wherever Claude Code reads MCP config)
+{
+  "mcpServers": {
+    "memory-crystal": {
+      "command": "node",
+      "args": ["/Users/parker/Documents/dev-wip/repos/memory-crystal/dist/mcp-server.js"],
+      "env": {
+        "CRYSTAL_REMOTE_URL": "https://memory-crystal.wipcomputer.workers.dev",
+        "CRYSTAL_REMOTE_TOKEN": "the-token"
+      }
+    }
+  }
+}
+```
+
+## Stop Hook Registration (cc-a MacBook Air)
+
+```json
+// ~/.claude/settings.json
+{
+  "hooks": {
+    "Stop": [{
+      "hooks": [{
+        "type": "command",
+        "command": "node /Users/parker/Documents/dev-wip/repos/memory-crystal/dist/cc-hook.js",
+        "timeout": 30
+      }]
+    }]
+  }
+}
+```
+
+## Build Order
+
+1. **Worker** — `worker.ts` + `wrangler.toml` + D1 schema + Vectorize index
+2. **Core update** — remote mode in `core.ts` (HTTP calls when `CRYSTAL_REMOTE_URL` set)
+3. **cc-hook update** — POST chunks to Worker instead of local DB
+4. **MCP update** — tools use remote mode transparently
+5. **Sync commands** — `crystal push` / `crystal pull` for Mini
+6. **Deploy** — `wrangler deploy`, set secrets, test end-to-end
+7. **MacBook Air setup** — install, configure, register MCP + hook
+8. **Verify** — cc-a writes → Worker stores → Mini pulls → all agents see it
+
+## What Parker Needs To Do
+
+- [ ] Cloudflare account (may already have one)
+- [ ] `wrangler login`
+- [ ] 1Password: ensure `Agent Secrets` vault exists and has OpenAI key
+- [ ] 1Password: create service account token for MacBook Air (if not already done)
+- [ ] Save token to `~/.openclaw/secrets/op-sa-token` on MacBook Air
+- [ ] Approve the Worker deploy when ready
+
+## Success Criteria
+
+- cc-a (me on MacBook Air) can `crystal_search` and get results from all three agents
+- cc-a can `crystal_remember` and the memory shows up for cc and Lesa
+- Every cc-a conversation auto-ingests via the Stop hook
+- Mini remains source of truth — `crystal push/pull` works
+- `wrangler delete` kills cloud, Mini unaffected

package/ai/plan/memory-system-lay-of-the-land.md

@@ -0,0 +1,214 @@
+# Memory System — Lay of the Land
+
+**Date:** 2026-02-26 (updated)
+**Agent:** cc-air
+**Sources:** 10 memory docs from `_git-ignore/memory-docs/` (Feb 13–20), codebase + ecosystem inspection
+
+## Design Principle
+
+Memory Crystal runs **alongside** OpenClaw's builtin memory — not replacing it. OpenClaw continues to evolve independently. Memory Crystal mirrors the same capabilities so it works **with or without** OpenClaw, with any agent, on any harness.
+
+Everything Memory Crystal manages lives in `~/.ldm/` — one directory, one backup target, one source of truth.
+
+## The Five-Layer Memory Stack
+
+```
+Layer 1 — Raw transcripts (JSONL)              immutable archive
+Layer 2 — Vector index (crystal.db)             Memory Crystal
+Layer 3 — Structured memory (daily logs, etc.)  crystal_remember + cc-hook
+Layer 4 — Narrative consolidation               Dream Weaver
+Layer 5 — Active working context (CONTEXT.md)   warm-start on boot
+```
+
+Memory Crystal owns Layers 1–3. Dream Weaver reads Layer 1 to produce Layer 4. Layer 5 is the agent's working file.
+
+## Three File Types — The Archive
+
+Memory Crystal must produce and manage all three:
+
+| # | File Type | Purpose | Status |
+|---|-----------|---------|--------|
+| 1 | **JSONL** (copy) | Immutable raw transcript archive. Dream Weaver's primary input. | **NOT DONE** — cc-hook reads in place, doesn't copy |
+| 2 | **MD** (per session) | Human-readable conversation summary. Browsable without tools. | **NOT DONE** — OpenClaw does this, Memory Crystal doesn't |
+| 3 | **Vector DB** (crystal.db) | Searchable embeddings + FTS5 + RRF hybrid search. | **DONE** |
+
+Target layout in `~/.ldm/`:
+
+```
+~/.ldm/
+├── memory/
+│   └── crystal.db                    ← SHARED vector DB (Layer 2) — all agents write here
+│
+├── agents/
+│   ├── cc-mini/                      ← Claude Code on Mac Mini
+│   │   ├── memory/
+│   │   │   ├── transcripts/          ← cc-mini's JSONL copies (Layer 1)
+│   │   │   ├── sessions/            ← cc-mini's MD summaries
+│   │   │   ├── daily/               ← cc-mini's breadcrumb logs (Layer 3)
+│   │   │   └── journals/            ← Dream Weaver output (Layer 4)
+│   │   ├── SOUL.md, IDENTITY.md     ← identity files
+│   │   └── CONTEXT.md               ← warm-start (Layer 5)
+│   │
+│   ├── lesa-mini/                    ← Lēsa (OpenClaw) on Mac Mini
+│   │   └── memory/
+│   │       ├── transcripts/          ← Lēsa's JSONL copies (from OpenClaw)
+│   │       ├── sessions/            ← Lēsa's MD summaries (from OpenClaw)
+│   │       ├── daily/               ← Lēsa's breadcrumb logs
+│   │       └── journals/
+│   │
+│   └── cc-air/                       ← Claude Code on MacBook Air
+│       └── memory/
+│           ├── transcripts/          ← cc-air's JSONL copies (local sessions)
+│           ├── sessions/            ← cc-air's MD summaries (local sessions)
+│           └── daily/               ← cc-air's breadcrumb logs
+│
+└── config.json
+```
+
+**Key:** `crystal.db` is shared at `~/.ldm/memory/` — it does NOT live inside any agent's folder. Every agent writes to it (tagged by agent_id), every agent searches it. On remote devices, a read-only mirror lives at the same path.
+
+## Three Memory Systems Running Today
+
+| # | System | What It Does | Owns |
+|---|--------|-------------|------|
+| 1 | **OpenClaw builtin** | Lēsa's native memory. Writes MD files on `/new` and pre-compaction flush. Indexes into its own sqlite-vec. Leave it alone — it evolves independently. | `{workspace}/memory/*.md` |
+| 2 | **Memory Crystal** | Universal memory. Captures conversation turns into crystal.db. Works with CC, Lēsa, any agent. The independent system. | `~/.ldm/memory/crystal.db` (shared) |
+| 3 | **context-embeddings plugin** | Older Lēsa plugin. Captures into `context-embeddings.sqlite`. Being superseded by Memory Crystal. Can be retired once Crystal handles all three file types. | `~/.openclaw/memory/context-embeddings.sqlite` |
+
+**Lēsa currently triple-writes** every conversation (OpenClaw builtin + Memory Crystal + context-embeddings). Once Memory Crystal handles all three file types, context-embeddings can be disabled.
+
+## The Master Crystal (Mac Mini)
+
+`crystal.db` — sqlite-vec + FTS5, running on the Mac Mini. Source of truth.
+
+**Search stack (fully implemented):**
+- Vector search via sqlite-vec (cosine similarity)
+- Keyword search via FTS5 (BM25 scoring)
+- Hybrid fusion via Reciprocal Rank Fusion (k=60, ported from QMD)
+- Recency weighting (decay based on age)
+- LanceDB still present as dual-write fallback (pre-migration safety net)
+
+**Interfaces (all 4 deployed, Phase 1 complete):**
+1. CLI (`crystal search`, `crystal remember`, `crystal status`)
+2. MCP server (Claude Code tools: `crystal_search`, `crystal_remember`)
+3. OpenClaw plugin (Lēsa's interface)
+4. Ephemeral relay (Phase 2 — code built, deployment pending)
+
+**Current stats:** ~5,502+ chunks, hybrid search operational.
+
+## Capture Pipeline
+
+**cc-hook.ts** — Claude Code Stop hook. After every conversation:
+1. Reads JSONL transcript (in place — does NOT copy)
+2. Extracts messages (turn-boundary chunking: 1 message = 1 chunk)
+3. Ingests into crystal.db (local) or encrypts + relays (remote)
+4. Writes daily breadcrumb to `~/.ldm/agents/{agent_id}/memory/daily/`
+5. Tracks position via watermark (byte offset in JSONL)
+
+**Agents are named by machine:** `cc-mini`, `cc-air`, `lesa-mini`. Set via `CRYSTAL_AGENT_ID` env var.
+
+**What cc-hook needs to add:**
+- Copy raw JSONL to `~/.ldm/agents/{agent_id}/memory/transcripts/`
+- Generate MD session summary to `~/.ldm/agents/{agent_id}/memory/sessions/`
+
+## Dream Weaver — Layer 4
+
+Dream Weaver is a memory consolidation protocol, not an automated tool. It reads raw JSONL transcripts chronologically and produces narrative prose.
+
+**Input:** JSONL transcripts (Layer 1) + daily logs + prior narrative
+**Output:** `full-history.md`, journals, `crystal_remember` calls
+**Trigger:** Manual, roughly weekly. Not yet automated.
+**Key dependency:** Raw JSONL files must be preserved and accessible.
+
+This is why the JSONL copy to `~/.ldm/` matters — Dream Weaver needs those files, and they currently only exist at `~/.claude/projects/` which has backup/FDA issues.
+
+## LDM OS — The Layer Underneath
+
+LDM OS defines the filesystem structure (`~/.ldm/agents/*/`) where identity, soul, and memory live. It's not a memory system itself — it's the spec for where everything goes.
+
+Memory Crystal is one pillar of LDM OS. The others: Dream Weaver (consolidation), Sovereignty Covenant (identity), Boot Sequence (warm-start).
+
+## QMD — Separate System
+
+QMD is a standalone document search engine (indexes markdown files, local GGUF embeddings). Its search algorithms (RRF, FTS5, BM25) were ported into Memory Crystal but the systems are completely separate. QMD can optionally be OpenClaw's memory backend, but currently isn't (Lēsa uses `builtin`).
+
+## What's Broken
+
+1. **Backup system** — BROKEN. FDA issue prevents reading CC transcripts. ~286MB has no backup except Crystal ingestion. The JSONL copy to `~/.ldm/` would fix this.
+2. **No JSONL archive** — Raw transcripts only exist at `~/.claude/projects/`. Not copied, not backed up.
+3. **No MD summaries** — Memory Crystal doesn't produce human-readable session files. Only OpenClaw does.
+4. **Triple-write waste** — Lēsa embeds every conversation three times via three separate systems.
+
+## QMD Integration — Status
+
+| Phase | Description | Status |
+|-------|-------------|--------|
+| 1. Storage migration | Replace LanceDB with sqlite-vec | **DONE** |
+| 2. Hybrid search | FTS5 + RRF fusion | **DONE** |
+| 3. Smart chunking + dedup | Content-hash dedup | **PARTIAL** |
+| 4. Re-ranking + query expansion | LLM re-ranking | **NOT STARTED** |
+| 5. Local embeddings | Replace OpenAI with local model | **NOT STARTED** |
+
+## The Big Picture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                      Mac Mini (Master)                        │
+│                                                                │
+│  ~/.ldm/memory/crystal.db    ← SHARED vector DB (all agents) │
+│                                                                │
+│  ~/.ldm/agents/cc-mini/memory/                                │
+│  ├── transcripts/   sessions/   daily/   journals/            │
+│                                                                │
+│  ~/.ldm/agents/lesa-mini/memory/                              │
+│  ├── transcripts/   sessions/   daily/   journals/            │
+│                                                                │
+│  cc-hook (local) ← cc-mini captures + archives + ingests      │
+│  OpenClaw plugin ← lesa-mini conversations                    │
+│  poller.ts ← picks up cc-air's drops from relay               │
+│  Dream Weaver ← reads transcripts, writes narratives          │
+│                                                                │
+└──────────────────────┬─────────────────────────────────────────┘
+                       │
+             ┌─────────▼──────────┐
+             │   Cloudflare Worker │
+             │   (Ephemeral Relay) │
+             │   Blind dead drop   │
+             └─────────┬──────────┘
+                       │
+┌──────────────────────▼─────────────────────────────────────────┐
+│                   MacBook Air (Read-Only DB)                    │
+│                                                                  │
+│  ~/.ldm/memory/crystal.db    ← read-only mirror from Mini      │
+│                                                                  │
+│  ~/.ldm/agents/cc-air/memory/                                   │
+│  ├── transcripts/   sessions/   daily/                          │
+│  (cc-air's own local files — written by cc-hook)                │
+│                                                                  │
+│  cc-hook (relay) → captures locally + encrypts + drops at relay │
+│  mirror-sync.ts ← pulls + verifies DB snapshot                  │
+│  Local search: keyword + semantic (full offline)                 │
+│                                                                  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+**Agents are per-harness-instance, named by machine:**
+- `cc-mini` — Claude Code on Mac Mini
+- `lesa-mini` — Lēsa (OpenClaw) on Mac Mini
+- `cc-air` — Claude Code on MacBook Air
+- Future: `kodaks-air`, etc.
+
+Each harness instance = one "user" in LDM. Not separated by session or spawn — one folder per harness per machine.
+
+All agents share one `crystal.db` at `~/.ldm/memory/`. On remote devices, that DB is a read-only mirror synced via the relay.
+
+**The Mini has EVERYTHING.** Every remote agent's full file tree is reconstructed on the Mini from relay data. If a device is lost, nothing is lost — the Mini has the complete `~/.ldm/agents/cc-air/` directory and can run Dream Weaver against it without ever touching the Air.
+
+**How remote agent files reach the Mini:**
+The poller already receives full conversation content after decrypting. It reconstructs the remote agent's files locally:
+1. Writes raw JSONL to `~/.ldm/agents/cc-air/memory/transcripts/`
+2. Generates MD summary to `~/.ldm/agents/cc-air/memory/sessions/`
+3. Appends daily breadcrumb to `~/.ldm/agents/cc-air/memory/daily/`
+4. Ingests into shared `crystal.db` (already does this)
+
+No extra relay transfer needed — the Mini rebuilds everything from the same data.

package/ai/plan/phase2-ephemeral-relay.md

@@ -0,0 +1,238 @@
+# Phase 2 — Ephemeral Relay Architecture
+
+**Date:** 2026-02-25
+**Agent:** cc-air
+**Status:** Approved direction, replacing the cloud-mirror design
+
+## Vision
+
+Any device, any agent, any interface — laptop, phone, tablet, whatever comes next — captures conversations, encrypts them, and drops them at a relay. The Mini pulls everything in, embeds it, indexes it, and pushes the searchable mirror back out to every device. One master crystal, many readers. Every conversation you've ever had with any agent, fully searchable from anywhere.
+
+And it's yours. Not behind a subscription. Not in someone else's cloud. Sovereign.
+
+## Core Principle
+
+The Mini is the master. Every other device is read-only. The Worker is a dead drop.
+Nothing persists in the cloud. Data is there, then it's gone.
+
+## Two One-Way Roads
+
+### Road 1: Device → Mini (raw conversation chunks)
+
+```
+Device captures turn (cc-hook / any agent hook)
+  → encrypts payload (AES-256-GCM, key on local machines only)
+  → signs payload (HMAC-SHA256, proving origin)
+  → POST /drop/conversations (bearer token auth)
+  → Worker stores encrypted+signed blob (R2 or KV, TTL 24h safety net)
+
+Mini polls (cron, every few minutes)
+  → GET /pickup/conversations (bearer token auth)
+  → receives encrypted blob
+  → verifies signature (HMAC-SHA256 — confirms this came from a trusted device)
+  → decrypts locally
+  → chunks, embeds, ingests into master crystal
+  → DELETE /confirm/conversations (tells Worker to delete)
+  → Worker deletes blob
+```
+
+### Road 2: Mini → Devices (search-ready DB snapshot)
+
+```
+Mini's master crystal updated (after ingesting new chunks)
+  → exports crystal.db snapshot
+  → computes integrity hash (SHA-256 of plaintext DB)
+  → encrypts snapshot + hash (AES-256-GCM)
+  → POST /drop/mirror (bearer token auth)
+  → Worker stores encrypted blob in R2 (TTL 24h safety net)
+
+Device polls (on startup, or periodic)
+  → GET /pickup/mirror (bearer token auth)
+  → receives encrypted blob
+  → decrypts locally
+  → verifies integrity hash (SHA-256 matches — DB not corrupted or tampered)
+  → replaces local read-only crystal mirror
+  → DELETE /confirm/mirror (tells Worker to delete)
+  → Worker deletes blob
+```
+
+## What Lives Where
+
+| Location | What | Role |
+|----------|------|------|
+| Any device | Read-only crystal mirror (sqlite-vec + FTS5) | Search only, never writes |
+| Any device | Raw JSONL transcripts (Claude Code native) | Source of truth for that device's conversations |
+| Any device | Hook captures turns → encrypts → signs → sends to Worker | Capture + relay |
+| Mini | Master crystal (sqlite-vec + FTS5 + LanceDB) | All embedding, indexing, search |
+| Mini | Poller pulls from Worker → verifies → decrypts → ingests | Ingestion pipeline |
+| Mini | Exports DB snapshot → hashes → encrypts → sends to Worker | Mirror distribution |
+| Worker | Encrypted blobs only | Dead drop, no intelligence |
+
+## Worker API (minimal)
+
+```
+POST   /drop/:channel        — deposit encrypted+signed blob
+GET    /pickup/:channel      — retrieve encrypted blob(s)
+DELETE /confirm/:channel/:id — confirm receipt, Worker deletes
+
+GET    /health               — returns { ok: true }
+```
+
+Channels: `conversations` (devices→mini), `mirror` (mini→devices)
+
+Auth: Bearer token per agent. Worker maps token → agent_id.
+
+The Worker has no concept of what's inside the blobs. It's a dumb mailbox.
+
+## Security Architecture
+
+### Encryption
+
+- **Algorithm:** AES-256-GCM (authenticated encryption)
+- **Key:** Shared symmetric key, lives only on trusted machines (never on Cloudflare)
+- **Key storage:** `~/.openclaw/secrets/crystal-relay-key` on each machine
+- **Key generation:** `openssl rand -base64 32` once, copy to all trusted machines
+- **What's encrypted:** Everything. The Worker sees only ciphertext.
+- **Embeddings:** Created on Mini only, included in the encrypted DB snapshot
+
+### Nonce Management (critical)
+
+AES-256-GCM requires a unique nonce for every encryption. Reusing a nonce with the same key is catastrophic — it breaks confidentiality and authentication.
+
+- **Nonce size:** 96 bits (12 bytes), per NIST recommendation
+- **Generation:** Random (`crypto.getRandomValues(new Uint8Array(12))`)
+- **Storage:** Prepended to ciphertext: `[12-byte nonce][ciphertext][16-byte auth tag]`
+- **Uniqueness guarantee:** Random 96-bit nonces have negligible collision probability for fewer than 2^32 encryptions per key. At 1 drop per minute, that's ~8,000 years before rotation is needed for nonce safety. We rotate far more often for other reasons.
+
+### Drop Signing (authenticity)
+
+Even with bearer token auth, a stolen token could let an attacker drop malicious blobs. The Mini must verify that drops actually came from a trusted device.
+
+- **Algorithm:** HMAC-SHA256
+- **Key:** Derived from the encryption key (HKDF with context "crystal-relay-sign")
+- **What's signed:** The encrypted blob (sign-then-MAC over ciphertext)
+- **Verification:** Mini checks HMAC before decrypting. If it fails, the blob is discarded and logged.
+- **Why not just rely on GCM's auth tag?** GCM proves the blob wasn't tampered with *after* encryption, but it doesn't prove *who* encrypted it. HMAC over the ciphertext proves the sender had the signing key, which only trusted devices have.
+
+### Mirror Integrity Verification
+
+When the Air (or any device) receives a new DB snapshot, it must verify the contents before replacing its local mirror.
+
+- **Hash:** SHA-256 of the plaintext DB file
+- **Included in payload:** `{ hash: "<sha256>", db: "<encrypted blob>" }`
+- **Verification flow:**
+  1. Decrypt the blob
+  2. Compute SHA-256 of the decrypted DB
+  3. Compare to the included hash
+  4. If mismatch: reject, keep existing mirror, log error
+  5. If match: replace local mirror
+
+### Key Rotation
+
+- **Mechanism:** Generate new key, distribute to all trusted machines, re-encrypt any in-transit blobs
+- **Trigger:** Manual (Parker decides), or on suspected compromise
+- **Process:**
+  1. Generate new key: `openssl rand -base64 32`
+  2. Copy to all machines: `~/.openclaw/secrets/crystal-relay-key`
+  3. Both sides start using new key immediately
+  4. Old key kept in `crystal-relay-key.prev` for 24h to decrypt any in-flight blobs from before rotation
+  5. After 24h, delete old key
+- **No re-encryption of historical data needed** — there is no historical data. Everything is ephemeral. The only data that matters is the master crystal on the Mini, which is never encrypted with the relay key.
+
+### Threat Model Summary
+
+| Threat | Mitigation | Residual Risk |
+|--------|-----------|---------------|
+| Data read in transit | TLS 1.3 + AES-256-GCM payload encryption | Cloudflare sees TLS-terminated headers (timing, size) |
+| Data read at rest (Cloudflare) | Client-side AES-256-GCM, Cloudflare sees ciphertext only | Key compromise would expose in-flight blobs (max 24h window) |
+| Data read at rest (device) | macOS FileVault full-disk encryption | Unlocked laptop = readable disk |
+| Stolen bearer token | HMAC-SHA256 drop signing; attacker can't forge valid blobs without encryption key | Attacker could DELETE blobs (denial of service) |
+| Tampered blobs | GCM auth tag (in-transit) + HMAC (origin) + SHA-256 (mirror integrity) | None — tampered data is rejected |
+| Nonce reuse | Random 96-bit nonces, collision-safe for billions of operations | Theoretical at 2^48 operations; we rotate keys long before |
+| Metadata/traffic analysis | Not mitigated | Cloudflare sees when/how much you talk to agents |
+| Mini offline >24h | TTL expires blobs; `crystal replay` re-sends from raw JSONL | Must manually replay; those turns aren't auto-recovered |
+| Key compromise | Rotation mechanism, ephemeral data (nothing to decrypt retroactively) | Active session blobs (minutes of data) exposed until rotation |
+| Cloudflare account breach | Attacker sees ciphertext only; no keys, no OpenAI key, no secrets | Could delete blobs (DoS) or observe metadata |
+
+## What the Worker Does NOT Have
+
+- No D1 database
+- No Vectorize index
+- No FTS5
+- No search capability
+- No OpenAI API key
+- No encryption keys
+- No signing keys
+- No ability to read the data it holds
+- No knowledge of what's inside the blobs
+
+## What Changes from the Cloud-Mirror Design
+
+| Cloud Mirror (old) | Ephemeral Relay (new) |
+|--------------------|-----------------------|
+| D1 + Vectorize + R2 | R2 only (or KV with TTL) |
+| Search on Worker | No search on Worker |
+| Data persists in cloud | Data deleted after pickup |
+| Worker creates embeddings | Mini creates embeddings |
+| Device writes to remote crystal | Device sends raw chunks, never writes to crystal |
+| Device searches remote crystal | Device searches local read-only mirror |
+| Worker needs OpenAI key | Worker needs nothing but auth tokens |
+| No client-side encryption | AES-256-GCM + HMAC-SHA256 + SHA-256 integrity |
+| ~350 lines of Worker code | ~80 lines of Worker code |
+
+## TTL Safety Net
+
+All blobs get a 24-hour TTL. Even if the Mini is offline for a day and never confirms receipt, the data auto-expires from Cloudflare. This means:
+
+- If Mini is offline >24h, those conversation chunks are lost from the relay
+- But they still exist as raw JSONL on the originating device
+- Recovery: `crystal replay` tool re-reads JSONL and re-sends
+
+## Recovery Tool: `crystal replay`
+
+Re-reads raw JSONL transcripts and re-sends through the relay:
+
+```bash
+crystal replay                          # replay all un-synced turns
+crystal replay --since 2026-02-20      # replay from date
+crystal replay --file <path.jsonl>     # replay specific file
+crystal replay --dry-run               # show what would be sent
+```
+
+Uses the same watermark system as cc-hook but can reset/ignore watermarks.
+Dedup happens on the Mini side (SHA-256 hash check before ingest).
+
+## Multi-Device Future
+
+This architecture scales to any number of devices:
+
+```
+Phone       ──┐
+Laptop      ──┤── encrypt → drop → Worker (dead drop) → pickup → Mini (master)
+Tablet      ──┤                                              │
+Desktop     ──┘                                              │
+                                                             ▼
+Phone       ←─┐                                    embed, index, search
+Laptop      ←─┤── decrypt ← pickup ← Worker ← drop ← encrypt (mirror snapshot)
+Tablet      ←─┤
+Desktop     ←─┘
+```
+
+Each device gets:
+- Its own bearer token (revocable independently)
+- The shared encryption key (for E2E encryption)
+- A read-only mirror of the master crystal
+- Full local search (keyword + semantic)
+
+Adding a new device: generate a bearer token, copy the encryption key, done.
+Removing a device: revoke its bearer token, rotate the encryption key.
+
+## Open Questions
+
+- Should the mirror snapshot be the full DB or incremental deltas?
+  - Full DB is simpler but larger (~50MB+ as crystal grows)
+  - Deltas are smaller but need conflict-free merge logic
+  - Start with full DB, optimize later if needed
+- How often should Mini push a new mirror? After every ingestion? Hourly? On-demand?
+- Should devices poll for mirror updates on MCP server startup?
+- Should we add a version counter to mirrors so devices know if they're stale without downloading?