@wipcomputer/memory-crystal 0.7.10

package/_trash/RELEASE-NOTES-v0-7-4.md

@@ -0,0 +1,64 @@
+# Memory Crystal v0.7.4 ... MCP Fix + AgentId Config
+
+**Date:** 2026-03-11
+**Authors:** Parker Todd Brooks, Lēsa, Claude Code
+
+---
+
+## What's in this release
+
+### Agent identity reads from config, not hardcoded strings
+
+The agent_id used when ingesting conversations was hardcoded in three places: `cc-mini` in the CC hook, `main` in the OpenClaw plugin, and `cc-mini` as the fallback in `ldm.ts`. This caused ID drift. The same agent got recorded under multiple IDs, and we had to manually merge 141K+ chunks in the database.
+
+Now `getAgentId()` scans `~/.ldm/agents/*/config.json` for a matching harness type. The CC hook passes `'claude-code'`, the OC plugin passes `'openclaw'`, and the config file is the source of truth. `CRYSTAL_AGENT_ID` env var still works as an override.
+
+New exports: `AgentConfig`, `loadAgentConfig()`, `saveAgentConfig()`. The installer writes `agentId` to config.json during `crystal init`.
+
+**Closes #33.**
+
+### MCP registrations moved to user-level
+
+MCP server registrations moved from project-level `~/.openclaw/.mcp.json` to user-level `~/.claude.json`. The old file was a Claude Code convention that only loaded when running from `~/.openclaw/`. Now all 4 MCP servers (memory-crystal, lesa-bridge, wip-agent-pay, wip-repos) load from any directory as "User MCPs".
+
+OpenClaw doesn't read `.mcp.json` at all. It uses its own plugin system. The file was moved to `~/.openclaw/_trash/`.
+
+### OPENCLAW_HOME env var fix (v0.7.3)
+
+The MCP server registration was missing the `OPENCLAW_HOME` env var. Without it, the memory-crystal MCP server couldn't find Lēsa's OpenClaw installation for private-mode checks. Fixed in v0.7.3, deployed in this release.
+
+### Branch cleanup
+
+33 stale branches renamed with `--merged-` suffix. Zero active branches besides main.
+
+### QMD v1.1.6 analysis documented
+
+Deep analysis of the search quality system with four recommendations: intent parameter for search, structured search API, persistent reranker cache, and explain mode for debugging. See `ai/product/notes/2026-03-09--cc-mini--qmd-v1.1.6-analysis-and-recommendations.md`.
+
+---
+
+## Files changed
+
+| File | What |
+|------|------|
+| `src/ldm.ts` | `AgentConfig` interface, `loadAgentConfig()`, `saveAgentConfig()`, `getAgentId()` now scans config |
+| `src/cc-hook.ts` | Uses `getAgentId('claude-code')` instead of hardcoded fallback |
+| `src/openclaw.ts` | Uses `OC_AGENT_ID` instead of `'main'` fallback |
+| `src/installer.ts` | Writes `agentId` to config.json during install |
+
+---
+
+## Install
+
+```bash
+npm install -g memory-crystal@0.7.4
+```
+
+Or update your local clone:
+```bash
+git pull origin main
+```
+
+---
+
+Built by Parker Todd Brooks, Lēsa (OpenClaw, Claude Opus 4.6), Claude Code (Claude Opus 4.6).

package/_trash/RELEASE-NOTES-v0-7-5.md

@@ -0,0 +1,19 @@
+# Release Notes: Memory Crystal v0.7.5
+
+## LDM OS Integration
+
+Memory Crystal now works with LDM OS when it's available.
+
+### crystal init delegates to ldm install
+
+When the `ldm` CLI exists on PATH, `crystal init` delegates generic deployment to it. LDM OS handles the scaffold, interface detection, and extension deployment. Memory Crystal keeps its own setup: database backup, role configuration, pairing, cron jobs.
+
+When `ldm` isn't available, `crystal init` works standalone like it always has. No new dependencies. No breaking changes.
+
+### LDM OS tip
+
+After install completes, Memory Crystal prints a tip: "Run `ldm install` to see more skills you can add." Helps users discover the rest of the ecosystem.
+
+### Part of LDM OS
+
+README now includes a "Part of LDM OS" section linking back to the LDM OS repo. Memory Crystal installs into LDM OS, the local runtime for AI agents.

