Installation

Installation connects Memory Crystal to your AI client and chooses where Memory Crystal data should live.

Primary installer

For Bash environments:

curl -fsSL https://memorycrystal.ai/crystal | bash

For native Windows PowerShell, use the PowerShell companion when available for your release:

iwr https://memorycrystal.ai/install.ps1 -UseBasicParsing | iex

The universal installer is the preferred path because it can detect supported clients, ask before changing each target, choose cloud or local-first backend mode, and print rollback guidance.

Agent Instructions

Copy and paste this directly into your agent, and it will know what to do:

Install Memory Crystal for this agent. Use the official installer command for this machine and client. Follow the installer prompts for authentication, backend mode, and config changes. Do not manually edit agent config files unless the installer fails and asks for a manual fallback. After installation, restart or reload the agent and verify that Memory Crystal tools are available. Refer to this page for the exact command to run for your platform and agent: https://docs.memorycrystal.ai/installation

Use the client matrix below when asking an agent to choose the exact command:

Client	Bash / macOS / Linux / WSL	Native Windows PowerShell	Verification
OpenClaw	`curl -fsSL https://memorycrystal.ai/crystal \| bash -s -- --targets openclaw`	`.\install.ps1 -Targets openclaw` writes generic MCP guidance; use Bash/WSL/Git Bash for the native plugin path	`openclaw plugins info crystal-memory`, `openclaw crystal_status`
Hermes Agent	`curl -fsSL https://memorycrystal.ai/crystal \| bash -s -- --targets hermes`	Not supported by the PowerShell installer yet	`/plugins`, `/reload-mcp`, `/crystal_status`
Claude Code	`curl -fsSL https://memorycrystal.ai/crystal \| bash -s -- --targets claude-code`	`.\install.ps1 -Targets claude-code`	Reopen Claude Code and confirm Memory Crystal MCP tools
Claude Desktop	`curl -fsSL https://memorycrystal.ai/crystal \| bash -s -- --targets claude-desktop`	`.\install.ps1 -Targets claude-desktop`	Restart Claude Desktop and confirm `memory-crystal` loads
Codex CLI	`curl -fsSL https://memorycrystal.ai/crystal \| bash -s -- --targets codex-cli`	`.\install.ps1 -Targets codex-cli`	`codex mcp list`, or restart and confirm tools
Codex Desktop	`curl -fsSL https://memorycrystal.ai/crystal \| bash -s -- --targets codex-desktop`	Generic MCP/manual config (PowerShell installer support not available yet)	Restart Codex Desktop (or Settings → MCP → Reload) and confirm Memory Crystal tools
Factory Droid	`curl -fsSL https://memorycrystal.ai/crystal \| bash -s -- --targets factory-droid`	`.\install.ps1 -Targets factory-droid`	`droid mcp list`, or reopen Factory Droid and confirm tools

Codex Desktop shares ~/.codex/config.toml with the Codex CLI, so --targets codex-desktop (or codex-cli) configures both surfaces. On native Windows PowerShell, use generic MCP/manual setup for Codex Desktop until install.ps1 gains support.

Backend choices

Backend	What it uses	Notes
Cloud	Hosted Memory Crystal backend	Recommended for most users
Local-first	Docker Convex on `127.0.0.1`	Data plane is local; hosted auth/license is still required
External self-hosted	Operator-provided Convex URL	Advanced path when supported by your release

Read Local-First Setup before choosing local mode. It documents Docker requirements, local dashboard URLs, config backups, local credential behavior, and rollback.

Supported clients

Client	Recommended path
OpenClaw	Universal installer, then accept the OpenClaw prompt
Hermes Agent	Universal installer, or Hermes Agent targeted install
Claude Code	Universal installer, or Claude Code single-client installer
Claude Desktop	Universal installer when supported, otherwise Claude Desktop manual config
Codex CLI	Universal installer, or Codex CLI single-client installer
Factory Droid	Universal installer, or Factory Droid single-client installer
Generic MCP	Universal installer generic MCP prompt, or MCP Server

Single-client installer paths

These paths remain available for compatibility and focused installs:

curl -fsSL https://memorycrystal.ai/install-claude-mcp.sh | bash
curl -fsSL https://memorycrystal.ai/install-codex-mcp.sh | bash
curl -fsSL https://memorycrystal.ai/install-droid-mcp.sh | bash

OpenClaw and Hermes Agent use the primary /crystal installer.

Safety guarantees installers should preserve

ask before configuring each detected client
create a backup before every config mutation
validate JSON/TOML where applicable before and after writes
restore the previous config when validation fails
redact API keys, bearer tokens, device codes, and local credentials from logs
avoid package-manager or service changes without a prompt

Self-hosting

For infrastructure-oriented self-hosting, see:

Docs preview

Mintlify docs for this repo live under apps/docs.

cd apps/docs
npx mint dev

Backend choices

Backend	Endpoint shape	Notes
Cloud hosted	`https://api.memorycrystal.ai/mcp`	Default and easiest setup
Local Docker Convex	`http://127.0.0.1:3211/api/mcp`	Local data plane with hosted auth/license bridge
External self-hosted	your Convex site URL	Advanced operators; verify your deployment and auth policy

run through Quickstart
verify tool access with crystal_wake, crystal_remember, and crystal_recall
keep the printed config backup path until you have verified the client works

Source of truth

apps/web/public/install.sh
apps/web/public/install.ps1
apps/web/public/install-claude-mcp.sh
apps/web/public/install-codex-mcp.sh
apps/web/public/install-droid-mcp.sh
scripts/convex-local-*.sh
scripts/convex-local-*.ts
.env.example

Get Started

Core Concepts

Integrations

Configuration

Help

Primary installer

Agent Instructions

Backend choices

Supported clients

Single-client installer paths

Safety guarantees installers should preserve

Self-hosting

Docs preview

Backend choices

Source of truth

​Primary installer

​Agent Instructions

​Backend choices

​Supported clients

​Single-client installer paths

​Safety guarantees installers should preserve

​Self-hosting

​Docs preview

​Backend choices

​Source of truth

Primary installer

Agent Instructions

Backend choices

Supported clients

Single-client installer paths

Safety guarantees installers should preserve

Self-hosting

Docs preview

Backend choices

Source of truth