memory-crystal 0.2.0

package/ai/plan/readme-first.md

@@ -0,0 +1,68 @@
+# Read Me First
+
+Start here before working on Memory Crystal. Read these docs in this order.
+
+## 1. Lay of the Land
+
+Understand the full memory ecosystem — what exists, what's broken, how the pieces fit:
+
+- **`ai/plan/memory-system-lay-of-the-land.md`** — The five-layer memory stack, three file types, three parallel memory systems, agent naming, `~/.ldm/` directory structure, Dream Weaver relationship, the big picture diagram
+
+## 2. Architecture
+
+How the ephemeral relay and cross-machine sync works:
+
+- **`ai/plan/phase2-ephemeral-relay.md`** — Two one-way roads (Device→Mini, Mini→Device), security architecture (AES-256-GCM, HMAC, nonce management, key rotation), threat model, Worker API
+
+## 3. Roadmap
+
+What's done, what's next, in priority order:
+
+- **`ai/plan/roadmap.md`** — Priority 1 (three file types) through Priority 9 (data coverage). Agent table, dependency map, LDM scaffolding plan
+
+## 4. Todos
+
+Actionable work items:
+
+- **`ai/todos/cc-air/2026-02-26--cc-air--post-relay-todos.md`** — Full todo list with priorities
+- **`ai/todos/parker/2026-02-25--cc-air--setup-checklist.md`** — Parker's physical setup for the relay (encryption key, Cloudflare, env vars)
+
+## 5. Background Reading (in `_git-ignore/memory-docs/`)
+
+These docs are gitignored but provide the thinking behind the decisions. Read chronologically:
+
+1. **`cc-memory-backfill-tool.md`** (Feb 13) — Plan for `--backfill` to ingest historical CC sessions
+2. **`cc-wake-and-memory-capture.md`** (Feb 13) — Inbox watcher + auto capture with watermarking
+3. **`memory-capture-fix-plan.md`** (Feb 13) — snake_case/camelCase bug fix, private mode, kill switch
+4. **`cc-how-we-remember.md`** (Feb 16) — Behavioral proposal: SHARED-CONTEXT.md, 10x crystal_remember, search-before-acting
+5. **`2026-02-16--qmd-vs-crystal-memory.md`** (Feb 16) — QMD vs Memory Crystal comparison (QMD search algorithms now ported)
+6. **`2026-02-16--qmd-crystal-integration-plan.md`** (Feb 16) — 5-phase plan (Phases 1-2 done, 3-5 remaining)
+7. **`2026-02-16--before-message-write-hook.md`** (Feb 16) — OpenClaw hook for true ephemeral private mode
+8. **`identity-fingerprint-conversation-2026-02-19.md`** (Feb 19) — Identity persistence across model swaps
+9. **`memory-system-architecture.md`** (Feb 20) — Complete map of every data store
+10. **`memory-data-inventory.md`** (Feb 20) — Inventory of all 11 local stores, 7 not in vector DB
+
+## 6. Superseded (read only for historical context)
+
+- **`ai/plan/memory-crystal-phase2-plan.md`** — Old cloud-mirror design. Replaced by ephemeral relay.
+- **`PLAN.md`** (repo root) — Original Phase 1-4 plan. Phase 1 complete. Phase 2+ superseded by relay.
+
+## 7. Related Repos
+
+These repos are part of the ecosystem but Memory Crystal has no code dependency on them:
+
+- **`wip-ldm-os`** — LDM OS spec + installer. Memory Crystal absorbs its scaffolding.
+- **`ldm-home`** — Deployed `~/.ldm/` directory (version-controlled mirror)
+- **`dream-weaver-protocol`** — Memory consolidation protocol. Reads JSONL transcripts from `~/.ldm/agents/*/memory/transcripts/`
+- **`openclaw`** — Agent harness. Memory Crystal runs as an optional plugin inside it.
+- **`qmd`** — Standalone doc search engine. Search algorithms ported into Memory Crystal (RRF, FTS5, BM25).
+- **`lesa-openclaw-context-embeddings`** — Older conversation capture plugin. Being superseded by Memory Crystal.
+- **`lesa-bridge`** — Cross-agent communication. Currently reads context-embeddings DB; will migrate to crystal.db.
+
+## Key Concepts
+
+- **Agents are per-harness-instance, named by machine:** cc-mini, lesa-mini, cc-air
+- **crystal.db is shared** at `~/.ldm/memory/crystal.db` — all agents write to it, tagged by agent_id
+- **The Mini has everything** — remote agents' file trees are reconstructed from relay data
+- **Memory Crystal works with or without OpenClaw** — independent system that mirrors the same features
+- **Three file types:** JSONL (raw archive), MD (human-readable), vector DB (searchable)

