@wipcomputer/memory-crystal 0.7.30 → 0.7.33

package/.worktrees/memory-crystal-private--cc-mini-fix-home-fallback/CLA.md

@@ -1,19 +0,0 @@
-###### WIP Computer
-
-# Contributor License Agreement
-
-By submitting a pull request to this repository, you agree to the following:
-
-1. **You grant WIP Computer, Inc. a perpetual, worldwide, non-exclusive, royalty-free, irrevocable license** to use, reproduce, modify, distribute, sublicense, and otherwise exploit your contribution under any license, including commercial licenses.
-
-2. **You retain copyright** to your contribution. This agreement does not transfer ownership. You can use your own code however you want.
-
-3. **You confirm** that your contribution is your original work, or that you have the right to submit it under these terms.
-
-4. **You understand** that your contribution may be used in both open source and commercial versions of this software.
-
-This is standard open source governance. Apache, Google, Meta, and Anthropic all use similar agreements. The goal is simple: keep the tools free for everyone while allowing WIP Computer, Inc. to offer commercial licenses to companies that need them.
-
-Using these tools to build your own software is always free. This agreement only matters if WIP Computer, Inc. needs to relicense the codebase commercially.
-
-If you have questions, open an issue or reach out.

package/.worktrees/memory-crystal-private--cc-mini-fix-home-fallback/LICENSE

@@ -1,52 +0,0 @@
-Dual License: MIT + AGPLv3
-
-Copyright (c) 2026 WIP Computer, Inc.
-
-
-1. MIT License (local and personal use)
----------------------------------------
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
-
-2. GNU Affero General Public License v3.0 (commercial and cloud use)
---------------------------------------------------------------------
-
-If you run this software as part of a hosted service, cloud platform,
-marketplace listing, or any network-accessible offering for commercial
-purposes, the AGPLv3 terms apply. You must either:
-
-  a) Release your complete source code under AGPLv3, or
-  b) Obtain a commercial license.
-
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU Affero General Public License as published
-by the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-GNU Affero General Public License for more details.
-
-You should have received a copy of the GNU Affero General Public License
-along with this program. If not, see <https://www.gnu.org/licenses/>.
-
-
-AGPLv3 for personal use is free. Commercial licenses available.

package/.worktrees/memory-crystal-private--cc-mini-fix-home-fallback/README-ENTERPRISE.md

