Skip to main content
Self-hosting Memory Crystal means your memories are stored in your own Convex deployment — not on memorycrystal.ai infrastructure. You get full data sovereignty and complete control over your data.

​
When to self-host

Self-hosting is the right choice when:
  • You need your data to stay on your own infrastructure
  • You have compliance or privacy requirements that require data residency control
The free tier at memorycrystal.ai is a good starting point if data sovereignty isn’t a requirement.

​
Prerequisites

Before you start, make sure you have:
  • A Convex account (free tier works)
  • OpenClaw installed
  • Node.js 18 or higher

​
Setup

1

Create a Convex project

Go to dashboard.convex.dev and create a new project. Note your deployment name — it looks like your-project-123.
2

Clone the repo and install dependencies

git clone https://github.com/memorycrystal/memorycrystal.git
cd memorycrystal
npm install
3

Deploy the schema and functions

Run convex deploy with your deployment name. This pushes the Memory Crystal schema and backend functions to your Convex project.
CONVEX_DEPLOYMENT=prod:your-project-123 npx convex deploy
Replace your-project-123 with your actual Convex deployment name.
4

Set environment variables

Add your deployment URL and key to mcp-server/.env and your shell environment:
CONVEX_URL=https://your-project-123.convex.cloud
CONVEX_DEPLOYMENT=prod:your-project-123
MEMORY_CRYSTAL_API_KEY=your-api-key-here
Your Convex URL follows the pattern https://<deployment-name>.convex.cloud.
5

Enable the plugin

Wire the plugin into your OpenClaw installation:
npm run crystal:enable
6

Verify the setup

Run the doctor command to confirm everything is connected correctly:
npm run crystal:doctor
If anything is misconfigured, the doctor output will tell you what to fix.

​
Verifying the connection

After setup, run a smoke test to confirm the plugin can reach your backend: 
npm run test:smoke
A successful result means your self-hosted backend is receiving and storing memories.

​
Important: fallback behavior

If you don’t set CONVEX_DEPLOYMENT and CONVEX_URL, Memory Crystal falls back to the hosted cloud backend. Your data will not stay on your own infrastructure. Always verify your env vars are set before using the plugin.

​
Troubleshooting

If crystal:doctor reports issues:
  • Confirm CONVEX_URL and CONVEX_DEPLOYMENT are set in your shell and in mcp-server/.env
  • Re-run bootstrap to repair any missing wiring: npm run crystal:bootstrap
  • Check that the Convex deploy succeeded without errors in the previous step
For more help, see the Troubleshooting page.