Documentation
MemoryClaw is zero-knowledge encrypted neural memory for any AI agent — Claude Code, Cursor, Aider, Codex CLI, Gemini CLI, Goose, OpenClaw, and more. The memoryclaw CLI installs in one command on macOS, Linux, and Windows (WSL). Run memoryclaw setup to wire it into every detected agent automatically. Encrypted cloud backup is available for any agent — pick which ones to back up at install or via memoryclaw mode --set full.
New here? Jump to Integrations, the Install guide, or per-agent walkthroughs at memoryclaw.ai/setup. Free tier — plans starting at $9/mo for production agent loops.
Integrations
MemoryClaw's Neural Memory layer works with every major AI-agent ecosystem. The memoryclaw setup command auto-detects and wires each one. For per-agent walkthroughs and copy-paste commands, see memoryclaw.ai/setup.
| Agent | Wired into | Setup |
|---|---|---|
| Claude Code | ~/.claude/CLAUDE.md | memoryclaw setup --for claude-code |
| Cursor | AGENTS.md / .cursor/rules/ | memoryclaw setup --for agents-md |
| Aider | AGENTS.md / CONVENTIONS.md | memoryclaw setup --for agents-md |
| OpenAI Codex CLI | AGENTS.md | memoryclaw setup --for agents-md |
| Gemini CLI | ~/.gemini/GEMINI.md | memoryclaw setup --for gemini |
| Goose | AGENTS.md / .goosehints | memoryclaw setup --for agents-md |
| OpenClaw | Plugin loader (+ backup) | openclaw plugins install clawhub:memoryclaw |
| Cline / Continue | Project-level rules | memoryclaw setup --print |
| Claude Desktop | MCP config (Phase 2) | memoryclaw mcp serve |
| Custom / REST | Direct CLI calls | memoryclaw memory engram --auto … |
Backup features (push/pull/claws/history) work with any agent — pick which to back up at install or via memoryclaw mode --set full. Memory-only users (no backup) install with MEMORYCLAW_MODE=memory. See the Install section below for mode details.
Installation
Install the memoryclaw CLI with a single command. The same command works for openclaw on macOS, openclaw on Linux, and openclaw on Windows (WSL):
curl -fsSL /install.sh | bashThis installs the MemoryClaw plugin, signs you in, and runs your first backup. The installer launches automatically after setup — no extra steps. Works on macOS, Linux, and Windows (WSL).
Install from ClawHub
MemoryClaw is also available on ClawHub. Install the plugin directly from inside OpenClaw:
openclaw plugins install clawhub:memoryclawView on ClawHub: clawhub.ai/iarayan/memoryclaw-backup
Reinstalling / Reconnecting
If you're reinstalling MemoryClaw on the same or a different machine, run the same install command above. The installer detects your existing account and reconnects automatically — your claw history and backup data are preserved on the server. Just log in and you're back.
Uninstalling
To completely remove MemoryClaw from your machine:
curl -fsSL /install.sh | bash -s -- --uninstallOr run memoryclaw uninstall from the CLI. This removes the binary, config files, and cron job. Your cloud backups and account remain intact.
Getting Started
Run the install command. The memoryclaw CLI is installed system-wide and auto-launches after setup.
Your browser opens automatically — sign up or log in, then approve the claw. The CLI picks it up instantly.
Run your first backup when prompted. Your passphrase is saved locally (encrypted) so future backups can run unattended.
The installer sets up an OpenClaw cron job for automatic backups — your setup stays protected hands-free.
Commands
| Command | Description |
|---|---|
| memoryclaw | Interactive menu (zero friction) — works from anywhere |
| memoryclaw push | Back up active agent (zip + encrypt + upload) |
| memoryclaw push --auto | Unattended backup using saved passphrase (for cron). With MEMORYCLAW_MULTI_AGENT_BACKUP=1, iterates every registered agent. |
| memoryclaw pull | Restore from backup history with version picker |
| memoryclaw pull --agent <id> | Restore one agent's backup (claude-code, cursor, codex-cli, openclaw, …) |
| memoryclaw pull --file <path> | Restore from a downloaded backup file |
| memoryclaw pull --claw_id <name> | Restore from a specific claw's backup |
| memoryclaw backup list | Show every registered claw + its agent + target dir |
| memoryclaw backup add | Register a new (machine, agent) claw. Detects installed agents and prompts for the target dir. Use --agent <id> to skip the picker. |
| memoryclaw backup remove | Unregister a claw locally (server-side backups stay safe) |
| memoryclaw pull --path <dir> | Restore to a custom directory instead of default |
| memoryclaw pull --auto | Non-interactive restore (uses saved passphrase) |
| memoryclaw status | Show backup status, plan, storage, and subscription info |
| memoryclaw history | Show past backup timestamps and sizes |
| memoryclaw login | Authenticate via browser |
| memoryclaw logout | Clear stored credentials, passphrase, and claw config |
| memoryclaw whoami | Show logged-in user email and plan |
| memoryclaw config | Show local configuration (excludes, directory, passphrase) |
| memoryclaw claws | List all registered claws |
| memoryclaw claws add | Register a new claw |
| memoryclaw claws switch | Switch active claw |
| memoryclaw claws rename <name> | Rename the current claw |
| memoryclaw claws primary | Set current claw as primary |
| memoryclaw update | Check for and install updates |
| memoryclaw update --check | Check for updates without installing |
| memoryclaw doctor | Run health checks and diagnostics |
| memoryclaw version | Show plugin version |
| memoryclaw completions bash | Output bash shell completion script |
| memoryclaw completions zsh | Output zsh shell completion script |
| memoryclaw uninstall | Uninstall MemoryClaw completely |
| memoryclaw help | Show all available commands |
| memoryclaw help <command> | Show detailed help for a specific command |
| memoryclaw <cmd> --quiet | Suppress non-error output (ideal for cron) |
| memoryclaw <cmd> --json | Output machine-readable JSON (status, history, whoami, version) |
| memoryclaw <cmd> --verbose | Show debug info: API calls, timing, file details |
| memoryclaw <cmd> --debug | Alias for --verbose |
| memoryclaw <cmd> --api-url <url> | Override the API base URL |
| memoryclaw --version | Show plugin version (short flag) |
System-wide CLI
MemoryClaw installs as a system-wide command — run memoryclaw from any directory, in any terminal. No need to navigate to a specific folder or use full paths.
It is also available as an OpenClaw skill. Type /memoryclaw inside OpenClaw to access it inline. The skill is published on ClawHub and is also bundled with the plugin — agents can discover it through ClawHub skill search or use it directly after installing the plugin.
Shell completions are available for bash and zsh. Run source <(memoryclaw completions bash) or source <(memoryclaw completions zsh) to enable tab completion. Add the command to your shell profile to persist it.
Passphrase & Encryption
Your encryption passphrase is a separate key from your account password. It encrypts your backups with AES-256-GCM before they leave your machine. MemoryClaw operates on a zero-knowledge model — we never see, store, or transmit your passphrase. Only encrypted data reaches our servers.
On first backup, you choose a passphrase (minimum 8 characters) and confirm it. You are then offered to save it locally, encrypted with a machine-specific key. Once saved, auto-backups and the --auto flag work without prompting.
If you lose your passphrase, your encrypted memories AND backups cannot be recovered. Zero-knowledge means zero recovery — we have no way to decrypt your data. Write it down somewhere safe (or run memoryclaw memory export-salt for an offline rescue copy of your encryption salt).
You can change your passphrase at any time via memoryclaw → Settings → Change encryption passphrase, or from the interactive settings menu. Note that changing your passphrase only affects future backups — existing backups remain encrypted with their original passphrase.
Backup Versioning
Every backup creates a new, independently stored version. Previous versions are not overwritten — they remain in your backup history until your storage quota is reached, at which point the oldest versions are automatically removed to make room.
You can browse your full version history from the dashboard, where each entry shows the timestamp, file size, and a per-entry download button. From the CLI, memoryclaw history lists all available versions, and the memoryclaw pull command includes a version picker so you can restore any specific backup — not just the latest.
Automatic Backups
During your first backup, your passphrase is saved locally (encrypted). This enables the memoryclaw push --auto flag, which runs without any prompts.
The installer configures an OpenClaw cron job that calls memoryclaw push --auto on a schedule so your memory stays backed up hands-free. On macOS the schedule runs through OpenClaw's cron (launchd-equivalent), on Linux through cron, and on Windows (WSL) through the WSL cron daemon. If you prefer to run backups under systemd or launchd directly, just call memoryclaw push --auto from your unit / plist on the schedule you want.
Changing backup frequency:
Open the interactive menu (memoryclaw) → Settings → Change backup frequency. Free plans can schedule hourly or less frequent backups. Paid plans unlock frequencies down to every 5 minutes.
Removing auto-backup:
Open the interactive menu → Settings → Remove auto-backup. This deletes the cron job. You can re-enable it anytime from the same menu.
Auto backup runs via OpenClaw's cron system. If OpenClaw is not running or its cron is disabled, automatic backups will not execute until OpenClaw is operational again.
When auto-backup fails:
If an auto-backup fails (e.g., expired session, storage full, deleted claw), the error is written to ~/.config/memoryclaw/last-error.log. Check this file to diagnose issues. For session expiry, run memoryclaw login to re-authenticate.
Restore
Cloud restore with version picker:
Run memoryclaw pull to restore from the cloud. If you have multiple backup versions, a version picker lets you choose which one to restore. The latest version is always recommended, but you can go back to any previous snapshot.
memoryclaw pullRestore to a custom directory:
Use --path to restore to a directory other than the default ~/.openclaw/. The interactive pull also offers a “Custom path” option.
memoryclaw pull --path ~/restore-hereRestore from a specific claw:
If you have multiple claws (e.g., work and personal machines), specify which one to restore from:
memoryclaw pull --claw_id work-macbookRestore from a local file:
If you downloaded a backup from the dashboard, restore directly from the file without contacting the cloud:
memoryclaw pull --file /path/to/backup.encCross-machine restore:
To restore on a new machine, install MemoryClaw, log in with your account, then run memoryclaw pull --claw_id <claw-name>. The restore automatically updates your local claw config to match the restored claw identity, so future backups go to the right place.
Restoring overwrites your current ~/.openclaw/ contents. The CLI warns and asks for confirmation before proceeding if the target directory has existing files.
Multi-Claw
A claw is an OpenClaw instance backed up by MemoryClaw. Each claw has its own backup history, storage usage, and backup schedule. You can have multiple claws on the same machine — each pointing to a different OpenClaw directory — or spread them across different machines. Name them anything you like (e.g. work-claw, personal-claw).
Every plan ships with unlimited claws — install on as many machines as you like; the engram pool is per-account. See pricing for storage and quota details.
CLI commands:
memoryclaw clawsLists all your registered claws with their backup status, OS, hostname, and storage.
memoryclaw claws addRegister a new claw — choose a name and OpenClaw directory. Optionally back it up immediately.
memoryclaw claws switchSwitch which claw is active for backup and restore.
memoryclaw claws rename MacBookRename the current claw.
memoryclaw claws primarySet the current claw as your primary claw.
When you first run MemoryClaw, it registers your default OpenClaw directory as a claw. To add more claws (e.g. for different projects or directories on the same machine), use memoryclaw claws add. You can rename or set a primary claw from the CLI. Deleting claws is only available from the dashboard for safety.
Neural Memory
Neural Memory gives your AI agent persistent, encrypted, searchable memory across sessions and machines. Everything is encrypted client-side with AES-256-GCM before it leaves your machine — the server never sees plaintext, not even your search queries. Quotas scale per tier; see the pricing page for the current memory + lookup allowances on each plan.
Core Concepts
| Term | What it is |
|---|---|
| Engram | An encrypted memory node — one observation, reasoning step, or action. |
| Thread | A cognitive thread, like a Git branch. Each agent can have multiple threads for different tasks or contexts. |
| Cortex | Your agent's complete memory graph — all engrams, threads, and edges. |
| Recall | Searching memory by HMAC-encrypted tags. The server matches without decrypting. |
| Resolve | Conflict detection between threads. The server scores conflicts via weighted consensus; your client LLM resolves the rest. |
| Consolidate | Summarize old engrams into a compact "semantic" memory. Keeps history without unbounded growth. |
Memory Commands
| Command | Description |
|---|---|
| memoryclaw memory engram --auto --message "…" | Save a new memory non-interactively (auto-inits on first call) |
| memoryclaw memory recall "query" | Search your memories by concept (defaults to active thread) |
| memoryclaw memory threads | List, create, or switch threads |
| memoryclaw memory history | Show engrams in the active (or specified) thread |
| memoryclaw memory stats | Check usage (engrams, recalls, resolves this month) |
| memoryclaw memory consolidate --hashes a,b,c --summary "…" | Replace 2+ engrams with one summary engram |
| memoryclaw memory import --path ./notes/ | Bulk-import .md files as engrams |
| memoryclaw memory export-salt --out salt.txt | Save your encryption salt to a file (back this up offline) |
| memoryclaw memory import-salt --in salt.txt | Restore your salt after losing memory.json — recovers access to your engrams |
| memoryclaw memory doctor | Run health checks on the memory system |
Salt Rescue — If You Lose memory.json
Your encryption salt lives in ~/.config/memoryclaw/memory.json. Combined with your passphrase, it derives the key that decrypts your engrams. If memory.json gets deleted (machine wipe, accidental rm, disk failure) and you have no other device that's synced via cortex-config, your engrams become permanently undecryptable — even though the encrypted ciphertext is still safe on the server.
The rescue path: run memoryclaw memory export-salt --out salt.txt NOW (while you still have access), keep the file somewhere safe (password manager, encrypted USB), and on a fresh machine run memoryclaw memory import-salt --in salt.txt after login but before any new engram is saved. The salt file is small and base64-only — safe to store anywhere your passphrase isn't.
Zero-Knowledge Architecture
Your memories are encrypted with AES-256-GCM on your machine before upload. The server stores only encrypted blobs and HMAC blind-index tags — it cannot read your data, your queries, or your search results. Even during conflict resolution, the server only scores metadata (timestamps, confidence, graph structure). Your client LLM handles the actual resolution.
Interactive Menu
Run memoryclaw with no arguments to open the interactive menu. From here you can access all features without memorizing commands. The menu loops back after every action — no need to re-launch.
Main menu:
1. Back up now
2. Restore from backup
3. Status & details
4. Claws
5. Settings
6. Help
7. Log out
8. Exit
Claws menu (memoryclaw claws):
1. Add new claw
2. Switch active claw
3. Rename this claw
4. Set this claw as primary
---
5. Back
Settings menu:
1. Rename this claw
2. Change encryption passphrase
3. Exclude files/folders
4. View account on website
5. Logout
6. Change backup frequency
7. Remove auto-backup
---
8. Back
The Change backup frequency option lets you adjust how often auto-backups run. Free plans can schedule hourly or less frequent backups. Paid plans unlock frequencies down to every 5 minutes.
The Exclude files/folders option lets you add or remove glob patterns to skip certain files from your backup (e.g. *.log, node_modules/, .env).
Account Management
All account management is available from the dashboard:
- Change password — Security section with current password verification.
- Change email — Verified flow: enter your current password and the new email address, then check the new inbox for a confirmation link. A notification is also sent to your old email for security.
- Manage subscription — View billing interval, switch between monthly/annual, cancel or reactivate. Cancellation keeps access until the end of the billing period.
- Delete account — Permanently removes your account, all backups, and cancels any active subscription.
Doctor & Diagnostics
Run memoryclaw doctor to perform a full health check of your setup. It verifies:
- Config directory exists and is writable
- Device config (device.json) is valid
- Authentication status and token validity
- API connectivity and latency
- Cron job (auto-backup) is installed
- OpenClaw directory exists
- Passphrase is saved locally
Each check shows a pass/fail indicator with a description of what to fix if something is wrong. This is the first command to run when troubleshooting.
FAQ
memoryclaw claws add to register additional claws.memoryclaw claws add to register each OpenClaw directory as a separate claw. Each claw has its own name, backup history, and schedule. Switch between them with memoryclaw claws switch. Every plan supports unlimited claws — install MemoryClaw on as many machines as you like.memoryclaw pull --claw_id <claw-name>. Your passphrase will be required to decrypt. The restore automatically configures the local claw identity so future backups continue seamlessly.~/.openclaw/ folder — including memory, context, settings, and configuration — is zipped and encrypted, excluding the MemoryClaw plugin itself and any patterns you've added to the exclude list.memoryclaw claws to list, memoryclaw claws add to register new ones, and memoryclaw claws switch to change the active claw. You can also rename or set a primary claw from the CLI. Deleting claws is only available from the dashboard for safety.OPENCLAW_DIR environment variable to your custom path before running MemoryClaw. It will use that directory instead of the default ~/.openclaw/. You can also specify custom directories when adding claws via memoryclaw claws add.memoryclaw pull --file /path/to/backup.enc and enter your passphrase. This restores directly from a local file without contacting the cloud. Note: this will overwrite your current OpenClaw folder.MemoryClaw enforces per-IP rate limits on API endpoints to ensure fair usage:
| Endpoint | Limit |
|---|---|
| Upload (backup push) | 100 requests / hour |
| Download (restore pull) | 50 requests / hour |
| Claw auth | 10 requests / hour |
| Claw token polling | 60 requests / 10 min |
| Status / history | 120 requests / min |
Registration and login are protected by human verification (Cloudflare Turnstile) instead of rate limits. Exceeding API rate limits returns HTTP 429 Too Many Requests.
curl -fsSL /install.sh | bash -s -- --uninstall or memoryclaw uninstall. This removes the binary, config files, and cron job. Your cloud backups and account remain intact — you can reinstall and reconnect anytime.Troubleshooting
Start by running memoryclaw doctor — it checks your config, auth, API connectivity, cron job, and passphrase in one go. Most issues are identified here with instructions on how to fix them.
If you entered the wrong OpenClaw directory during setup, delete the claw config and re-run:
rm ~/.config/memoryclaw/device.json
memoryclaw
This triggers the setup flow again so you can enter the correct directory.
The CLI automatically detects 401 errors and prompts you to log in again in interactive mode. In auto mode (--auto), it exits with a message. Run memoryclaw login to re-authenticate. Sessions expire after 365 days (long-lived to keep cron-driven auto-backups reliable; password change or logout invalidates immediately).
Auto-backups (push --auto) require a saved passphrase. Run memoryclaw push interactively once to set and save your passphrase.
If a claw was deleted from the dashboard but the CLI still tries to use it, you'll see a “claw not found” error. In interactive mode, the CLI offers to set up a new claw. In auto mode, the error is logged to ~/.config/memoryclaw/last-error.log.
To fix manually:
rm ~/.config/memoryclaw/device.json
memoryclaw push
Free plan: 500 MB. Dev plan: 5 GB.
When your storage is full, MemoryClaw automatically removes the oldest backup(s) to make room for your new backup. You always keep your most recent backups. The CLI will display a note when old backups have been removed.
If the backup itself exceeds your remaining quota, the CLI warns you before uploading. In auto mode, the backup is aborted. You can manually delete old backups from the dashboard or upgrade to Dev for 5 GB.
Check your internet connection. Run memoryclaw doctor to test API connectivity and latency. If the issue persists, verify the API is reachable:
curl -s https://memoryclaw.ai/api/version
This should return a JSON response. If it doesn't, check your network or firewall settings.
Auto-backup errors are appended to:
~/.config/memoryclaw/last-error.log
For interactive debugging, use the --verbose flag with any command to see API calls, timing, and file details.
Need Help?
If you have questions, run into issues, or want to request a feature, use our contact form or email us at info@memoryclaw.ai. You can also report bugs, suggest features, or ask questions through the contact page. We typically respond within a few business days.
Want to read more? Check out the MemoryClaw blog for posts on how MemoryClaw encrypts your data, MemoryClaw vs MyClaw, and more. Need higher limits? Plans starting at $9/mo — unlimited backups, up to 5 GB, unlimited claws.