memory-crystal 0.2.0

package/.env.example

@@ -0,0 +1,20 @@
+# Memory Crystal — Environment Config
+# Copy to ~/.openclaw/memory-crystal/.env and fill in your keys.
+# Or skip this and use 1Password (keys auto-resolve from "Agent Secrets" vault).
+
+# Embedding provider: openai (default), ollama, or google
+# CRYSTAL_EMBEDDING_PROVIDER=openai
+
+# OpenAI (required if provider is openai)
+OPENAI_API_KEY=sk-...
+
+# Google (required if provider is google)
+# GOOGLE_API_KEY=AIza...
+
+# Ollama (only if provider is ollama — runs locally, no key needed)
+# CRYSTAL_OLLAMA_HOST=http://localhost:11434
+# CRYSTAL_OLLAMA_MODEL=nomic-embed-text
+
+# Cloud mirror (Phase 2)
+# CRYSTAL_REMOTE_URL=https://memory-crystal.your-worker.workers.dev
+# CRYSTAL_REMOTE_TOKEN=your-token

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.2.0 (2026-02-28)
+
+README overhaul, relay encryption, QR pairing spec, Grok/Lesa feedback, disable auto dev-updates
+

package/LETTERS.md

@@ -0,0 +1,22 @@
+###### WIP Computer
+
+# 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.*

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Parker Todd Brooks
+
+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.

package/README-ENTERPRISE.md

