Persistent Memory
for AI Agents

Set up Memory Crystal (persistent memory) on this machine, then use it in every session from now on.

STEP 1 - INSTALL
Detect this harness and pass --targets with the matching id: claude-code, claude-desktop, codex-cli, codex-desktop, cursor, opencode, factory-droid, hermes, openclaw, grok, generic-mcp.
macOS / Linux / WSL:  curl -fsSL https://memorycrystal.ai/crystal | bash -s -- --targets <id>
Windows PowerShell:   iwr https://memorycrystal.ai/install.ps1 -OutFile install.ps1; .\install.ps1 -Targets <id>
hermes is bash-only. Follow sign-in and backend prompts. Never hand-edit harness config (MCP, hooks, plugins). If the installer says to reload or restart this app, do that before verifying. Grok is Capture tier: tools and automatic capture, no automatic recall. Passive events ignore stdout, so the harness cannot inject context. Buzz is Hosted: install into the CLI Buzz is running, not into Buzz. Channel memory is not available. Docs: https://docs.memorycrystal.ai/installation

STEP 2 - VERIFY (after any required reload/restart)
Read Support Tier from the installer line "Support Tier: <id> = full|capture|tools". That is the harness tier, not billing. whoami.account.tier is billing (free/pro). whoami email or name is account identity.
Use ~/.memory-crystal/config.json (apiKey, convexUrl, agentId). Hosted default convexUrl: https://convex.memorycrystal.ai. GET {convexUrl}/api/mcp/whoami with Authorization: Bearer <apiKey>.
Assert only layers the installer claimed or wrote. If output says hooks, Managed Block, or instructions.md were skipped (tools-tier, PowerShell, or no agentsFile), skip those layers and do not fail. Capture-tier and skipped-hooks installs must not fail for missing automatic recall.
Report pass/fail per layer, including the whoami email or name:
- credentials: whoami returns email or name. Missing key or 401 = FAIL credentials (name that layer).
- tools: crystal_stats or crystal_status responds.
- hooks/plugin: only if the installer wrote hooks or a plugin. Tools-tier and PowerShell hook skips: skip; do not fail.
- discipline: only if the installer wrote a Managed Block or instructions.md. If skipped, skip; do not fail.
- identity: config.json agentId is non-empty.
- automatic recall: only if Support Tier is full AND hooks were written. Do not assert on capture-tier, tools-tier, or skipped-hooks installs.
If a claimed layer fails, re-run the installer and stop. Do not patch config by hand.

STEP 3 - USE MEMORY CRYSTAL — ASYMMETRIC CONTRACT, EVERY SESSION, NOT OPTIONAL.
- **Recall (read):** call crystal_recall (crystal_what_do_i_know for broad topics) when the task depends on past work, decisions, people, projects, or preferences. Never answer from vague recollection. Skip self-contained requests.
- Need exact past wording, quotes, commands, or code? crystal_search_messages.
- **Remember (write):** after learning any durable fact, decision, preference, lesson, or goal: save it with crystal_remember immediately, without being asked. Correct existing memories with crystal_update; replace outdated ones with crystal_supersede.
- BEFORE config changes, deletions, or external sends: crystal_preflight for the rules and lessons that apply.
- Reference material lives in knowledge bases: crystal_list_knowledge_bases to discover them, crystal_query_knowledge_base with the KB name for targeted lookups.
- Before changing something you did not build: use crystal_why_did_we to recover the recorded rationale.
- At major milestones, or when the user asks for a backup: crystal_checkpoint.
Only skip recall tools for greetings, small talk, or questions fully answered inside the current conversation.