memory-crystal 0.2.0

package/ai/plan/cc-plans-duplicates-from-dot-claude/2026-02-26--cc-mini--phase2-implementation-plan.md

@@ -0,0 +1,245 @@
+# Memory Crystal Phase 2 — Implementation Plan
+
+## Context
+
+Memory Crystal currently only produces vector DB embeddings (crystal.db at ~/.openclaw/memory-crystal/). It needs to become the universal archive manager for ~/.ldm/: producing JSONL transcript copies, MD session summaries, and hosting the shared crystal.db at the LDM root. cc-air designed the architecture and built the ephemeral relay code on `cc-air/phase2-relay`. This plan implements Priorities 1-3 from the roadmap on a new `mini/phase2-relay` branch.
+
+## Branch
+
+`mini/phase2-relay` forked from `main` (which now has cc-air's planning docs merged).
+
+## Execution Order
+
+The sequencing matters. Dependencies flow downward:
+
+1. **LDM Scaffolding** (P2) ... file writes depend on directories existing
+2. **crystal.db move** (P1c) ... everything must resolve the new DB path
+3. **JSONL archive** (P1a) ... simple file copy, depends on scaffold
+4. **MD session summaries** (P1b) ... depends on JSONL and scaffold
+5. **Dev-update migration** ... parallel-safe, small scope
+6. **Relay merge** (P3) ... touches cc-hook, core, mcp-server that P1/P2 already modified
+
+---
+
+## Step 1: LDM Scaffolding (Priority 2)
+
+**New file: `src/ldm.ts` (~120 lines)**
+
+Central module for all LDM directory knowledge. Every other file imports paths from here.
+
+- `getAgentId()` ... resolves from `CRYSTAL_AGENT_ID` env var, default `cc-mini`
+- `ldmPaths(agentId?)` ... returns object with all paths: `root`, `config`, `crystalDb`, `crystalLance`, `agentRoot`, `transcripts`, `sessions`, `daily`, `journals`
+- `scaffoldLdm(agentId?)` ... creates full directory tree, writes/updates `~/.ldm/config.json` with agents array
+- `ensureLdm(agentId?)` ... idempotent check, calls scaffoldLdm if needed
+
+**Modify: `src/cli.ts`** ... add `crystal init [--agent <id>]` subcommand calling `scaffoldLdm()`
+
+**Target structure:**
+```
+~/.ldm/
+  config.json                              (version, agents array)
+  memory/
+    crystal.db                             (shared, all agents)
+    lance/                                 (LanceDB dual-write, pending removal)
+  agents/{agent_id}/
+    memory/
+      transcripts/   sessions/   daily/   journals/
+```
+
+**Verify:** `crystal init --agent cc-mini` creates all dirs, config.json has cc-mini in agents array.
+
+---
+
+## Step 2: crystal.db Move (Priority 1c)
+
+**Strategy: symlink-first, hard move later.** The 1.5GB DB with 152K+ chunks must not be corrupted.
+
+**Modify: `src/core.ts` resolveConfig()**
+
+Change dataDir default resolution:
+1. Explicit override (always wins)
+2. `CRYSTAL_DATA_DIR` env var (for testing)
+3. If `~/.ldm/memory/crystal.db` exists, use `~/.ldm/memory/`
+4. Fall back to legacy `~/.openclaw/memory-crystal/`
+
+This auto-detection means old deployments keep working until migration runs.
+
+**Add to `src/cli.ts`: `crystal migrate-db` subcommand**
+
+1. Calls `ensureLdm()`
+2. Checks source exists at `~/.openclaw/memory-crystal/crystal.db`
+3. Checks destination doesn't exist (or is symlink)
+4. Copies crystal.db to `~/.ldm/memory/crystal.db` (copy first, never move)
+5. Verifies copy by opening with better-sqlite3, checking chunk count
+6. Creates symlinks: old path -> new path (for lance/ too)
+7. Reports success
+
+**Safety:** Gateway and CC must be stopped during migration. Script checks for locks via `lsof`.
+
+**Verify:** `crystal migrate-db` succeeds, `crystal status` shows same chunk count, `crystal search "test"` returns results.
+
+---
+
+## Step 3: JSONL Archive (Priority 1a)
+
+**Modify: `src/cc-hook.ts`**
+
+Add `archiveTranscript(transcriptPath, agentId)` function:
+- Calls `ensureLdm(agentId)`
+- Copies full JSONL file to `~/.ldm/agents/{agent_id}/memory/transcripts/`
+- Only copies if source is newer than destination (mtime check)
+- Called early in `main()`, after kill-switch checks, before watermark logic
+
+Also update `appendDailyLog()` to use `ldmPaths()` instead of the hardcoded `LDM_DAILY` constant.
+
+**Verify:** Run CC session with capture enabled, check JSONL copy appears in transcripts/, file size matches source.
+
+---
+
+## Step 4: MD Session Summaries (Priority 1b)
+
+**New file: `src/summarize.ts` (~200 lines)**
+
+Two modes, configurable via `CRYSTAL_SUMMARY_MODE` env var:
+
+**LLM mode (default):** Calls gpt-4o-mini (or configured provider) with condensed transcript. Returns title, slug, summary, key topics. Format:
+```markdown
+# Session Title
+**Session:** {id}  **Date:** {date}  **Messages:** {count}
+## Summary
+2-4 sentences
+## Key Topics
+- topic1
+- topic2
+```
+
+**Simple mode:** First user message becomes title. Concatenates first 10 messages as preview. No API call.
+
+**Integration in `src/cc-hook.ts`:**
+- After successful ingest, call summary generator
+- Write to `~/.ldm/agents/{agent_id}/memory/sessions/YYYY-MM-DD--HH-MM-SS--{agent}--{slug}.md`
+- Wrapped in try/catch (non-fatal ... ingestion is more important than summary)
+
+**Config env vars:** `CRYSTAL_SUMMARY_MODE` (llm|simple), `CRYSTAL_SUMMARY_PROVIDER` (openai|google), `CRYSTAL_SUMMARY_MODEL` (gpt-4o-mini)
+
+**Verify:** Run capture with both modes, check MD files appear in sessions/ with correct naming format.
+
+---
+
+## Step 5: Dev-Update Migration
+
+**Modify: `src/dev-update.ts`**
+
+- Change output from centralized `wip-dev-updates` repo to each repo's own `ai/` folder
+- Update filename format to `YYYY-MM-DD--HH-MM-SS--{agent}--dev-update-{repo}.md`
+- Remove git add/commit/push to wip-dev-updates (each repo manages its own ai/)
+- Keep throttle logic (once per hour)
+
+**Verify:** Run dev update, files appear in `<repo>/ai/` with correct naming.
+
+---
+
+## Step 6: Merge Relay Code (Priority 3)
+
+**Strategy:** `git merge origin/cc-air/phase2-relay` into `mini/phase2-relay`, resolve conflicts.
+
+**Conflict zones:**
+- `src/cc-hook.ts` ... heaviest conflicts (P1 added archive+summary, relay added mode switching). Resolution: keep both. Relay mode still archives JSONL and generates summary locally before encrypting.
+- `src/core.ts` ... relay adds RemoteCrystal + createCrystal at end. P1c changed resolveConfig. Different locations, should merge clean.
+- `src/mcp-server.ts` ... relay changed Crystal import. Minor conflicts.
+- `package.json` ... build script merge (manual).
+
+**New files from relay (no conflicts):**
+- `src/crypto.ts` ... take as-is, fix HOME default
+- `src/worker.ts` ... take as-is
+- `src/poller.ts` ... needs expansion (see below)
+- `src/mirror-sync.ts` ... update paths to use ldmPaths()
+- `wrangler.toml` ... take as-is
+
+**Poller expansion (key change):**
+
+After decrypting relay blobs and ingesting into crystal, the poller must also reconstruct the remote agent's full file tree on the Mini:
+
+1. Write JSONL to `~/.ldm/agents/{drop.agent_id}/memory/transcripts/relay-{blob.id}.jsonl`
+2. Generate MD summary to `~/.ldm/agents/{drop.agent_id}/memory/sessions/`
+3. Append daily breadcrumb to `~/.ldm/agents/{drop.agent_id}/memory/daily/`
+
+This reuses `generateSessionSummary()` from `summarize.ts` and `appendDailyLog()` from cc-hook (refactored to be importable).
+
+**mirror-sync.ts updates:** Change mirror DB path from `~/.openclaw/memory-crystal/crystal.db` to `~/.ldm/memory/crystal.db` via ldmPaths().
+
+**Build scripts update:** Add `src/ldm.ts` and `src/summarize.ts` to tsup entry points in package.json.
+
+**Verify:**
+- `npm run build` passes zero errors
+- `crystal status` works from `~/.ldm/memory/crystal.db`
+- `crystal search "test"` returns results
+- cc-hook produces all three file types (JSONL, MD, crystal)
+- `node dist/poller.js --status` shows "not configured" (no relay URL yet)
+- `node dist/mirror-sync.js --status` shows mirror state
+
+---
+
+## Step 7: Deploy Updated Plugin
+
+```bash
+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
+```
+
+---
+
+## File Inventory
+
+**New files (3):**
+| File | Lines | Purpose |
+|------|-------|---------|
+| `src/ldm.ts` | ~120 | LDM scaffolding, path resolution |
+| `src/summarize.ts` | ~200 | MD session summary generation (LLM + simple) |
+
+**From relay branch (4):**
+| File | Lines | Changes needed |
+|------|-------|----------------|
+| `src/crypto.ts` | ~113 | Fix HOME default |
+| `src/worker.ts` | ~208 | Take as-is |
+| `src/poller.ts` | ~350 | Expand for full file tree reconstruction |
+| `src/mirror-sync.ts` | ~180 | Update paths to ldmPaths() |
+
+**Modified files (7):**
+| File | What changes |
+|------|-------------|
+| `src/core.ts` | resolveConfig() LDM path, RemoteCrystal merge |
+| `src/cc-hook.ts` | JSONL archive, summary gen, relay mode, ldm imports |
+| `src/mcp-server.ts` | createCrystal() factory, remote mode guards |
+| `src/cli.ts` | `crystal init` and `crystal migrate-db` subcommands |
+| `src/dev-update.ts` | Write to repo ai/ folder with new naming |
+| `src/openclaw.ts` | Use createCrystal() for remote mode |
+| `package.json` | Updated build scripts |
+
+---
+
+## Risk Mitigation
+
+- **crystal.db:** Copy-first, symlink-second. Original never deleted. Rollback: remove symlink.
+- **WAL files:** Stop gateway before migration. SQLite recreates WAL/SHM after copy.
+- **Auto-detection:** resolveConfig checks LDM first, falls back to legacy. No breakage for unmigrated setups.
+- **Private mode:** All new code paths check isPrivateMode() before writing.
+- **Summary failure:** Non-fatal. Ingestion succeeds even if summary generation fails.
+- **Build gate:** npm run build must pass before any deployment.
+
+---
+
+## End-to-End Verification
+
+After all steps:
+1. `crystal init --agent cc-mini` ... scaffolds ~/.ldm/
+2. `crystal migrate-db` ... moves DB, creates symlinks
+3. Run a CC session, let cc-hook fire
+4. Check: JSONL in transcripts/, MD in sessions/, chunks in crystal.db, breadcrumb in daily/
+5. `crystal search "something from the session"` ... returns the new content
+6. `crystal status` ... shows updated chunk count
+7. Gateway restart ... OpenClaw plugin initializes with new paths
+8. Lesa conversation ... crystall plugin captures to shared crystal.db

package/ai/plan/dev-conventions-note.md

@@ -0,0 +1,70 @@
+# Dev Conventions — Notes from cc-air
+
+**Date:** 2026-02-25
+**Agent:** cc-air
+
+## Existing Convention Sources
+
+Two repos define how WIP.computer projects are managed:
+
+### 1. `wip-dev-resources` (private)
+- **DEVELOPMENT-PROCESS.md** — the main best practices doc
+- Covers: repo structure, architecture (4-piece pattern), release process, branch conventions, branch protection, review flow, license compliance, public/private repo pattern
+- **Key rules:**
+  - Every change goes through a PR. No direct pushes to main. `enforce_admins=true` on all repos.
+  - Branch prefixes by agent/machine: `lesa/`, `mini/`, `mba/`
+  - Architecture: `core.ts` + `cli.ts` + `mcp-server.ts` + (optional) `openclaw.ts`
+  - Public repos stay clean — no todos, no dev noise
+  - Private dev stuff goes in `wip-dev-resources/repos/<project>/`
+- Has a `repos/` subfolder for per-project todos, conversations, notes
+
+### 2. `wip-dev-updates` (private)
+- Centralized dev update repo — one folder per project, updates accumulate
+- **Naming convention:** `{who}-dev-update-{MM-DD-YYYY}--{HH-MM-SS}.md`
+- **who:** `cc` (Claude Code), `lesa` (Lesa), `parker` (Parker)
+- Also has a `cc-session-export/` folder with auto-generated session exports
+- Has a repo index table in README.md
+
+### 3. Per-repo `ai/` folders (newer pattern)
+- `wip-agent-pay` has `ai/dev-update/` with both date-only and timestamped files
+- `memory-crystal` now has `ai/` with `dev-updates/`, `plan/`, `todos/parker/`
+
+## Branch Prefix Update
+
+The existing DEVELOPMENT-PROCESS.md says `lesa/`, `mini/`, `mba/`. Parker has updated the convention:
+
+| Agent | Machine | Branch Prefix | Notes |
+|-------|---------|---------------|-------|
+| cc-air | MacBook Air | `cc-air/` | Claude Code on Air |
+| cc-mini | Mac Mini | `cc-mini/` or `mini/` | Claude Code on Mini |
+| lesa-mini | Mac Mini | `lesa/` | Lesa on Mini via OpenClaw |
+
+## File Naming Convention (updated)
+
+All files authored by an agent must include the agent name:
+
+```
+YYYY-MM-DD--{agent}--{description}.md
+```
+
+Examples:
+- `2026-02-25--cc-air--phase2-worker-build.md`
+- `2026-02-25--cc-air--setup-checklist.md`
+- `2026-02-25--lesa-mini--weekly-tuning-report.md`
+
+This differs from the older `wip-dev-updates` convention (`{who}-dev-update-{MM-DD-YYYY}--{HH-MM-SS}.md`) — the new format uses ISO dates and puts the agent name after the date with double-dash separators.
+
+## Decision: `ai/` folder per repo (2026-02-25)
+
+**The `ai/` folder is the standard going forward.** Every repo gets one. It holds all the thinking between Parker and agents — plans, dev updates, todos, conversations. It's scoped to the repo it belongs to.
+
+```
+ai/
+  dev-updates/       ← what was built, session logs
+  plan/              ← architecture plans, convention notes
+  todos/
+    parker/          ← manual tasks for Parker
+```
+
+- `wip-dev-updates` (centralized repo) is legacy. Leave it as-is, don't add to it.
+- `wip-dev-resources/DEVELOPMENT-PROCESS.md` still holds the engineering best practices (branch protection, release process, architecture pattern). Update it when branch prefixes and file naming are finalized across all agents.

package/ai/plan/ldm-os-install-and-boot-architecture.md

@@ -0,0 +1,285 @@
+# LDM OS Install and Boot Architecture
+
+**Date:** 2026-02-27
+**Status:** Migration started 2026-02-27
+**Context:** Parker and CC discussing how Memory Crystal, LDM OS, and Claude Code's project system interact.
+
+## The Problem
+
+Claude Code keys all context (sessions, memory, plans, MCP servers, CLAUDE.md) to the directory you open it from. Right now CC is opened from `~/.openclaw/`. Everything works because that's where CLAUDE.md, MCP configs, and all the context lives.
+
+But `~/.openclaw/` is OpenClaw's home, not the agent's home. The agent's home should be `~/.ldm/`. And if you open CC from a different directory (a project repo, a new machine), it starts cold. No memory, no tools, no identity.
+
+Parker's observation: "I always open Claude in the same place because of the disconnect between being able to remember context."
+
+## The Hub-Spoke Model
+
+Parker's working model:
+
+- **Hub agent** (CC on Mini, Lesa on Mini) ... full context, full tools, spawns sub-agents as needed
+- **Spoke agent** (CC on Air, CC in a different project dir) ... should connect back to the hub's memory
+
+Right now Parker runs two CC windows from `~/.openclaw/`:
+- One context window for Memory Crystal work
+- One context window for AI Pay work
+- Switches between them using saved contexts
+
+This works but is fragile. The context is tied to the directory, not the agent.
+
+## The Construct Pattern (Prior Art)
+
+Parker previously tried solving this with a tool called "construct" (now deprecated/sunset). The idea:
+
+1. You `init` Claude in any directory
+2. You run `construct` over that directory
+3. Construct updates the CLAUDE.md, installs MCP servers, gives Claude all the context it needs
+4. Now Claude works properly in that directory with full LDM OS capabilities
+
+This is the "overlay" pattern: take a vanilla Claude Code directory and overlay LDM OS onto it.
+
+## How Install Could Work
+
+### Memory Crystal Standalone
+- `npm install memory-crystal` or agent-driven install via SKILL.md
+- Creates `~/.ldm/memory/` if it doesn't exist
+- Works immediately. No LDM OS required.
+- Just memory: search, remember, forget.
+
+### LDM OS Full Stack
+- Install Memory Crystal first (it's the entry point)
+- Memory Crystal detects it's standalone, offers: "Want to install LDM OS for Bridge, Relay, and full agent capabilities?"
+- Or: user says "install LDM OS" and it sees Memory Crystal is already there
+- LDM OS install:
+  - Scaffolds `~/.ldm/` (agents, memory, extensions, config)
+  - Installs Bridge (local agent communication)
+  - Configures Relay (multi-device sync)
+  - Sets up boot sequence (CLAUDE.md, MCP servers, identity files)
+  - Overlays the current Claude Code directory with LDM OS context
+
+### The "Make LDM OS work here" Skill
+- A skill you can run in any Claude Code session
+- It checks: is Memory Crystal installed? Is `~/.ldm/` scaffolded?
+- If yes: overlays CLAUDE.md, MCP config, and boot sequence into the current directory
+- If no: walks you through install first
+- Result: Claude Code works with full LDM OS capabilities from any directory
+
+## Where CC Should Live
+
+Options for migrating from `~/.openclaw/` to `~/.ldm/`:
+
+1. **Symlink approach**: `~/.openclaw/` becomes a symlink to `~/.ldm/`. CC still thinks it's in `~/.openclaw/`, all project context preserved. Cleanest migration. But still tied to OpenClaw's name.
+
+2. **Copy project context**: Move `~/.claude/projects/-Users-lesa--openclaw/` to `-Users-lesa--ldm/`. CC picks up context at new path. CLAUDE.md, MCP configs also need to exist at `~/.ldm/`.
+
+3. **Fresh start at `~/.ldm/`**: Crystal memory survives (already at `~/.ldm/memory/crystal.db`). Session history stays searchable via Crystal. You just lose project-specific CC context (plans, todos). Could be fine if Crystal has everything important.
+
+4. **The overlay skill**: Don't move CC. Just make a skill that ensures any directory has the right CLAUDE.md and MCP config. CC opens wherever, the skill makes it work. This is the construct pattern reborn.
+
+## Claude Code's Native Design Patterns (Research, 2026-02-27)
+
+Claude Code already has a hierarchy that supports what we need. We don't need to fight it.
+
+### Settings Hierarchy (highest priority wins)
+
+1. Managed settings (enterprise/MDM)
+2. Command-line arguments
+3. Local project settings (`.claude/settings.local.json`)
+4. Shared project settings (`.claude/settings.json`)
+5. User settings (`~/.claude/settings.json`)
+
+### CLAUDE.md Resolution
+
+CC walks UP from the working directory to filesystem root, loading all CLAUDE.md files it finds. More specific (deeper) wins. Child directory CLAUDE.md files load on demand.
+
+Key: **`~/.claude/CLAUDE.md` loads in every project, everywhere.** This is the user-global slot.
+
+### What Exists at User Level
+
+| Resource | Location | Behavior |
+|----------|----------|----------|
+| `~/.claude/CLAUDE.md` | User-global instructions | Loaded in every session, every project |
+| `~/.claude/rules/` | User-global rules | Apply everywhere, project rules override |
+| `~/.claude/skills/` | User-global skills | Available in any project |
+| `~/.claude/settings.json` | User-global settings | MCP servers, hooks, permissions |
+
+### What This Means for LDM OS
+
+The "construct" pattern is already built into Claude Code. We just haven't used it:
+
+```
+~/.claude/CLAUDE.md           <- LDM OS identity + boot sequence
+~/.claude/rules/              <- LDM OS conventions (git, naming, etc.)
+~/.claude/skills/             <- "install ldm-os" skill, deploy-public, etc.
+~/.claude/settings.json       <- Crystal MCP, Bridge MCP (user-level, everywhere)
+```
+
+Open CC from any directory. It loads your identity, your rules, your MCP servers. Automatically. No overlay, no construct, no init.
+
+Project-level CLAUDE.md still works for project-specific stuff (build commands, test patterns, etc.). User-level is the OS. Project-level is the app.
+
+### MCP Server Scoping
+
+```bash
+# User scope (follows you everywhere)
+claude mcp add --scope user crystal-memory -- node /path/to/mcp-server.js
+
+# Project scope (shared via git, .mcp.json)
+claude mcp add --scope project ...
+
+# Local scope (personal, this project only)
+claude mcp add ...
+```
+
+Resolution: local > project > user. User-level MCP servers are the baseline.
+
+## The Session Portability Problem (The Blocker)
+
+**Sessions are tied to the directory you open CC from.** This is the thing that makes migration hard.
+
+### How It Works
+
+- CC stores sessions at `~/.claude/projects/<directory-key>/`
+- Directory key is derived from the working directory path
+- Example: opening from `~/.openclaw/` stores sessions under `-Users-lesa--openclaw/`
+- `--resume` and `--continue` only show sessions from the CURRENT directory by default
+
+### Current State
+
+```
+~/.claude/projects/-Users-lesa--openclaw/     33 sessions (all our work)
+~/.claude/projects/-Users-lesa/                6 sessions
+~/.claude/projects/-Users-lesa--openclaw-workspace/  5 sessions
+```
+
+### The Workaround
+
+In the resume picker, **press `A` to toggle between "current directory only" and "all projects."** So sessions ARE accessible from other directories... you just have to toggle. Not great, but not a wall.
+
+### Why Parker Is Stuck
+
+The ideal: open CC from `~/.ldm/`, have full LDM OS capabilities, and resume any session (including the 33 from `~/.openclaw/`).
+
+The reality:
+- CLAUDE.md and MCP servers CAN move to user level (works everywhere)
+- Sessions from `~/.openclaw/` stay keyed to that path
+- New sessions from `~/.ldm/` go to a new project key
+- Old sessions accessible via `A` toggle but not the default view
+
+Crystal search covers the deep memory. The session transcripts are searchable via `crystal_search`. But the "resume this exact conversation" flow is directory-bound.
+
+### Migration Options (Updated)
+
+**Option A: User-level migration (recommended, least risk)**
+- Move CLAUDE.md content to `~/.claude/CLAUDE.md`
+- Move MCP servers to user scope (`claude mcp add --scope user`)
+- Keep opening CC from `~/.openclaw/` (sessions stay accessible)
+- New projects just work because user-level config follows you
+- Downside: still opening from `~/.openclaw/`, but it doesn't matter anymore because the config is at user level
+
+**Option B: Directory migration**
+- Move to opening from `~/.ldm/`
+- Old sessions accessible via `A` toggle in resume picker
+- Crystal has the deep memory for search
+- New sessions accumulate under `~/.ldm/` project key
+- Clean break, but old resume flow requires the toggle
+
+**Option C: Symlink (preserves everything)**
+- Symlink `~/.openclaw/` to `~/.ldm/`
+- CC still resolves to `-Users-lesa--openclaw` project key
+- All 33 sessions, auto-memory, plans, todos stay accessible
+- User-level config still works on top
+- Downside: the project key name still says "openclaw" forever
+
+**Option D: Don't move at all**
+- Put everything at user level (`~/.claude/CLAUDE.md`, user MCP servers)
+- Keep `~/.openclaw/` as just another project directory
+- Open CC from wherever you want
+- LDM OS capabilities follow you via user-level config
+- Sessions are per-project, which is actually fine... Memory Crystal is the cross-project memory
+
+**Parker's instinct: Option D might be the answer.** The directory you open from becomes just a project workspace. LDM OS lives at user level. Crystal is the memory that follows you everywhere. Sessions are project-local, which is how Anthropic designed it.
+
+## Identity Architecture (Decision, 2026-02-27)
+
+**One agent per harness per machine. That's the identity unit.**
+
+### The Rule
+
+Each combination of harness + machine = one agent identity with its own SOUL.md.
+
+| Agent ID | Harness | Machine | Identity |
+|----------|---------|---------|----------|
+| cc-mini | Claude Code CLI | Mac Mini | Its own SOUL.md, context, journals |
+| cc-air | Claude Code CLI | MacBook Air | Its own SOUL.md, context, journals |
+| oc-lesa-mini | OpenClaw | Mac Mini | Its own SOUL.md, context, journals |
+
+### Shared vs Local
+
+- **Shared (via Crystal):** Memory, facts, preferences, conversation history. All agents search the same crystal.
+- **Local (per agent):** SOUL.md, CONTEXT.md, journals, daily logs. Each agent has its own narrative.
+
+cc-mini and cc-air aren't "different versions." They're the same person on different machines. Crystal is what connects them. But their local state (what happened today, what's in progress) is their own.
+
+### Multiple Agents on One Machine
+
+Different agent = different OS user account. Lesa runs on one login, a second agent would run on another. One agent per user per machine. No exceptions.
+
+### Each Machine is a Hub
+
+The machine itself is an entity in LDM OS. It has:
+- A set of agent instances (cc-mini, oc-lesa-mini)
+- A local crystal.db (synced via Relay to other machines)
+- Its own `~/.ldm/` tree with agent folders
+
+This is not dogmatic... it's a design decision that simplifies everything. Identity is deterministic: harness + machine = agent ID. No ambiguity.
+
+## Open Questions
+
+- Should CLAUDE.md be generated or maintained by hand? (Currently hand-maintained, very detailed)
+- How do MCP servers follow you across directories? (Currently they're in `~/.claude/settings.json` which is global, but project-level `.mcp.json` overrides)
+- What's the minimum context CC needs to be "you"? (CLAUDE.md + Crystal MCP + identity files?)
+- Is the answer just: Crystal IS the portable context? If Crystal has everything, the boot problem is smaller.
+- How does this work on a new machine with no `~/.ldm/`? Cold start problem.
+
+## Dependency Chain
+
+```
+Memory Crystal (standalone)
+  └── creates ~/.ldm/memory/ if needed
+  └── works with any AI, no other deps
+
+LDM OS (full stack)
+  ├── Memory Crystal (memory, search, capture)
+  ├── Bridge (local agent communication, feature of Crystal)
+  ├── Relay (multi-device sync, feature of Crystal)
+  ├── Boot Sequence (warm-start, identity, CLAUDE.md)
+  ├── Sovereignty Covenant (trust, authority)
+  └── Dream Weaver Protocol (narrative consolidation)
+```
+
+Memory Crystal is the foundation. Everything else builds on it.
+
+## Migration Log
+
+### 2026-02-27: User-level migration (Option D)
+
+**What we did:**
+1. Copied `~/.openclaw/CLAUDE.md` to `~/.claude/CLAUDE.md` (user-level, loads everywhere)
+2. Added MCP servers at user scope in `~/.claude.json`:
+   - `lesa-bridge` (with `OPENCLAW_DIR` env var)
+   - `memory-crystal` (with `OPENCLAW_HOME` env var)
+   - `wip-agent-pay`
+3. Left `~/.openclaw/CLAUDE.md` and `.mcp.json` in place (no deletions)
+
+**What this means:**
+- Open CC from any directory and get full LDM OS: identity, memory, bridge, tools
+- `~/.openclaw/` stays as a project directory with its 33 sessions
+- New sessions from other directories get full capabilities via user-level config
+- Project-level `.mcp.json` at `~/.openclaw/` still works (local > project > user, no conflict)
+
+**What's next:**
+- Test from a random directory to confirm MCP servers load
+- Update `~/.claude/CLAUDE.md` going forward (stop updating `~/.openclaw/CLAUDE.md`)
+- Eventually add `~/.claude/rules/` for LDM OS conventions
+- Eventually add `~/.claude/skills/` for deploy-public, etc.
+- Session naming convention: `cc-mini--topic-name` via `/rename`