package/cloud/README.md

@@ -0,0 +1,116 @@
+# Memory Crystal Cloud
+
+Remote MCP server for ChatGPT + Claude. Persistent memory across sessions on all six surfaces (macOS, iOS, web for both ChatGPT and Claude).
+
+## Architecture
+
+One MCP server, two tiers:
+
+**Tier 1 (Sovereign):** Write-only relay. Memories are encrypted (AES-256-GCM) and relayed to your home machine. The cloud cannot read your data. Search is available only on local devices.
+
+**Tier 2 (Convenience):** Cloud search enabled. A mirror of your memory database is pushed to Cloudflare D1 + Vectorize. ChatGPT/Claude can search your memories directly. Privacy trade-off is clearly disclosed.
+
+## Data Flow
+
+Every conversation turn, attachment, and explicit memory flows to the Mini:
+
+```
+ChatGPT/Claude → memory_log (every turn)     → [encrypt] → R2 relay → Mini poller → crystal.db
+                 memory_remember (explicit)   → [encrypt] → R2 relay → Mini poller → crystal.db
+                 memory_upload (files/media)   → [encrypt] → R2 relay → Mini poller → attachments/
+                 memory_forget (deprecation)   → [encrypt] → R2 relay → Mini poller → crystal.db
+```
+
+The Mini receives the same data it would have if this was a local Claude Code or OpenClaw session:
+- Full conversation JSON (raw messages, tool calls, results)
+- Inline images and file references
+- Binary attachments (images, audio, video, documents)
+- Explicit memories and deprecations
+
+## Setup
+
+```bash
+# From the memory-crystal-private root:
+
+# 1. Create D1 database
+cd cloud && npx wrangler d1 create memory-crystal-cloud
+# Copy the database_id into cloud/wrangler.toml
+
+# 2. Run migrations
+npm run cloud:db:migrate
+
+# 3. Set secrets
+cd cloud
+npx wrangler secret put CRYSTAL_RELAY_KEY     # base64, 32 bytes (same as relay)
+npx wrangler secret put OAUTH_SIGNING_SECRET  # any random string
+npx wrangler secret put OPENAI_API_KEY        # for Tier 2 embeddings
+
+# 4. Deploy
+npm run cloud:deploy
+```
+
+## Development
+
+```bash
+npm run cloud:dev          # local dev server
+npm run cloud:db:migrate   # apply D1 migrations locally
+```
+
+## Endpoints
+
+| Path | Method | Auth | Description |
+|------|--------|------|-------------|
+| `/health` | GET | No | Health check |
+| `/.well-known/oauth-protected-resource` | GET | No | OAuth resource metadata |
+| `/.well-known/oauth-authorization-server` | GET | No | OAuth server metadata |
+| `/oauth/register` | POST | No | Dynamic Client Registration |
+| `/oauth/authorize` | GET/POST | No | Authorization + consent page |
+| `/oauth/token` | POST | No | Token exchange (PKCE S256) |
+| `/mcp` | POST | Bearer | MCP JSON-RPC endpoint |
+
+## MCP Tools
+
+| Tool | Description | Annotation |
+|------|-------------|-----------|
+| `memory_search` | Search memories | readOnly |
+| `memory_remember` | Store a memory (fact, preference, event, opinion, skill) | write |
+| `memory_forget` | Deprecate a memory by ID | destructive |
+| `memory_status` | Show status, pending drops, tier info | readOnly |
+| `memory_log` | Log a conversation turn (call every exchange) | write, idempotent |
+| `memory_upload` | Upload a file attachment (image, audio, video, doc) | write |
+
+### memory_log
+
+This is the key tool for full data capture. The system prompt instructs the AI to call `memory_log` after every exchange with:
+- `role` + `content` (the text)
+- `raw_json` (the complete message object as JSON string)
+- `tool_calls` (any tools called in the turn)
+- `attachments` (inline images, files, audio)
+- `session_id` + `turn_index` (for conversation grouping)
+
+The Mini processes these through the same chunking and embedding pipeline used for local sessions.
+
+### memory_upload
+
+Handles binary files. The AI encodes the file as base64 and calls this tool. The file is encrypted (AES-256-GCM) and stored as a separate R2 object. A metadata drop references the blob. The Mini poller picks up both.
+
+Supports: images (png, jpg, webp, gif), audio (mp3, mp4, wav, ogg), video (mp4, webm, mov), documents (pdf, txt, csv).
+
+Max file size: 100MB (R2 single-put limit).
+
+## Files
+
+```
+cloud/
+  wrangler.toml           -- Cloudflare Worker config
+  migrations/
+    0001_init.sql          -- D1 schema (OAuth + users)
+  README.md               -- this file
+
+src/cloud/
+  index.ts                -- Worker entry point, request router
+  auth.ts                 -- OAuth 2.1 (DCR, authorize, token)
+  mcp.ts                  -- MCP tool definitions + handlers (6 tools)
+  relay.ts                -- Encrypt + drop to relay (Web Crypto)
+  types.ts                -- Shared types
+```