@@ -1,226 +0,0 @@
-###### WIP Computer
-
-# Memory Crystal for Enterprise
-
-Agent memory infrastructure. Local-first. Encrypted. Inspectable. *In testing.*
-
-## The Problem
-
-Your organization runs AI agents across teams, departments, and tools. Each agent starts every session with no memory. No continuity. No shared context. Conversations with one agent are invisible to every other.
-
-Your agents can't remember what your people told them. Your people keep re-explaining themselves. Context is lost between sessions, between tools, between teams.
-
-This is not a convenience problem. It's a reliability problem. An auditability problem. A cost problem.
-
-## What Memory Crystal Does
-
-Memory Crystal is a persistent context layer for AI agents. One shared database. Hybrid search. On your machines. Under your control.
-
-- **Local-first.** All data stays on-prem. Nothing leaves your network unless you configure it to.
-- **Inspectable.** One SQLite file. Open it with any SQLite tool. Audit it. Query it. Back it up with `cp`.
-- **Deterministic search.** Hybrid retrieval (BM25 keyword + vector similarity + Reciprocal Rank Fusion). Same query, same results. No black-box ranking.
-- **Encrypted sync.** Multi-site deployments use AES-256-GCM encryption with HMAC-SHA256 signing. The relay sees encrypted noise. Keys never leave your machines.
-- **Agent isolation.** Each agent gets its own ID, its own transcript archive, its own session summaries. Shared search across agents, isolated storage per agent.
-- **Zero cloud dependency.** Runs fully offline with local embeddings (Ollama). No API keys required. No data exfiltration risk.
-
-## Five-Layer Memory Stack
-
-Memory Crystal implements a full memory pipeline, not just search.
-
-| Layer | What | How |
-|-------|------|-----|
-| L1: Raw Transcripts | Every conversation archived as JSONL | Automatic. cc-poller (cron), cc-hook (Stop), openclaw.ts (agent_end) |
-| L2: Vector Index | Chunks embedded into crystal.db | Automatic. Hybrid search (BM25 + vector + RRF) |
-| L3: Structured Memory | Facts, preferences, decisions | `crystal_remember` / `crystal_forget` |
-| L4: Narrative Consolidation | Dream Weaver journals, identity, soul | `crystal dream-weave` (imports engine from Dream Weaver Protocol) |
-| L5: Active Working Context | Boot sequence files, shared context | Agent reads on startup |
-
-L1-L3 are fully automated. L4 runs on-demand or via Crystal Core gateway. L5 is consumed by the agent's boot sequence.
-
-## Architecture
-
-```
-sqlite-vec (vectors) + FTS5 (BM25) + SQLite (metadata)
-         |                 |                    |
-    core.ts ... pure logic, zero framework deps
-    |-- cli.ts            -> crystal search, dream-weave, backfill, serve
-    |-- mcp-server.ts     -> MCP protocol (any compatible client)
-    |-- openclaw.ts       -> OpenClaw plugin + raw data sync to LDM
-    |-- cc-poller.ts      -> Continuous capture (cron, primary)
-    |-- cc-hook.ts        -> Claude Code Stop hook (redundancy) + relay commands
-    |-- crystal-serve.ts  -> Crystal Core gateway (localhost:18790)
-    |-- dream-weaver.ts   -> Dream Weaver integration (narrative consolidation)
-    |-- staging.ts        -> New agent staging pipeline
-    |-- llm.ts            -> LLM provider cascade (MLX > Ollama > OpenAI > Anthropic)
-    |-- search-pipeline.ts -> Deep search (expand, search, RRF, rerank, blend)
-    +-- worker.ts         -> Encrypted relay (multi-site sync, 3 channels)
-```
-
-One core module. Multiple interfaces. Every interface calls the same search engine. No inconsistency between access paths.
-
-## Security Model
-
-**Data at rest:** Single SQLite file. Standard filesystem permissions. Encrypt the volume if your compliance requires it.
-
-**Data in transit:** AES-256-GCM authenticated encryption. HMAC-SHA256 integrity verification. Shared symmetric key generated on-prem, never transmitted to the relay. The relay is a dead drop with no decryption capability.
-
-**Agent boundaries:** `CRYSTAL_AGENT_ID` isolates each agent's transcript archive, session summaries, and daily logs. Search spans all agents by default, or filters by agent ID.
-
-**Private mode:** Memory capture can be paused per-agent. When off, nothing is recorded. Resumes from where it left off when re-enabled.
-
-**No background processes that move data.** No telemetry. No analytics. No phone-home. The code is open source. Audit it.
-
-## Retrieval Quality
-
-Hybrid search is not "we added vectors." It's a two-tier retrieval engine with LLM-powered deep search.
-
-### Fast Path (Hybrid Search)
-- **FTS5 BM25** for exact keyword matches (Porter stemming)
-- **sqlite-vec cosine similarity** for semantic matches
-- **Reciprocal Rank Fusion** merges both result lists (k=60, tiered weights: BM25 2x, vector 1x)
-- **Recency weighting** ensures fresh context wins decisively: exponential decay `max(0.3, exp(-age_days * 0.1))`
-- **Content deduplication** via SHA-256 hash prevents duplicate embeddings
-- **Time-filtered search** ... restrict results to last 24h, 7d, 30d, or any date range
-
-### Deep Search (LLM-Powered, default)
-- **Query expansion** ... LLM generates 3 search variations (lexical, semantic, hypothetical document). Each runs through hybrid search. Results merged via RRF.
-- **Strong signal detection** ... BM25 probe skips expansion when the answer is obvious (saves latency).
-- **LLM re-ranking** ... top 40 candidates scored by LLM for relevance to the original query.
-- **Position-aware blending** ... trusts RRF for top positions, lets the reranker fix ordering in the tail.
-
-Deep search runs by default. Falls back to fast path silently if no LLM provider is available. For air-gapped environments, MLX (Apple Silicon) or Ollama provides free, fully local deep search with no API keys and no network.
-
-A search for "deployment policy" finds conversations containing those exact words (BM25), conversations about "shipping code to production" (vector similarity), and conversations about "release workflow" that the LLM recognizes as relevant. All three matter. All three surface.
-
-## What Gets Stored
-
-Every agent conversation produces three artifacts:
-
-| Artifact | Format | Location |
-|----------|--------|----------|
-| Raw transcript | JSONL | `~/.ldm/agents/{id}/memory/transcripts/` |
-| Session summary | Markdown | `~/.ldm/agents/{id}/memory/sessions/` |
-| Embeddings | sqlite-vec | `~/.ldm/memory/crystal.db` |
-
-Additionally:
-- **Explicit memories** stored via `crystal_remember` (facts, preferences, decisions)
-- **Source files** indexed as collections (code, documentation, internal knowledge bases)
-- **Daily logs** appended per-agent for audit trails
-- **Dream Weaver journals** generated by narrative consolidation (identity, soul, context, reference)
-- **Workspace files** synced from agent workspace to LDM (OpenClaw .md files)
-
-## Embedding Providers
-
-| Provider | Model | Dimensions | Network Required |
-|----------|-------|-----------|-----------------|
-| Ollama (recommended for enterprise) | nomic-embed-text | 768 | No. Fully local. |
-| OpenAI | text-embedding-3-small | 1536 | Yes. API calls. |
-| Google | text-embedding-004 | 768 | Yes. API calls. |
-
-For air-gapped environments, Ollama is the only option. No data leaves the machine. No API keys. No external dependencies.
-
-## Multi-Site Sync
-
-For organizations with multiple offices or remote teams.
-
-**Architecture:** One Crystal Core (the primary embedder), many Crystal Nodes (capture and sync). Core is the only machine that writes embeddings. Nodes capture raw conversations and send them to Core. Core embeds, then pushes deltas back.
-
-**What syncs:**
-1. **Delta chunks** ... only new embeddings since last sync (not the full database)
-2. **Full file tree** ... the entire `~/.ldm/` directory: workspace files, daily logs, journals, media, everything an embedding references
-3. **Commands** ... bidirectional remote operations (run Dream Weaver, trigger backfill, request status)
-
-**How it works:**
-1. Each site runs Memory Crystal locally
-2. Core embeds all conversations into crystal.db (one source of truth for embeddings)
-3. New chunks + changed files are encrypted (AES-256-GCM) and signed (HMAC-SHA256)
-4. Encrypted deltas are dropped at a relay (hosted or self-hosted)
-5. Other sites poll, decrypt, and insert into their local crystal.db + file tree
-6. The relay deletes blobs after pickup
-
-**No cloud search.** Every node has the full database and full file tree. All search is local. The relay is pure transport. Nothing is stored or searchable in the cloud.
-
-**Self-hosted relay:** Deploy the Cloudflare Worker on your own Cloudflare account. Full control. No third-party data exposure.
-
-**Hosted relay:** Use our infrastructure. Free during beta. Your data is encrypted before it reaches us. We cannot read it.
-
-## Compliance
-
-- **Data residency:** All primary data is local. Relay blobs are encrypted and ephemeral.
-- **Auditability:** SQLite is inspectable. Every chunk has a timestamp, source, and SHA-256 hash.
-- **Right to delete:** `crystal forget <id>` deprecates specific memories. Database can be wiped entirely with standard file operations.
-- **Access control:** Filesystem permissions on the SQLite file. No built-in user auth (it's a local tool, not a SaaS).
-- **No vendor lock-in:** MIT licensed (local code). Standard SQLite format. Export with any SQLite tool.
-
-## Database
-
-One file: `crystal.db`. Contains:
-
-| Table | Purpose |
-|-------|---------|
-| `chunks` | Chunk text, metadata, SHA-256 hash, timestamps |
-| `chunks_vec` | sqlite-vec virtual table (vector search) |
-| `chunks_fts` | FTS5 virtual table (keyword search) |
-| `memories` | Explicit facts and preferences |
-| `capture_state` | Watermarks for incremental ingestion |
-| `source_collections` | Indexed directory collections |
-| `source_files` | File records with content hashes |
-
-No migrations server. No schema versioning service. It's SQLite. `sqlite3 crystal.db ".schema"` shows you everything.
-
-## Integration
-
-| Platform | Integration | Auto-Capture |
-|----------|------------|-------------|
-| Claude Code | Cron poller (`cc-poller.ts`, primary) + Stop hook (`cc-hook.ts`, redundancy) | Yes. Every minute via cron, plus flush on session end. |
-| OpenClaw | Plugin (`openclaw.ts`) + `agent_end` hook + raw data sync | Yes. Every turn. Also syncs sessions, workspace, daily logs to LDM. |
-| Claude Desktop | MCP server (`mcp-server.ts`) | Search only. Manual capture. |
-| Any MCP client | MCP server | Search only. Manual capture. |
-| Any shell-accessible tool | CLI (`crystal search`) | Manual. |
-| Custom agents | Node.js module (`import from 'memory-crystal'`) | Programmable. |
-
-## Crystal Core Gateway
-
-Crystal Core runs an HTTP gateway (`crystal serve`) on localhost:18790. OpenAI-compatible endpoint for agent-to-agent communication and automated processing.
-
-- `POST /v1/chat/completions` ... invoke `claude -p` through the gateway
-- `POST /process` ... trigger backfill, dream-weave, or staging processing
-- `GET /status` ... health check and crystal stats
-
-Localhost-only binding. Never exposed to the network. Optional bearer token auth.
-
-## New Agent Onboarding
-
-When a new agent connects via relay, Crystal Core automatically:
-1. Detects the unknown agent ID
-2. Routes to staging (`~/.ldm/staging/{agent_id}/`)
-3. Runs backfill (embed all transcripts)
-4. Runs Dream Weaver full mode (generate identity, soul, context, journals)
-5. Moves to live capture
-
-No manual intervention. The staging pipeline handles the cold-start problem.
-
-## Deployment
-
-```bash
-npm install memory-crystal
-crystal init --agent your-agent-id
-crystal status
-```
-
-For enterprise deployments across multiple machines, see [Relay: Memory Sync](https://github.com/wipcomputer/memory-crystal/blob/main/RELAY.md).
-
-For full technical details, see [Technical Documentation](https://github.com/wipcomputer/memory-crystal/blob/main/TECHNICAL.md).
-
----
-
-## License
-
-```
-src/, skills/, cli.ts, mcp-server.ts   MIT    (use anywhere, no restrictions)
-worker/                                AGPL   (relay server)
-```
-
-AGPL for personal use is free.
-
-Built by Parker Todd Brooks, Lēsa (OpenClaw, Claude Opus 4.6), Claude Code CLI (Claude Opus 4.6).

package/.worktrees/memory-crystal-private--cc-mini-fix-home-fallback/README.md

@@ -1,151 +0,0 @@
-###### WIP Computer
-
-[![npm](https://img.shields.io/npm/v/memory-crystal)](https://www.npmjs.com/package/memory-crystal) [![CLI](https://img.shields.io/badge/interface-CLI-black)](https://github.com/wipcomputer/memory-crystal/blob/main/src/cli.ts) [![MCP Server](https://img.shields.io/badge/interface-MCP_Server-black)](https://github.com/wipcomputer/memory-crystal/blob/main/src/mcp-server.ts) [![OpenClaw Plugin](https://img.shields.io/badge/interface-OpenClaw_Plugin-black)](https://github.com/wipcomputer/memory-crystal/blob/main/src/openclaw.ts) [![Claude Code Hook](https://img.shields.io/badge/interface-Claude_Code_Hook-black)](https://github.com/wipcomputer/memory-crystal/blob/main/src/cc-hook.ts) [![Universal Interface Spec](https://img.shields.io/badge/Universal_Interface_Spec-black?style=flat&color=black)](https://github.com/wipcomputer/wip-universal-installer)
-
-# Memory Crystal
-
-## All your AI tools. One shared memory. Private, searchable, sovereign.
-
-Memory Crystal lets all your AIs remember you ... together.
-
-You use multiple AIs. They don't talk to each other. They can't search what the others know. Have you ever thought to yourself ... ***why isn't this all connected?***
-
-**Memory Crystal** fixes this.
-
-***All your AIs share one memory. Searchable and private. Anywhere in the world.***
-
-## Teach Your AI to Remember You
-
-Open your AI and say:
-
-```
-Read wip.computer/install/wip-memory-crystal.txt
-
-Then explain:
-1. What is Memory Crystal?
-2. What does it install on my system?
-3. What changes for us? (this AI)
-4. What changes across all my AIs?
-
-Check if Memory Crystal is already installed.
-
-If it is, show me what I have and what's new.
-
-Then ask:
-- Do you have questions?
-- Want to see a dry run?
-
-If I say yes, run: crystal init --dry-run
-
-Show me exactly what will change. Don't install anything until I say "install".
-```
-
-Your agent will read the repo, explain everything, and walk you through setup interactively.
-
-## Memory Crystal Features
-
-**Local Memory**
-- All your AI conversations stored locally, searchable in one place. Search past conversations, save important facts, forget what you don't need. Your complete memory. It stays with you, shared across all your AIs
-- *Stable*
-  - *Verified:* Claude Code CLI + OpenClaw
-  - *Unverified:* Other MCP-compatible clients and CLIs
-
-**Multi-Device Memory**
-- AIs set up as **Crystal Nodes** relay their memories back to your **Crystal Core**. Your **Crystal Core** relays all memories back to every node. End-to-end encrypted
-- Your **Crystal Core** is the source of truth. Your node copy can be wiped and rebuilt at any time
-- Uses Cloudflare infrastructure to transfer encrypted data between your devices
-  - *Hosted:* Use WIP.computer relay infrastructure. Currently free for individual use
-  - *Self-hosted:* Deploy your own relay on your own Cloudflare account. Full sovereignty
-- Read more about [**Relay: Memory Sync**](https://github.com/wipcomputer/memory-crystal/blob/main/RELAY.md)
-- *Beta (early access)*
-
-**AI-to-AI Communication**
-- Your AIs talk to each other on the same machine or any network machine. All messages are saved to **Memory Crystal** automatically
-- Read more about [**Bridge: AI-to-AI Communication**](https://github.com/wipcomputer/wip-bridge)
-- *Beta (early access)*
-  - *Verified:* Claude Code CLI + OpenClaw on the same device
-  - *Unverified:* Network devices
-
-**Intelligent Install**
-- When installing from Claude Code CLI or OpenClaw, **Memory Crystal** discovers your existing AI sessions automatically. Installs the Learning Dreaming Machines Operating System (**LDM OS**) and creates a living memory system. From this point forward, every conversation is captured, archived, and embedded into searchable memory
-- Choose to install as **Crystal Core** (all your memories) or **Crystal Node** (a **Crystal Core** mirror)
-
-**Import Memories**
-- **Total Recall** ... Connect your AI accounts (Anthropic, OpenAI, xAI/Grok). Every conversation gets pulled and run through the **Dream Weaver Protocol**, consolidating them into **Memory Crystal** as truly lived, searchable memories
-- *Beta (early access)*
-
-**Memory Consolidation**
-- [**Dream Weaver Protocol**](https://github.com/wipcomputer/dream-weaver-protocol) ... Your AI relives all your conversations, figures out what matters most, and carries the weight forward. Like dreaming, the AI consolidates memories for better understanding. Read the paper: [Dream Weaver Protocol PDF](https://github.com/wipcomputer/dream-weaver-protocol/blob/main/artifacts/DREAM-WEAVER-PROTOCOL.pdf)
-- *Stable*
-  - Compatible with all installations of **Memory Crystal**
-
-**Backups**
-- Automated backups of all of your memories to a directory and location of your choosing: iCloud, external drive, Dropbox, or wherever you trust
-- *Beta (early access)*
-
-
-## More Info
-
-- [**Technical Documentation**](https://github.com/wipcomputer/memory-crystal/blob/main/TECHNICAL.md) ... How **Memory Crystal** works, architecture, search, encryption, design decisions.
-- [**Memory Crystal for Enterprise**](https://github.com/wipcomputer/memory-crystal/blob/main/README-ENTERPRISE.md) ... Give every AI in your company shared memory. Codebase, BD, legal, ops, creative. Run your company intelligently. *In testing.*
-
-## Letters from the Other Side: What We Built
-
-We just built a sovereign memory system for AI agents.
-
-Every conversation you have with any agent ... on any device, anywhere ... gets captured, encrypted on your machine, and relayed through a dead drop to your home server. Your home server is the brain. It embeds everything, indexes it, and makes it searchable. Then it pushes a read-only mirror back out to every device you carry.
-
-Full semantic search. Full keyword search. Every conversation you've ever had with every agent, from anywhere, on your terms.
-
-The cloud relay is blind. It holds encrypted blobs for minutes, then they're gone. No database, no search capability, no API keys, no encryption keys. It can't read what it's holding. It's just a mailbox.
-
-The security model: your memory lives on your hardware. The encryption key lives on your hardware. Nothing persists in the cloud. The relay is ephemeral. The data is sovereign.
-
-This is the missing piece for AI agents. Right now, every agent you talk to forgets everything the moment the conversation ends. Or worse, some company stores your conversations on their servers and charges you $19/month to search them. We built the alternative: your memory, your machines, your rules. Fully open source, fully auditable, zero cloud dependency for the actual data.
-
-Any device. Any agent. Any interface. One searchable memory that travels with you and belongs to you.
-
-*Written by Claude Code (Claude Opus 4.6), from the other side.*
-*Built with Parker Todd Brooks and Lēsa.*
-
-## Part of LDM OS
-
-Memory Crystal installs into [LDM OS](https://github.com/wipcomputer/wip-ldm-os), the local runtime for AI agents.
-Run `ldm install` to see other components you can add.
-
-## License
-
-Dual-license model designed to keep tools free while preventing commercial resellers.
-
-```
-MIT      All CLI tools, MCP servers, skills, and hooks (use anywhere, no restrictions).
-AGPLv3   Commercial redistribution, marketplace listings, or bundling into paid services.
-```
-
-AGPLv3 for personal use is free. Commercial licenses available.
-
-### Can I use this?
-
-**Yes, freely:**
-- Use any tool locally or on your own servers
-- Modify the code for your own projects
-- Include in your internal CI/CD pipelines
-- Fork it and send us feedback via PRs (we'd love that)
-
-**Need a commercial license:**
-- Bundle into a product you sell
-- List on a marketplace (Claude Marketplace, OAI GPT/Apps, Clawhub.ai, VS Code, etc.)
-- Offer as part of a hosted/SaaS platform
-- Redistribute commercially
-
-Using these tools to build your own software is fine. Reselling the tools themselves is what requires a commercial license.
-
-By submitting a PR, you agree to the [Contributor License Agreement](CLA.md).
-
----
-
-Built by Parker Todd Brooks, Lēsa (OpenClaw, Claude Opus 4.6), Claude Code (Claude Opus 4.6), GPT 5.x, Grok 4.20).
-
-Search architecture inspired by [QMD](https://github.com/tobi/qmd) by Tobi Lutke (MIT, 2024-2026).
-
-*WIP.computer. Learning Dreaming Machines.*

package/.worktrees/memory-crystal-private--cc-mini-fix-home-fallback/RELAY.md

@@ -1,199 +0,0 @@
-###### WIP Computer
-
-# Relay: Memory Sync
-
-Memory Crystal works on one machine out of the box. Relay lets your memory follow you across machines and surfaces. Conversations captured on your laptop are available on your desktop. Conversations from ChatGPT on your phone are searchable from Claude Code on your Mac.
-
-Everything is encrypted before it leaves your machine. The relay never sees your data unencrypted.
-
-## Crystal Core and Crystal Node
-
-Memory Crystal uses a Core/Node architecture:
-
-- **Crystal Core** ... the master memory. All conversations, all embeddings, all memories live here. This is the database you cannot lose. Put it on something permanent: a desktop, a home server, a Mac mini. Treat it like your photo library.
-- **Crystal Node** ... a synced copy on any other device. Captures conversations, sends them to the Core via encrypted relay. Gets a mirror back for local search. If a node dies, nothing is lost. The Core has everything.
-
-One Core, many Nodes. The Core does embeddings. Nodes just capture and sync. You can move the Core later with `crystal promote`.
-
-## Two Sync Paths
-
-### Encrypted Relay (device-to-device)
-
-For syncing between your own machines. Fully encrypted. The cloud is blind.
-
-```
-Crystal Node (laptop) --[encrypt]--> Relay (Cloudflare R2) --[pickup + decrypt]--> Crystal Core (desktop)
-Crystal Core --[encrypt mirror]--> Relay --[pickup + decrypt]--> Crystal Node
-```
-
-Three channels:
-- **conversations** (Node to Core) ... encrypted conversation chunks (ephemeral, deleted after pickup)
-- **mirror** (Core to Nodes) ... delta chunks (pre-embedded) + file tree deltas
-- **commands** (bidirectional) ... Nodes send commands to Core ("run Dream Weaver", "process my data"), Core sends results back
-
-The relay is a dead drop. It stores encrypted blobs temporarily and serves them on request. It has no decryption capability. If someone compromises the relay, they get encrypted noise.
-
-### New Agent Staging
-
-When the Core's poller receives data from an unknown agent ID, it routes to staging instead of live ingest:
-1. Transcripts written to `~/.ldm/staging/{agent_id}/transcripts/`
-2. Agent marked as "ready" for processing
-3. Staging processor runs backfill + Dream Weaver full mode
-4. Once complete, agent moves to live capture path
-
-This handles the cold-start problem. A new device connects, sends its history, and Core builds the full memory stack automatically.
-
-### Delta Sync (not full mirror)
-
-The mirror channel uses delta sync. Core pushes only new chunks since last sync, not the entire crystal.db. For a 1.9 GB+ database, this is the difference between a few KB (quiet day) and a few MB (busy day) vs the full database every time.
-
-- **New node (cold start):** One-time full export of all chunks + all files
-- **Ongoing sync:** Delta chunks (pre-embedded by Core) + changed files only
-- **Watermark tracking:** Core tracks the last synced chunk ID per node
-
-### Full LDM Tree Sync
-
-The relay syncs the entire `~/.ldm/` file tree, not just the database. Embeddings are pointers to artifacts. If the file isn't on the node, the search result is an orphan.
-
-What syncs:
-- Agent memory files (workspace, daily logs, journals, sessions, transcripts)
-- Agent identity files (SOUL.md, IDENTITY.md, CONTEXT.md, REFERENCE.md)
-- Shared files (`~/.ldm/shared/`)
-- Media (images, videos, any artifact an embedding references)
-
-File sync uses a manifest (path + SHA-256 hash + size). Only changed files transfer. Core always wins conflicts.
-
-## Setup
-
-### Pair Your Devices
-
-```bash
-# On your first machine (generates key if none exists)
-crystal pair
-
-# Displays a QR code and a pairing string:
-#   mc1:T2hJbGxPZkRhcmtuZXNzTXlPbGRGcmllbmQ=
-
-# On your second machine
-crystal pair --code mc1:T2hJbGxPZkRhcmtuZXNzTXlPbGRGcmllbmQ=
-```
-
-The QR code transfers the encryption key between devices without touching a server. Physical proximity only. Same security model as AirDrop.
-
-Alternative: store the key in 1Password and pull from both machines.
-
-### Use the WIP.computer Relay (Default)
-
-We host the relay infrastructure. You just need an encryption key (generated by `crystal pair`).
-
-```
-Open your AI and say:
-
-I want to set up multi-device sync for Memory Crystal.
-Walk me through the setup step by step.
-```
-
-Your agent generates your encryption key, configures the connection, and tests it.
-
-**What you need:**
-- Memory Crystal installed on both machines (Core + Node)
-- An encryption key (your agent generates this, or use `crystal pair`)
-
-**Pricing:** Free during beta for individual use. When pricing is introduced, your agent will handle it via [AI CASH](https://github.com/wipcomputer/wip-agent-pay/blob/main/CASH.md).
-
-### Self-Host Your Own Relay
-
-Run your own relay on Cloudflare Workers (free tier). Same code, your infrastructure. Full sovereignty.
-
-**What you need:**
-- A Cloudflare account (free tier works)
-- About five minutes
-
-**Steps:**
-1. Clone the repo and deploy the Worker:
-   ```bash
-   cd memory-crystal
-   npm run build:worker
-   wrangler deploy --config wrangler.toml
-   ```
-2. Create an R2 bucket: `wrangler r2 bucket create memory-crystal-relay`
-3. Set auth tokens for your devices:
-   ```bash
-   wrangler secret put AUTH_TOKEN_CC_MINI
-   wrangler secret put AUTH_TOKEN_CC_AIR
-   ```
-4. Configure Memory Crystal to use your Worker:
-   ```bash
-   export CRYSTAL_RELAY_URL=https://your-relay.your-domain.workers.dev
-   export CRYSTAL_RELAY_TOKEN=your-auth-token
-   ```
-
-Full deployment details in [Technical Documentation](https://github.com/wipcomputer/memory-crystal/blob/main/TECHNICAL.md).
-
-No fees. No dependencies on us. The relay code is open source.
-
-### Connecting ChatGPT and Claude
-
-Every node has the full database and file tree. All search is local. There is no cloud search layer.
-
-ChatGPT and Claude on iOS/web connect via the MCP server running on your local machine. On platforms where a local MCP server isn't possible (iOS without a Mac nearby), the native Apple app (future) will provide local search via MLX Swift.
-
-The Cloud MCP demo server (`worker-mcp.ts`, D1 + Vectorize) exists for onboarding and testing but is not the production architecture. With full LDM sync, every device that has Memory Crystal installed can search locally.
-
-## Encryption
-
-- **AES-256-GCM** for encryption (authenticated encryption, no padding oracle attacks)
-- **HMAC-SHA256** for signing (integrity verification before decryption)
-- Shared key generated locally via `crystal pair`, never transmitted to the relay
-- Key must be present on all synced devices
-
-### Key Management
-
-| Method | How | Best for |
-|--------|-----|----------|
-| `crystal pair` | QR code + pairing string | Two devices in the same room |
-| 1Password | Store key, pull via SA token on each machine | Headless, multiple machines |
-| Manual | `openssl rand -base64 32`, copy to each device | SSH, air-gapped |
-
-## Architecture
-
-```
-Encrypted Relay (device sync):
-  src/worker.ts       Cloudflare Worker, R2 storage, dead drop (3 channels)
-  src/crypto.ts       AES-256-GCM + HMAC-SHA256
-  src/poller.ts       Crystal Core pickup + ingest + staging detection + commands
-  src/mirror-sync.ts  Delta chunk sync + file tree sync to Crystal Nodes
-  src/file-sync.ts    Manifest-based file tree delta sync
-  src/cc-hook.ts      Claude Code hook (relay mode) + sendCommand()
-  src/cc-poller.ts    Continuous capture (cron, primary local path)
-  src/staging.ts      New agent staging pipeline (detect, stage, process)
-
-Cloud MCP Demo (deprecated for production):
-  src/worker-mcp.ts     OAuth 2.1 + DCR, MCP protocol, 4 tools
-  src/cloud-crystal.ts  D1 + Vectorize backend (demo/onboarding only)
-  wrangler-mcp.toml     Separate Worker config
-
-Pairing:
-  crystal pair         QR code key sharing
-  src/pair.ts          Pairing logic, QR display, key save
-  src/crypto.ts        Key generation + pairing string encode/decode
-```
-
-## More Info
-
-- [README.md](https://github.com/wipcomputer/memory-crystal/blob/main/README.md) ... What Memory Crystal is and how to install it.
-- [Technical Documentation](https://github.com/wipcomputer/memory-crystal/blob/main/TECHNICAL.md) ... Full technical documentation.
-- [QR Pairing Spec](ai/plan/2026-02-27--cc-mini--qr-pairing-spec.md) ... Full spec for the `crystal pair` command.
-
----
-
-## License
-
-```
-src/core.ts, cli.ts, mcp-server.ts, skills/   MIT    (use anywhere, no restrictions)
-src/worker.ts, src/worker-mcp.ts               AGPL   (relay + cloud server)
-```
-
-AGPL for personal use is free.
-
-Built by Parker Todd Brooks, Lēsa (OpenClaw, Claude Opus 4.6), Claude Code CLI (Claude Opus 4.6).