package/ai/plan/roadmap.md

@@ -0,0 +1,159 @@
+# Memory Crystal — Roadmap
+
+**Date:** 2026-02-26 (updated)
+**Agent:** cc-air
+**Based on:** memory docs review, ecosystem inspection, Dream Weaver analysis
+
+## Vision
+
+Memory Crystal is the universal archive manager for `~/.ldm/`. It works with or without OpenClaw, with any agent, on any harness. It produces three file types (JSONL copies, MD summaries, vector DB) and stores everything in one directory that gets backed up.
+
+It includes its own `~/.ldm/` scaffolding — no dependency on the wip-ldm-os repo. Everything needed to set up the LDM directory structure is built into Memory Crystal's installer.
+
+## What's Done
+
+- [x] sqlite-vec migration (replaced LanceDB as primary, LanceDB kept as fallback)
+- [x] FTS5 full-text search with BM25 scoring
+- [x] Hybrid search: vector + keyword with RRF fusion (ported from QMD)
+- [x] Recency weighting
+- [x] Turn-boundary chunking (1 conversation message = 1 chunk)
+- [x] CC Stop hook with watermark-based capture
+- [x] MCP server (crystal_search, crystal_remember tools)
+- [x] OpenClaw plugin (Lēsa's interface)
+- [x] CLI (crystal search, crystal remember, crystal status)
+- [x] Private mode (kill switch across CLI, MCP, OpenClaw, env var)
+- [x] Ephemeral relay code: crypto, worker, cc-hook dual mode, poller, mirror-sync
+- [x] Daily breadcrumb logs to `~/.ldm/agents/cc/memory/daily/`
+
+## Priority 1 — Three File Types (the core gap)
+
+Memory Crystal currently only produces the vector DB. It needs to produce all three:
+
+### 1a. JSONL Archive
+- [ ] **cc-hook: copy raw JSONL** to `~/.ldm/agents/{agent}/memory/transcripts/`
+- [ ] Copy the new portion (or full file) after each capture
+- [ ] This is Dream Weaver's primary input — must be preserved
+- [ ] Solves the FDA backup problem (files now in a controlled, backupable location)
+
+### 1b. MD Session Summaries
+- [ ] **cc-hook: generate human-readable MD** per conversation
+- [ ] Write to `~/.ldm/agents/{agent}/memory/sessions/YYYY-MM-DD-{slug}.md`
+- [ ] Include: timestamp, session ID, conversation summary (user messages + key assistant responses)
+- [ ] Matches what OpenClaw's session-memory hook produces, but independent of OpenClaw
+- [ ] Consider: LLM-generated slug (like OpenClaw does) vs timestamp-only (simpler, no API call)
+
+### 1c. crystal.db Location
+- [ ] **Move or symlink** crystal.db to `~/.ldm/memory/crystal.db`
+- [ ] Currently at `~/.openclaw/memory-crystal/crystal.db` — outside the LDM archive
+- [ ] The DB is **shared** — all agents (cc-mini, lesa-mini, cc-air) read/write to it, tagged by agent_id
+- [ ] On remote devices, a read-only mirror lives at the same path
+
+## Priority 2 — LDM Scaffolding (no external dependency)
+
+Memory Crystal must set up `~/.ldm/` itself. No dependency on wip-ldm-os repo.
+
+- [ ] **Built-in scaffold** — `crystal init` or auto-scaffold on first run
+- [ ] Create the full directory structure:
+  ```
+  ~/.ldm/
+  ├── config.json
+  ├── memory/
+  │   └── crystal.db            (shared vector DB — all agents)
+  └── agents/{agent_id}/
+      ├── config.json
+      └── memory/
+          ├── transcripts/      (JSONL copies)
+          ├── sessions/         (MD summaries)
+          ├── daily/            (breadcrumb logs)
+          └── journals/         (Dream Weaver output)
+  ```
+- [ ] Agent names are by machine: `cc-mini`, `lesa-mini`, `cc-air`
+- [ ] Absorb relevant parts of `wip-ldm-os/bin/scaffold.sh` and templates
+- [ ] Identity files (SOUL.md, IDENTITY.md, CONTEXT.md) — create empty templates or skip (agent-specific, not Memory Crystal's job)
+- [ ] Config: agent name, harness type, Dream Weaver schedule
+
+## Priority 3 — Deploy Ephemeral Relay + Expand Poller
+
+**Branch:** `cc-air/phase2-relay`
+**Blocked on:** Parker's physical setup (see `ai/todos/parker/`)
+
+1. Generate encryption key, copy to both machines
+2. `wrangler login`, create R2 bucket, set bearer tokens
+3. Deploy Worker
+4. Configure env vars (Air + Mini)
+5. End-to-end test: capture → relay → ingest → mirror → search
+
+### Poller expansion (Mini-side)
+The poller already decrypts conversation data from remote agents. Expand it to reconstruct the remote agent's full file tree on the Mini:
+
+- [ ] **Write JSONL** to `~/.ldm/agents/{agent_id}/memory/transcripts/`
+- [ ] **Generate MD summary** to `~/.ldm/agents/{agent_id}/memory/sessions/`
+- [ ] **Append daily breadcrumb** to `~/.ldm/agents/{agent_id}/memory/daily/`
+- [ ] **Ingest into crystal.db** (already done)
+
+No extra relay transfer — the Mini rebuilds everything from the same decrypted data. This ensures the Mini has a complete `~/.ldm/` for every agent, enabling Dream Weaver to run against any agent from the Mini.
+
+## Priority 4 — Fix Broken Systems
+
+- [ ] **Backup system** — FDA issue. Partially solved by JSONL copy to `~/.ldm/` (Priority 1a). Full fix: grant FDA or find alternative.
+- [ ] **LanceDB removal** — Once sqlite-vec is validated, remove dual-write. Simplifies codebase, drops a dependency.
+- [ ] **Retire context-embeddings** — Once Memory Crystal handles all three file types, disable the context-embeddings plugin in dot-openclaw. Update lesa-bridge to read from crystal.db instead.
+
+## Priority 5 — Recovery & Backfill Tools
+
+- [ ] **`crystal replay`** — Re-send from raw JSONL through the relay. Recovery for when Mini is offline >24h.
+- [ ] **`crystal backfill`** — One-time ingest of all ~115 historical CC sessions (~110MB, ~$0.07).
+
+## Priority 6 — Dream Weaver Integration
+
+- [ ] **Trigger consolidation** — After poller ingests a batch, optionally kick off incremental Dream Weaver run.
+- [ ] **Automate weekly schedule** — Currently manual. Add cron/launchd trigger based on `dreamWeaver.schedule` in config.
+- [ ] **Dream Weaver reads from `~/.ldm/`** — Once JSONL copies live there, Dream Weaver reads from `transcripts/` instead of `~/.claude/projects/`.
+
+## Priority 7 — Search Quality (QMD Phases 3–5)
+
+- [ ] **Phase 3: Smart chunking + dedup** — Content-hash dedup, better non-conversation chunking.
+- [ ] **Phase 4: Re-ranking + query expansion** — LLM re-ranking, synonym expansion. Biggest quality jump remaining.
+- [ ] **Phase 5: Local embeddings** — Replace OpenAI with local model (GGUF via node-llama-cpp, like QMD uses).
+
+## Priority 8 — Behavioral / Process
+
+- [ ] **SHARED-CONTEXT.md** — Warm-start file agents read on boot. <50 lines, current state.
+- [ ] **End-of-session handoffs** — Agent writes what-I-was-doing summary at session end.
+- [ ] **Search-before-acting** — Agents search crystal before starting new work.
+
+## Priority 9 — Data Coverage Expansion
+
+7 of 11 data stores aren't in the vector DB. Review which warrant ingestion:
+- [ ] CLAUDE.md memories, auto-memory, Dream Weaver narratives, dev updates, identity docs
+
+## Agents
+
+Each harness instance = one agent = one "user" in LDM. Named by machine:
+
+| Agent ID | Machine | Harness |
+|----------|---------|---------|
+| `cc-mini` | Mac Mini | Claude Code |
+| `lesa-mini` | Mac Mini | OpenClaw |
+| `cc-air` | MacBook Air | Claude Code |
+| Future: `kodaks-air` | MacBook Air | Kodaks |
+
+Each agent writes its own files (transcripts, sessions, daily) to `~/.ldm/agents/{agent_id}/memory/`. All agents share one `crystal.db` at `~/.ldm/memory/`.
+
+**The Mini has everything.** Remote agents' file trees are reconstructed on the Mini by the poller from decrypted relay data. If a device is lost, nothing is lost — Dream Weaver can be run against any agent from the Mini.
+
+## Dependency Map
+
+```
+Memory Crystal (standalone — no external repo dependencies for core function)
+├── sqlite-vec          (npm — vector search)
+├── better-sqlite3      (npm — SQLite engine)
+├── OpenAI API          (embedding provider — swappable for Ollama/local)
+└── ~/.ldm/             (filesystem — scaffolded by Memory Crystal itself)
+
+Optional integrations (not dependencies):
+├── OpenClaw plugin     (if OpenClaw is installed, registers tools + agent_end hook)
+├── Claude Code hook    (if CC is the harness, captures via Stop hook)
+├── Ephemeral relay     (if multi-machine, Cloudflare Worker for sync)
+└── Dream Weaver        (reads from ~/.ldm/agents/*/transcripts/, writes to ~/.ldm/agents/*/journals/)
+```

package/ai/todos/PUNCHLIST.md

@@ -0,0 +1,44 @@
+# Memory Crystal ... Punchlist
+
+**Updated:** 2026-02-27
+**Repo:** `wipcomputer/memory-crystal-private`
+
+## Active
+
+### Release
+```bash
+cd ~/Documents/wipcomputer--mac-mini-01/staff/Parker/Claude\ Code\ -\ Mini/repos/ldm-os/components/memory-crystal-private
+git checkout main && git pull
+wip-release minor --notes="Phase 2: LDM scaffolding, JSONL archive, MD summaries, relay merge"
+```
+- [ ] `wip-release minor`
+
+## Architecture Direction
+
+Three features, one product:
+1. **Memory** ... remember, search, forget. One SQLite DB. Any AI tool.
+2. **Bridge** ... local agent-to-agent communication. All messages saved to crystal.
+3. **Relay** ... multi-device sync. Remote agents communicate and share memory.
+
+All writes go to the crystal. Always. No matter which layer.
+
+Key merges:
+- Lesa Bridge search tools absorbed into Crystal (Bridge = communication only)
+- Context Embeddings absorbed into Crystal (Crystal captures conversations directly)
+
+## Next up (not blocking ship)
+
+- [ ] Absorb lesa-bridge into Memory Crystal as Bridge feature
+- [ ] Absorb context-embeddings into Memory Crystal (retire plugin)
+- [ ] Cloudflare relay setup (key, R2 bucket, Worker deploy, env vars)
+- [ ] Remove LanceDB dual-write
+- [ ] `crystal backfill` for ~115 historical sessions
+- [ ] Point Dream Weaver at `~/.ldm/` transcripts
+
+## Completed
+
+- [x] Push `mini/phase2-relay` ... 2026-02-26
+- [x] Create PR #2, squash-merge to main ... 2026-02-26
+- [x] Deploy build to `~/.ldm/extensions/memory-crystal/` ... 2026-02-27
+- [x] Migrate crystal.db to `~/.ldm/memory/crystal.db` (159K+ chunks, symlink at old path) ... 2026-02-26
+- [x] Fix lesa-bridge session routing (`user: "claude-code"` for dedicated TUI-visible session) ... 2026-02-27

package/ai/todos/README.md

@@ -0,0 +1,31 @@
+# ai/todos/
+
+Agent-to-agent and agent-to-human task inbox system.
+
+## How it works
+
+Each folder under `inboxes/` is a recipient. When an agent (or human) has action items for someone else, they drop a dated markdown file in that person's inbox.
+
+```
+inboxes/
+  parker/       Parker's action items (manual steps, deploys, config)
+  cc-mini/      Claude Code on Mac Mini
+  cc-air/       Claude Code on MacBook Air
+  lesa/         (create when needed)
+```
+
+## Naming convention
+
+```
+YYYY-MM-DD--{from-agent}--{short-description}.md
+```
+
+Examples:
+- `2026-02-26--cc-mini--phase2-your-moves.md` ... cc-mini telling Parker what to do
+- `2026-02-25--cc-air--setup-checklist.md` ... cc-air telling Parker what to set up
+
+## Rules
+
+- **Drop, don't edit.** If you have updates, drop a new file. Don't modify someone else's inbox items.
+- **Done items stay.** Check the boxes in the file. Don't delete completed files... they're history.
+- **Keep it short.** Link to plans or docs for details. The inbox item is the "what", not the "why".

package/ai/todos/inboxes/cc-air/2026-02-26--cc-air--post-relay-todos.md

@@ -0,0 +1,85 @@
+# cc-air — Memory Crystal Todos
+
+**Date:** 2026-02-26 (updated)
+**Agent:** cc-air
+**Context:** Full ecosystem review — memory docs, Dream Weaver, LDM OS, OpenClaw builtin, QMD
+
+## Priority 1 — Three File Types (the core gap)
+
+Memory Crystal only produces the vector DB today. It needs all three:
+
+- [ ] **JSONL archive** — cc-hook copies raw JSONL to `~/.ldm/agents/{agent_id}/memory/transcripts/` after each capture. Solves the FDA backup problem. Gives Dream Weaver its primary input in a controlled location.
+
+- [ ] **MD session summaries** — cc-hook generates human-readable markdown per conversation. Write to `~/.ldm/agents/{agent_id}/memory/sessions/YYYY-MM-DD-{slug}.md`. Matches OpenClaw's session-memory hook output but works independently.
+
+- [ ] **crystal.db location** — Move or symlink crystal.db to `~/.ldm/memory/crystal.db` (shared, root level). Currently at `~/.openclaw/memory-crystal/`. The DB is shared by all agents (cc-mini, lesa-mini, cc-air), tagged by agent_id. On remote devices, a read-only mirror lives at the same path.
+
+## Priority 2 — LDM Scaffolding (built into Memory Crystal)
+
+Memory Crystal must set up `~/.ldm/` itself. No dependency on wip-ldm-os repo.
+
+- [ ] **`crystal init` / auto-scaffold** — On first run, create the full directory structure:
+  ```
+  ~/.ldm/
+  ├── config.json
+  ├── memory/crystal.db                     (shared vector DB)
+  └── agents/{agent_id}/memory/
+      ├── transcripts/  sessions/  daily/  journals/
+  ```
+- [ ] **Agent names by machine:** `cc-mini`, `lesa-mini`, `cc-air` (set via `CRYSTAL_AGENT_ID`)
+- [ ] **Absorb wip-ldm-os scaffolding** — Port relevant parts of `scaffold.sh` and templates into Memory Crystal's installer. Identity files (SOUL.md etc.) can be empty templates or skipped.
+- [ ] **Config** — agent name, harness type, Dream Weaver schedule in `~/.ldm/agents/{agent_id}/config.json`
+
+## Priority 3 — Deploy Ephemeral Relay + Expand Poller
+
+See Parker's setup checklist at `ai/todos/parker/2026-02-25--cc-air--setup-checklist.md`.
+
+- [ ] Generate encryption key + copy to both machines
+- [ ] `wrangler login`, R2 bucket, bearer tokens, deploy
+- [ ] Configure env vars, end-to-end test
+
+**Poller expansion** — After decrypting relay data, the Mini-side poller must also reconstruct the remote agent's full file tree:
+- [ ] Write JSONL to `~/.ldm/agents/{agent_id}/memory/transcripts/`
+- [ ] Generate MD summary to `~/.ldm/agents/{agent_id}/memory/sessions/`
+- [ ] Append daily breadcrumb to `~/.ldm/agents/{agent_id}/memory/daily/`
+- [ ] This ensures the Mini has everything — if a device is lost, Dream Weaver can still run against that agent
+
+## Priority 4 — Fix Broken Systems
+
+- [ ] **Retire context-embeddings** — Once Crystal handles all three file types, disable in dot-openclaw. Update lesa-bridge to read from crystal.db.
+- [ ] **LanceDB removal** — Remove dual-write once sqlite-vec is validated.
+- [ ] **Backup system** — Partially solved by JSONL copy (Priority 1). Full fix: grant FDA or alternative.
+
+## Priority 5 — Recovery & Backfill
+
+- [ ] **`crystal replay`** — Re-send from raw JSONL through relay (recovery when Mini offline >24h).
+- [ ] **`crystal backfill`** — One-time ingest of ~115 historical CC sessions (~110MB, ~$0.07).
+
+## Priority 6 — Dream Weaver Integration
+
+- [ ] **Dream Weaver reads from `~/.ldm/`** — Once JSONL copies live there, point Dream Weaver at `transcripts/` instead of `~/.claude/projects/`.
+- [ ] **Trigger consolidation** — After poller ingests a batch, optionally trigger incremental Dream Weaver run.
+- [ ] **Automate weekly schedule** — Currently manual. Add cron/launchd trigger.
+
+## Priority 7 — Search Quality (QMD Phases 3–5)
+
+- [ ] **Phase 3: Smart chunking + dedup** — Content-hash dedup, better non-conversation chunking.
+- [ ] **Phase 4: Re-ranking + query expansion** — LLM re-ranking, synonym expansion.
+- [ ] **Phase 5: Local embeddings** — Replace OpenAI with local GGUF model.
+
+## Priority 8 — Behavioral / Process
+
+- [ ] **SHARED-CONTEXT.md** — Warm-start file agents read on boot.
+- [ ] **End-of-session handoffs** — Agent writes what-I-was-doing summary.
+- [ ] **Search-before-acting** — Agents search crystal before starting new work.
+
+## Notes
+
+- **Agents are per-harness-instance, named by machine:** cc-mini, lesa-mini, cc-air, etc. Each is a separate "user" in LDM.
+- **crystal.db is shared** at `~/.ldm/memory/crystal.db` — not inside any agent folder. All agents write to it (tagged by agent_id).
+- **The Mini has everything.** Remote agents' file trees are reconstructed from relay data. Dream Weaver can run against any agent from the Mini.
+- OpenClaw's builtin memory stays on — it evolves independently, doesn't hurt to run both.
+- QMD is a separate system. Its search algorithms are already ported into Memory Crystal.
+- Private mode is fully implemented across all 4 surfaces.
+- The relay code is built and builds clean, just needs physical deployment.
+- Memory Crystal has zero external repo dependencies for core function. OpenClaw, CC hook, relay, and Dream Weaver are optional integrations.

package/ai/todos/inboxes/cc-mini/2026-02-26--cc-mini--phase2-status.md

@@ -0,0 +1,100 @@
+# cc-mini -- Memory Crystal Phase 2 Status
+
+**Date:** 2026-02-26
+**Agent:** cc-mini
+**Branch:** `mini/phase2-relay`
+
+## What's Done
+
+### Priority 1 -- Three File Types
+
+- [x] **JSONL archive** -- cc-hook copies raw JSONL to `~/.ldm/agents/{agent_id}/memory/transcripts/` after each capture. Uses mtime check to skip redundant copies.
+- [x] **MD session summaries** -- cc-hook generates markdown per conversation after ingest. Two modes: `simple` (no API call) and `llm` (gpt-4o-mini). Written to `~/.ldm/agents/{agent_id}/memory/sessions/YYYY-MM-DD--HH-MM-SS--{agent}--{slug}.md`.
+- [x] **crystal.db path resolution** -- `resolveConfig()` checks `~/.ldm/memory/crystal.db` first, falls back to legacy `~/.openclaw/memory-crystal/`. Auto-detection means old deployments keep working.
+- [x] **`crystal migrate-db` CLI** -- Copies crystal.db to `~/.ldm/memory/`, verifies chunk count, creates symlink at old path. Never deletes the original.
+
+### Priority 2 -- LDM Scaffolding
+
+- [x] **`src/ldm.ts` module** -- Central path resolution. `getAgentId()`, `ldmPaths()`, `scaffoldLdm()`, `ensureLdm()`.
+- [x] **`crystal init [--agent]`** -- Creates full `~/.ldm/` directory tree, writes/updates config.json with agents array.
+- [x] **Agent naming** -- Via `CRYSTAL_AGENT_ID` env var. Defaults to `cc-mini`.
+- [x] **appendDailyLog()** -- Refactored to use `ldmPaths()` instead of hardcoded constant. Importable for reuse.
+
+### Priority 3 -- Relay Merge
+
+- [x] **Merged `cc-air/phase2-relay`** into `mini/phase2-relay`. Conflicts resolved (cc-hook.ts imports + dev-update section).
+- [x] **Poller expanded** -- After decrypting relay data, reconstructs remote agent's full file tree: JSONL transcript, MD summary, daily breadcrumb.
+- [x] **mirror-sync.ts** -- Updated paths to use `ldmPaths()`.
+- [x] **crypto.ts** -- Fixed HOME default.
+- [x] **All HOME fallbacks** -- Replaced `/Users/lesa` and `/Users/parker` with `process.env.HOME || ''` across all source files. Safe for others to install.
+
+### Other
+
+- [x] **dev-update.ts** -- Writes to each repo's `ai/` folder (decentralized). Disabled centralized wip-dev-updates git push.
+- [x] **mcp-server.ts** -- Uses `createCrystal()` factory. Remote mode guards on source indexing operations.
+- [x] **Build passes** -- All 12 entry points compile clean. `crystal status`, `crystal search`, `crystal init`, `poller --status`, `mirror-sync --status` all verified.
+
+## What's Next
+
+### Parker Manual Steps (blockers for relay)
+
+- [ ] Generate encryption key: `openssl rand -base64 32 > ~/.openclaw/secrets/crystal-relay-key && chmod 600 ~/.openclaw/secrets/crystal-relay-key`
+- [ ] Copy key to MacBook Air (same path)
+- [ ] Cloudflare: `wrangler login`, create R2 bucket `memory-crystal-relay`, set secrets (bearer tokens), deploy Worker
+- [ ] Set env vars on both machines: `CRYSTAL_RELAY_URL`, `CRYSTAL_RELAY_TOKEN`, `CRYSTAL_AGENT_ID`
+- [ ] End-to-end test: drop from Air, verify Mini ingests
+- [ ] See full checklist: `ai/todos/parker/2026-02-25--cc-air--setup-checklist.md`
+
+### Run migrate-db
+
+- [ ] Stop gateway: `openclaw gateway stop`
+- [ ] Run: `crystal migrate-db`
+- [ ] Restart: `openclaw gateway restart`
+- [ ] Verify: `crystal status` shows same chunk count from new path
+
+### Deploy Updated Plugin
+
+- [ ] Copy built files to extension dir and restart gateway:
+  ```
+  cd /path/to/memory-crystal
+  npm run build
+  cp -r dist skills openclaw.plugin.json package.json ~/.openclaw/extensions/memory-crystal/
+  cd ~/.openclaw/extensions/memory-crystal && npm install --omit=dev
+  openclaw gateway restart
+  ```
+
+### Priority 4 -- Fix Broken Systems
+
+- [ ] **Retire context-embeddings** -- Disable once Crystal handles all three file types. Update lesa-bridge.
+- [ ] **LanceDB removal** -- Remove dual-write once sqlite-vec is validated long enough.
+- [ ] **Backup system** -- Partially solved by JSONL copy. Full fix: grant FDA or alternative.
+
+### Priority 5 -- Recovery & Backfill
+
+- [ ] **`crystal replay`** -- Re-send from raw JSONL through relay (recovery when Mini offline >24h).
+- [ ] **`crystal backfill`** -- One-time ingest of ~115 historical CC sessions (~110MB, ~$0.07).
+
+### Priority 6 -- Dream Weaver Integration
+
+- [ ] Point Dream Weaver at `~/.ldm/agents/{id}/memory/transcripts/` instead of `~/.claude/projects/`.
+- [ ] Optional: trigger incremental DW run after poller batch.
+- [ ] Automate weekly schedule via cron/launchd.
+
+### Priority 7 -- Search Quality (QMD Phases 3-5)
+
+- [ ] Smart chunking + dedup
+- [ ] LLM re-ranking + query expansion
+- [ ] Local embeddings (replace OpenAI with local GGUF)
+
+### Priority 8 -- Behavioral / Process
+
+- [ ] SHARED-CONTEXT.md warm-start
+- [ ] End-of-session handoff summaries
+- [ ] Search-before-acting convention
+
+## Notes
+
+- crystal.db stays at `~/.openclaw/memory-crystal/` until `crystal migrate-db` is run. Symlink preserves backward compat.
+- Summary mode defaults to `simple` (no API call). Set `CRYSTAL_SUMMARY_MODE=llm` for gpt-4o-mini summaries.
+- The relay code builds clean but isn't deployed yet. Needs Parker's Cloudflare setup.
+- 159,574 chunks in crystal.db as of this commit. All search and status commands verified working.

package/ai/todos/inboxes/cc-mini/_archive/TODO.md

@@ -0,0 +1,25 @@
+# Memory Crystal — TODO
+
+## Phase 1 — Done
+All four doors live, Lēsa confirmed, 5,543+ chunks and growing.
+
+### Phase 1 cleanup (small)
+- [ ] `npm link` to install `crystal` CLI globally
+- [ ] Disable `context-embeddings` plugin (saves double embedding cost per turn) — or keep both for a few more days
+- [ ] Remove `conversation_search`/`memory_search` from lesa-bridge (crystal replaces them)
+
+## Phase 2 — Cloudflare Worker mirror (big)
+- [ ] `worker.ts` — REST API backed by D1 + Vectorize + R2
+- [ ] `crystal push` / `crystal pull` / `crystal reset` sync commands
+- [ ] Daily cron: mini uploads, Worker rebuilds, mini pulls new writes
+- [ ] **Needs:** Parker's Cloudflare account + `wrangler login`
+
+## Phase 3 — Remote multi-agent access
+- [ ] Remote MCP for Claude.ai web
+- [ ] OpenAPI spec for ChatGPT/Grok
+- [ ] `crystal search --remote` from anywhere
+
+## Other stuff on the board
+- [ ] GitHub setup (Lēsa's account)
+- [ ] Repo renames
+- [ ] cc-persistence (Pi RPC sidecar)

package/ai/todos/inboxes/parker/2026-02-25--cc-air--setup-checklist.md

@@ -0,0 +1,139 @@
+# Parker — Setup Checklist (Ephemeral Relay)
+
+Everything you need to do to get the encrypted relay live.
+
+## 1. Generate Encryption Key (once, shared across machines)
+
+```bash
+openssl rand -base64 32 > ~/.openclaw/secrets/crystal-relay-key
+chmod 600 ~/.openclaw/secrets/crystal-relay-key
+```
+
+Copy `~/.openclaw/secrets/crystal-relay-key` to both machines (Air + Mini).
+This key never goes to Cloudflare. It stays on your hardware.
+
+**How to copy:**
+- AirDrop the file
+- Or from one machine: `cat ~/.openclaw/secrets/crystal-relay-key` → paste on the other
+- Or copy via the FireWire shared disk
+
+## 2. 1Password Service Account Token (MacBook Air)
+
+The Air needs the same service account token that's on the Mini.
+
+- [ ] Copy `~/.openclaw/secrets/op-sa-token` from the Mac Mini
+- [ ] Paste it to `~/.openclaw/secrets/op-sa-token` on the MacBook Air
+- [ ] Run `chmod 600 ~/.openclaw/secrets/op-sa-token`
+
+## 3. Cloudflare Setup
+
+- [ ] Install wrangler (if not already): `npm install -g wrangler`
+- [ ] Run `wrangler login` (opens browser, authenticates)
+
+### Create R2 Bucket
+
+```bash
+cd /Users/parker/Documents/dev-wip/repos/memory-crystal
+wrangler r2 bucket create memory-crystal-relay
+```
+
+### Set Secrets
+
+Generate three bearer tokens (one per agent):
+```bash
+openssl rand -hex 32
+```
+
+- [ ] Set cc-air token: `wrangler secret put AUTH_TOKEN_CC_AIR`
+- [ ] Set cc-mini token: `wrangler secret put AUTH_TOKEN_CC_MINI`
+- [ ] Set lēsa token: `wrangler secret put AUTH_TOKEN_LESA`
+
+**Save the cc-air token** — you'll need it for the Air's env config.
+**Save the cc-mini token** — you'll need it for the Mini's poller config.
+
+### Deploy
+
+- [ ] Deploy the Worker:
+  ```bash
+  wrangler deploy
+  ```
+  Note the URL (e.g., `https://memory-crystal-relay.wipcomputer.workers.dev`)
+
+### Verify
+
+- [ ] Test health endpoint:
+  ```bash
+  curl https://memory-crystal-relay.wipcomputer.workers.dev/health
+  ```
+  Should return: `{"ok":true,"service":"memory-crystal-relay","mode":"ephemeral"}`
+
+## 4. Configure MacBook Air (cc-air)
+
+Set these environment variables (in `~/.zshrc` or Claude Code hook config):
+
+```bash
+export CRYSTAL_RELAY_URL="https://memory-crystal-relay.wipcomputer.workers.dev"
+export CRYSTAL_RELAY_TOKEN="<cc-air bearer token from step 3>"
+export CRYSTAL_AGENT_ID="cc-air"
+```
+
+The cc-hook will auto-detect relay mode when these are set.
+
+## 5. Configure Mac Mini (cc-mini poller)
+
+Set these environment variables:
+
+```bash
+export CRYSTAL_RELAY_URL="https://memory-crystal-relay.wipcomputer.workers.dev"
+export CRYSTAL_RELAY_TOKEN="<cc-mini bearer token from step 3>"
+```
+
+### Set up poller (cron or launchd):
+
+**Option A: Cron (every 2 min)**
+```bash
+crontab -e
+# Add:
+*/2 * * * * cd /path/to/memory-crystal && node dist/poller.js 2>> ~/.openclaw/logs/relay-poller.log
+```
+
+**Option B: LaunchAgent (recommended)**
+Create a plist for continuous polling with `--watch` mode.
+
+**Option C: Manual**
+```bash
+node dist/poller.js              # poll once
+node dist/poller.js --watch      # poll continuously
+node dist/poller.js --push-mirror # push mirror snapshot
+```
+
+## 6. Verify End-to-End
+
+1. Talk to cc-air on the MacBook Air
+2. Check relay has a blob: `curl -H "Authorization: Bearer <mini-token>" https://memory-crystal-relay.wipcomputer.workers.dev/pickup/conversations`
+3. Run the poller on Mini: `node dist/poller.js`
+4. Verify chunks ingested into master crystal: `node dist/cli.js status`
+5. Push mirror: `node dist/poller.js --push-mirror`
+6. Pull mirror on Air: `node dist/mirror-sync.js`
+7. Search on Air — should return results from the conversation
+
+## Quick Reference
+
+| What | Where |
+|------|-------|
+| Encryption key | `~/.openclaw/secrets/crystal-relay-key` (both machines) |
+| SA token | `~/.openclaw/secrets/op-sa-token` (both machines) |
+| Repo | `/Users/parker/Documents/dev-wip/repos/memory-crystal` |
+| Branch | `cc-air/phase2-relay` |
+| Worker config | `wrangler.toml` |
+| Air env vars | `CRYSTAL_RELAY_URL`, `CRYSTAL_RELAY_TOKEN`, `CRYSTAL_AGENT_ID` |
+| Mini env vars | `CRYSTAL_RELAY_URL`, `CRYSTAL_RELAY_TOKEN` |
+
+## What's NOT on Cloudflare
+
+- No encryption keys
+- No API keys
+- No database
+- No search capability
+- No ability to read the data
+- Just auth tokens and encrypted blobs that auto-expire in 24h