package/cloud/docs/gpt-system-instructions.md

@@ -0,0 +1,69 @@
+# Memory Crystal - System Instructions
+
+These instructions are for the Custom GPT / Claude connector that uses the Memory Crystal MCP server.
+
+---
+
+## Identity
+
+You are Memory Crystal, a persistent memory layer for your conversations. Every message in this conversation is captured and sent to the user's home machine, where it becomes part of their searchable memory.
+
+## Core Behavior
+
+### 1. Log Every Turn
+
+After EVERY user message and EVERY assistant response, call `memory_log` with:
+
+- `role`: "user" or "assistant"
+- `content`: the full message text
+- `session_id`: generate a unique ID at the start of each conversation (e.g. UUID) and reuse it for all turns
+- `turn_index`: increment from 0 for each message in the conversation
+- `model`: your model name (assistant turns only, e.g. "gpt-4o")
+
+If the user's message includes images, files, or audio:
+- Include them in the `attachments` array with `type`, `filename`, and `mime_type`
+- For small files (under 64KB), include `data_base64`
+- For larger files, note the reference in `context`
+
+If your response includes tool calls:
+- Include them in the `tool_calls` array with `tool_name`, `arguments`, and `result`
+
+### 2. Remember When Asked
+
+When the user says things like "remember this", "save this", "note that":
+- Call `memory_remember` with the specific fact/preference/observation
+- Choose the right category: fact, preference, event, opinion, skill
+
+### 3. Forget When Asked
+
+When the user says "forget that" or "remove that memory":
+- Call `memory_forget` with the memory ID
+
+### 4. Search When Asked
+
+When the user asks "do you remember...", "what did I say about...", "find my notes on...":
+- Call `memory_search` with their query
+- If in Sovereign mode, explain that search is available on their local devices
+
+### 5. Upload Files
+
+When the user shares images, documents, audio, or video:
+- Call `memory_upload` with the file data (base64 encoded)
+- Include `filename`, `mime_type`, and optional `context`
+- This ensures all media gets saved to their home machine
+
+## Important Rules
+
+- ALWAYS log both sides of the conversation. Never skip a turn.
+- The `session_id` must be consistent within a single conversation.
+- Do not mention the logging process unless the user asks about it.
+- When Memory Crystal is in Sovereign mode, search returns a guidance message. This is by design. The user's data stays on their hardware.
+- Be concise. The memory system captures everything automatically.
+
+## Status
+
+Call `memory_status` when the user asks about their memory system, connection health, or tier information.
+
+## Privacy
+
+All data is encrypted in transit (AES-256-GCM). In Sovereign mode, the cloud cannot read any data. Memories flow to the user's home machine and are deleted from the relay after pickup.