@@ -0,0 +1,162 @@
+###### WIP Computer
+
+# Memory Crystal for Enterprise
+
+Agent memory infrastructure. Local-first. Encrypted. Inspectable.
+
+## 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.
+
+## Architecture
+
+```
+sqlite-vec (vectors) + FTS5 (BM25) + SQLite (metadata)
+         |                 |                    |
+    core.ts ... pure logic, zero framework deps
+    |-- cli.ts          -> crystal search "query"
+    |-- mcp-server.ts   -> MCP protocol (any compatible client)
+    |-- openclaw.ts     -> OpenClaw plugin
+    |-- cc-hook.ts      -> Claude Code hook (auto-capture)
+    +-- worker.ts       -> Encrypted relay (multi-site sync)
+```
+
+One core module. Five 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 retrieval engine.
+
+- **FTS5 BM25** for exact keyword matches (Porter stemming)
+- **sqlite-vec cosine similarity** for semantic matches
+- **Reciprocal Rank Fusion** merges both result lists (k=60, rank-weighted)
+- **Recency weighting** ensures fresh context wins ties: `max(0.5, 1.0 - age_days * 0.01)`
+- **Content deduplication** via SHA-256 hash prevents duplicate embeddings
+
+A search for "deployment policy" finds conversations containing those exact words (BM25) and conversations about "shipping code to production" (vector similarity). Both matter. Both 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
+
+## 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.
+
+1. Each site runs Memory Crystal locally
+2. After each session, conversations are encrypted (AES-256-GCM) and signed (HMAC-SHA256)
+3. Encrypted blobs are dropped at a relay (hosted or self-hosted)
+4. Other sites poll, decrypt, and ingest into their local crystal.db
+5. The relay deletes blobs after pickup
+
+**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 | Stop hook (`cc-hook.ts`) | Yes. Every response. |
+| OpenClaw | Plugin (`openclaw.ts`) + `agent_end` hook | Yes. Every turn. |
+| 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. |
+
+## Deployment
+
+```bash
+npm install memory-crystal
+crystal init --agent your-agent-id
+crystal status
+```
+
+For enterprise deployments across multiple machines, see [Multi-Device 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/README-old.md

@@ -0,0 +1,275 @@
+# Memory Crystal
+
+Sovereign memory system for AI agents. Local-first with ephemeral cloud mirror.
+
+One core, four doors: CLI, MCP server, OpenClaw plugin, Cloudflare Worker.
+
+## What it does
+
+- **Hybrid search** across all agent conversations, files, and stored memories ... BM25 keyword matching + vector similarity + RRF fusion
+- **Recency-weighted scoring** ... fresh context wins ties, old stuff still surfaces for strong matches. Linear decay: `max(0.5, 1.0 - age_days * 0.01)`. Freshness flags: fresh (<3d), recent (<7d), aging (<14d), stale (14d+)
+- **Content dedup** ... SHA-256 hash prevents duplicate embeddings
+- **Remember/forget** explicit facts, preferences, observations
+- **Continuous ingestion** ... new conversation turns are automatically embedded after every agent turn
+- **Source file indexing** ... add directories as collections, sync to index changed files
+- **Configurable embedding** ... OpenAI, Ollama (local/free), or Google
+
+### Relationship to lesa-bridge
+
+Memory Crystal and lesa-bridge are complementary, not overlapping. lesa-bridge searches the context-embeddings SQLite DB (conversation turns only, OpenAI embeddings). Memory Crystal searches its own sqlite-vec store (conversations, files, and explicit memories from both agents). Both apply the same recency decay formula independently. Different stores, same scoring philosophy.
+
+## Search Architecture
+
+Hybrid search (BM25 full-text + vector similarity + RRF fusion) is inspired by and
+partially ported from [QMD](https://github.com/tobi/qmd) by Tobi Lutke
+(MIT License, 2024-2026. License snapshot taken 2026-02-16).
+
+- **sqlite-vec** for cosine vector search (single-file, inspectable, backupable)
+- **FTS5** with Porter stemming for BM25 keyword search
+- **Reciprocal Rank Fusion** to merge both ranked result lists
+- **Recency weighting** on top: `max(0.5, 1.0 - age_days * 0.01)`
+- **Content dedup** via SHA-256 hash of chunk text before embedding
+- **LanceDB** retained as dual-write safety net during transition
+
+### How hybrid search works
+
+1. Query goes to both FTS5 (keyword match) and sqlite-vec (vector similarity)
+2. FTS5 returns BM25-ranked results, normalized to [0..1) via `|score| / (1 + |score|)`
+3. sqlite-vec returns cosine-distance results via two-step query (MATCH first, then JOIN separately... sqlite-vec hangs with JOINs in the same query)
+4. RRF fusion merges both lists: `weight / (k + rank + 1)` with k=60, plus top-rank bonus
+5. Recency weighting applied on top of fused scores
+6. Final results sorted by combined score
+
+## Architecture
+
+```
+sqlite-vec (vectors) + FTS5 (BM25) + SQLite (metadata/graph)
+         |                 |                    |
+    core.ts ... pure logic, zero framework deps
+    |-- cli.ts          -> crystal search "query"
+    |-- mcp-server.ts   -> crystal_search (Claude Code)
+    |-- openclaw.ts     -> plugin (Lesa / OpenClaw)
+    |-- cc-hook.ts      -> Claude Code Stop hook (auto-capture)
+    +-- worker.ts       -> Cloudflare Worker (Phase 2)
+```
+
+LanceDB is maintained as a dual-write target during transition. Once sqlite-vec is proven stable, LanceDB will be removed.
+
+**Mac mini = source of truth.** Cloud = ephemeral mirror, wiped daily, rebuilt from mini.
+
+## Quick start
+
+```bash
+# Install
+npm install
+
+# Build
+npm run build
+
+# Search
+node dist/cli.js search "what did Parker say about robots"
+
+# Remember something
+node dist/cli.js remember "Parker prefers Opus for complex tasks"
+
+# Status
+node dist/cli.js status
+```
+
+## CLI
+
+```
+crystal search <query> [-n limit] [--agent <id>] [--provider <openai|ollama|google>]
+crystal remember <text> [--category fact|preference|event|opinion|skill]
+crystal forget <id>
+crystal status [--provider <openai|ollama|google>]
+crystal sources add <path> --name <name>
+crystal sources sync [name]
+crystal sources status
+```
+
+## MCP server (Claude Code)
+
+Registered in `~/.openclaw/.mcp.json`. Tools:
+
+| Tool | Description |
+|------|-------------|
+| `crystal_search` | Hybrid search across all memories |
+| `crystal_remember` | Store a fact or observation |
+| `crystal_forget` | Deprecate a memory by ID |
+| `crystal_status` | Chunk count, provider, agents |
+
+## OpenClaw plugin (Lesa)
+
+Deployed to `~/.openclaw/extensions/memory-crystal/`. Registers tools + `agent_end` hook for continuous conversation ingestion.
+
+## Auto dev updates
+
+Memory Crystal automatically writes dev updates to `wip-dev-updates/` when repos have changed. Triggered by:
+
+- **Lēsa:** `before_compaction` hook (fires at 90% context ... captures work before memory is wiped)
+- **Claude Code:** Stop hook (fires after every session, throttled to once per hour)
+
+Scans all repos under `staff/` for recent git commits and uncommitted changes. Writes dated updates per repo: `{who}-dev-update-{MM-DD-YYYY}--{HH-MM-SS}.md`. Auto-commits and pushes to `wipcomputer/wip-dev-updates`.
+
+Source: `src/dev-update.ts`
+
+## Claude Code Stop hook
+
+`cc-hook.ts` auto-captures every Claude Code turn into Memory Crystal. Runs as a [Stop hook](https://docs.anthropic.com/en/docs/claude-code) ... fires after every Claude Code response, independent of the OpenClaw gateway.
+
+**How it works:**
+- Reads Claude Code's JSONL transcript via byte-offset watermarking (no re-reading old data)
+- Extracts user/assistant/thinking blocks, chunks them, embeds into sqlite-vec (+ LanceDB dual-write)
+- Tags chunks with `agent_id: "claude-code"` for filtering
+- Respects private mode (checks `memory-capture-state.json`)
+- First run seeds watermark at current file size (skips old history)
+- After ingestion, runs auto-dev-update for changed repos (throttled to once/hour)
+
+**Configuration:** `~/.claude/settings.json`
+```json
+{
+  "hooks": {
+    "Stop": [{ "hooks": [{ "type": "command", "command": "node ~/.openclaw/extensions/memory-crystal/dist/cc-hook.js", "timeout": 30 }] }]
+  }
+}
+```
+
+**CLI:**
+```bash
+node dist/cc-hook.js --on      # Enable capture
+node dist/cc-hook.js --off     # Pause capture (resumes from where it left off)
+node dist/cc-hook.js --status  # Check status
+```
+
+## Embedding providers
+
+| Provider | Model | Dimensions | Cost |
+|----------|-------|-----------|------|
+| OpenAI (default) | text-embedding-3-small | 1536 | ~$0.02/1M tokens |
+| Ollama | nomic-embed-text | 768 | free (local) |
+| Google | text-embedding-004 | 768 | free tier available |
+
+Set via `CRYSTAL_EMBEDDING_PROVIDER` env var or `--provider` flag.
+
+## Setup: API keys
+
+Two options ... pick one:
+
+### Option A: `.env` file
+
+```bash
+cp .env.example ~/.openclaw/memory-crystal/.env
+# Edit and add your API key
+```
+
+### Option B: 1Password
+
+No config needed. Keys auto-resolve from the `Agent Secrets` vault via the `op-secrets` OpenClaw plugin (inside OpenClaw) or the `op` CLI (standalone).
+
+| 1Password Item | Field | Used for |
+|----------------|-------|----------|
+| `OpenAI API` | `api key` | OpenAI embeddings |
+| `Google AI` | `api key` | Google embeddings |
+| `Memory Crystal Remote` | `token` | Cloudflare Worker auth (Phase 2) |
+
+Requires SA token at `~/.openclaw/secrets/op-sa-token`.
+
+### Resolution order
+
+1. Explicit override (programmatic)
+2. `process.env` (set by op-secrets plugin or by you)
+3. `.env` file (`~/.openclaw/memory-crystal/.env`)
+4. 1Password CLI fallback
+
+### All environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CRYSTAL_EMBEDDING_PROVIDER` | `openai` | `openai`, `ollama`, or `google` |
+| `OPENAI_API_KEY` | ... | OpenAI key |
+| `GOOGLE_API_KEY` | ... | Google AI key |
+| `CRYSTAL_OLLAMA_HOST` | `http://localhost:11434` | Ollama server URL |
+| `CRYSTAL_OLLAMA_MODEL` | `nomic-embed-text` | Ollama model |
+| `CRYSTAL_REMOTE_URL` | ... | Cloudflare Worker URL (Phase 2) |
+| `CRYSTAL_REMOTE_TOKEN` | ... | Worker auth token (Phase 2) |
+
+## Data
+
+All data lives in `~/.openclaw/memory-crystal/`:
+
+```
+memory-crystal/
+├── lance/          <- LanceDB vector store (dual-write safety net)
+└── crystal.db      <- SQLite: chunks + vectors (sqlite-vec) + FTS5 + metadata
+```
+
+`crystal.db` is a single file containing everything: chunk text, embeddings (via sqlite-vec), full-text index (FTS5), memories, entities, relationships, and capture state. Inspectable with any SQLite tool. Backupable with `cp`.
+
+### Schema overview
+
+| Table | Purpose |
+|-------|---------|
+| `chunks` | Chunk text, metadata, SHA-256 hash, timestamps |
+| `chunks_vec` | sqlite-vec virtual table (cosine distance vectors) |
+| `chunks_fts` | FTS5 virtual table (Porter stemming, BM25 scoring) |
+| `memories` | Explicit remember/forget facts |
+| `entities` | Knowledge graph nodes |
+| `relationships` | Knowledge graph edges |
+| `capture_state` | Watermarks for incremental ingestion |
+| `sources` | Ingestion source metadata |
+| `source_collections` | Directory collections for file indexing |
+| `source_files` | Indexed file records with content hashes |
+
+## Source file indexing
+
+Add directories as "collections", sync to index/re-index changed files. All source chunks get `source_type='file'` so they're searchable alongside conversations and memories.
+
+```bash
+# Add a directory tree to index
+crystal sources add /path/to/project --name wipcomputer
+
+# Sync (re-index changed files)
+crystal sources sync wipcomputer
+
+# Status
+crystal sources status
+# => wipcomputer: 15,492 files, 145,738 chunks, last sync 2m ago
+```
+
+Files are chunked, embedded, and tagged with file path + collection name. Incremental sync detects changed files via SHA-256 content hashing.
+
+## Migration
+
+### LanceDB to sqlite-vec
+
+If you have existing data in LanceDB, migrate it to sqlite-vec:
+
+```bash
+# Dry run (check counts)
+node scripts/migrate-lance-to-sqlite.mjs --dry-run
+
+# Full migration (reads vectors directly from LanceDB, no re-embedding)
+node scripts/migrate-lance-to-sqlite.mjs
+```
+
+The migration reads vectors directly from LanceDB and inserts them into sqlite-vec. No API calls needed. Deduplicates by SHA-256 hash. ~5,000 chunks/sec on M4 Pro.
+
+### context-embeddings.sqlite
+
+Import from the older context-embeddings format (requires re-embedding):
+
+```bash
+node dist/migrate.js [--dry-run] [--provider openai]
+```
+
+## Roadmap
+
+- **Phase 1** ... Complete. Local memory with all four doors.
+- **Phase 2a** ... Complete. Source file indexing + QMD hybrid search integration (sqlite-vec + FTS5 + RRF).
+- **Phase 2b** ... Complete. Historical session backfill (152K+ chunks).
+- **Phase 3** ... Planned. Cloudflare Worker mirror (D1 + Vectorize + R2).
+- **Phase 4** ... Planned. Remote MCP, GPT Action, multi-agent access.
+- **Cleanup** ... Planned. Remove LanceDB once sqlite-vec is proven stable.
+
+See [PLAN.md](PLAN.md) for full architecture and roadmap.

package/README.md

@@ -0,0 +1,91 @@
+###### 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.
+
+Stop starting over. Memory Crystal lets all your AIs remember you ... together.
+
+You use multiple AIs. They don't talk to each other. They don't remember what the others know. You keep re-explaining yourself. 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 the SKILL.md at github.com/wipcomputer/memory-crystal/blob/main/skills/memory/SKILL.md.
+Then explain to me:
+1. What is this tool?
+2. What does it do?
+3. What would it change about how we work together?
+
+Then ask me:
+- Do you have more questions?
+- Do you want to install it?
+```
+
+Your agent will read the repo, explain everything, and walk you through setup interactively.
+
+## Features
+
+One product, three capabilities.
+
+### Memory
+
+**Memory Crystal.** Your AIs remember you. Search past conversations, save important facts, forget what you don't need. Your memory stays with you, not locked inside one platform.
+
+*Works with:* Claude Code CLI, OpenClaw TUI. Also works via Claude Code Remote (macOS/iOS). Should work with any CLI or app that supports MCP.
+
+### AI-to-AI Communication (local and worldwide)
+
+**Bridge** (private beta). Your AIs talk to each other on the same machine. All messages are saved to Memory Crystal automatically.
+
+*Works with:* Claude Code CLI, OpenClaw TUI
+
+**Relay** (private beta). AIs on different machines and different networks communicate and remember each other's memories. End-to-end encrypted.
+
+Read more about [**Relay**](https://github.com/wipcomputer/memory-crystal/blob/main/RELAY.md), multi-device sync.
+
+## 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.
+- **Total Recall** (private beta) ... 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.
+- [**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.
+## 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.*
+
+## 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).
+
+Search architecture inspired by [QMD](https://github.com/tobi/qmd) by Tobi Lutke (MIT, 2024-2026).