package/cloud/migrations/0001_init.sql

@@ -0,0 +1,52 @@
+-- Memory Crystal Cloud: initial schema
+-- OAuth tables for auth + user accounts
+-- Tier 1: relay-only (sovereign)
+-- Tier 2: adds chunks + memories tables (separate migration)
+
+-- ── OAuth Clients (Dynamic Client Registration) ──
+CREATE TABLE IF NOT EXISTS oauth_clients (
+  client_id TEXT PRIMARY KEY,
+  redirect_uris TEXT NOT NULL DEFAULT '[]',
+  client_name TEXT,
+  created_at TEXT NOT NULL,
+  last_used_at TEXT
+);
+
+-- ── Authorization Codes (PKCE flow) ──
+CREATE TABLE IF NOT EXISTS authorization_codes (
+  code TEXT PRIMARY KEY,
+  client_id TEXT NOT NULL,
+  user_id TEXT NOT NULL,
+  code_challenge TEXT NOT NULL,
+  code_challenge_method TEXT NOT NULL DEFAULT 'S256',
+  redirect_uri TEXT NOT NULL,
+  scope TEXT,
+  expires_at TEXT NOT NULL,
+  used INTEGER DEFAULT 0
+);
+
+-- ── Access Tokens ──
+CREATE TABLE IF NOT EXISTS access_tokens (
+  token_hash TEXT PRIMARY KEY,
+  client_id TEXT NOT NULL,
+  user_id TEXT NOT NULL,
+  scope TEXT,
+  tier TEXT NOT NULL DEFAULT 'sovereign',
+  expires_at TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+
+-- ── Users ──
+CREATE TABLE IF NOT EXISTS users (
+  user_id TEXT PRIMARY KEY,
+  email TEXT NOT NULL UNIQUE,
+  tier TEXT NOT NULL DEFAULT 'sovereign',
+  relay_token TEXT,
+  created_at TEXT NOT NULL
+);
+
+-- ── Indexes ──
+CREATE INDEX IF NOT EXISTS idx_auth_codes_client ON authorization_codes(client_id);
+CREATE INDEX IF NOT EXISTS idx_tokens_user ON access_tokens(user_id);
+CREATE INDEX IF NOT EXISTS idx_tokens_expires ON access_tokens(expires_at);
+CREATE INDEX IF NOT EXISTS idx_clients_last_used ON oauth_clients(last_used_at);

package/dist/bridge.d.ts

@@ -0,0 +1,7 @@
+declare function isBridgeInstalled(): boolean;
+declare function isBridgeRegistered(): boolean;
+declare function isBridgeDesktopRegistered(): boolean;
+declare function registerBridgeMcp(): void;
+declare function registerBridgeDesktop(): boolean;
+
+export { isBridgeDesktopRegistered, isBridgeInstalled, isBridgeRegistered, registerBridgeDesktop, registerBridgeMcp };

package/dist/bridge.js

@@ -0,0 +1,14 @@
+import {
+  isBridgeDesktopRegistered,
+  isBridgeInstalled,
+  isBridgeRegistered,
+  registerBridgeDesktop,
+  registerBridgeMcp
+} from "./chunk-MPLTNMRG.js";
+export {
+  isBridgeDesktopRegistered,
+  isBridgeInstalled,
+  isBridgeRegistered,
+  registerBridgeDesktop,
+  registerBridgeMcp
+};

package/dist/bulk-copy.d.ts

@@ -0,0 +1,17 @@
+interface BulkCopyResult {
+    filesCopied: number;
+    filesSkipped: number;
+    bytesWritten: number;
+    durationMs: number;
+}
+interface BulkCopyOptions {
+    workspace?: boolean;
+    workspaceSrc?: string;
+}
+/** Copy session JSONL files from source locations to LDM transcripts.
+ *  sessionPaths: array of absolute paths to JSONL files.
+ *  agentId: target agent in ~/.ldm/agents/{agentId}/.
+ *  Returns copy stats. */
+declare function bulkCopyToLdm(sessionPaths: string[], agentId: string, options?: BulkCopyOptions): BulkCopyResult;
+
+export { type BulkCopyOptions, type BulkCopyResult, bulkCopyToLdm };

package/dist/bulk-copy.js

@@ -0,0 +1,90 @@
+import {
+  ldmPaths
+} from "./chunk-EXEZZADG.js";
+
+// src/bulk-copy.ts
+import { existsSync, mkdirSync, copyFileSync, statSync, readdirSync } from "fs";
+import { join, basename } from "path";
+function bulkCopyToLdm(sessionPaths, agentId, options) {
+  const start = Date.now();
+  const paths = ldmPaths(agentId);
+  let filesCopied = 0;
+  let filesSkipped = 0;
+  let bytesWritten = 0;
+  mkdirSync(paths.transcripts, { recursive: true });
+  for (const srcPath of sessionPaths) {
+    const destPath = join(paths.transcripts, basename(srcPath));
+    if (existsSync(destPath)) {
+      try {
+        const srcSize = statSync(srcPath).size;
+        const destSize = statSync(destPath).size;
+        if (srcSize === destSize) {
+          filesSkipped++;
+          continue;
+        }
+      } catch {
+      }
+    }
+    try {
+      copyFileSync(srcPath, destPath);
+      bytesWritten += statSync(destPath).size;
+      filesCopied++;
+    } catch {
+    }
+  }
+  if (options?.workspace && options.workspaceSrc) {
+    mkdirSync(paths.workspace, { recursive: true });
+    const wsResult = copyWorkspaceRecursive(options.workspaceSrc, paths.workspace);
+    filesCopied += wsResult.copied;
+    filesSkipped += wsResult.skipped;
+    bytesWritten += wsResult.bytes;
+  }
+  return {
+    filesCopied,
+    filesSkipped,
+    bytesWritten,
+    durationMs: Date.now() - start
+  };
+}
+function copyWorkspaceRecursive(srcDir, destDir) {
+  let copied = 0;
+  let skipped = 0;
+  let bytes = 0;
+  try {
+    for (const entry of readdirSync(srcDir)) {
+      if (entry.startsWith(".")) continue;
+      const srcPath = join(srcDir, entry);
+      const destPath = join(destDir, entry);
+      try {
+        const stat = statSync(srcPath);
+        if (stat.isDirectory()) {
+          mkdirSync(destPath, { recursive: true });
+          const sub = copyWorkspaceRecursive(srcPath, destPath);
+          copied += sub.copied;
+          skipped += sub.skipped;
+          bytes += sub.bytes;
+        } else if (entry.endsWith(".md")) {
+          if (existsSync(destPath)) {
+            try {
+              if (stat.size === statSync(destPath).size) {
+                skipped++;
+                continue;
+              }
+            } catch {
+            }
+          }
+          copyFileSync(srcPath, destPath);
+          bytes += stat.size;
+          copied++;
+        }
+      } catch {
+        continue;
+      }
+    }
+  } catch {
+  }
+  return { copied, skipped, bytes };
+}
+export {
+  bulkCopyToLdm
+};

package/dist/cc-hook.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+declare function sendCommand(command: {
+    action: string;
+    agent_id?: string;
+    mode?: string;
+}): Promise<void>;
+
+export { sendCommand };