The crystal-memory plugin integrates directly into OpenClaw’s conversation lifecycle. Once installed, every session is automatically captured, and relevant memories are injected before each AI response. No manual recall needed.
Install
One-line install
Manual install
Run the installer script:curl -fsSL https://memorycrystal.ai/crystal | bash
Copy the plugin files into your OpenClaw extensions directory:mkdir -p ~/.openclaw/extensions/crystal-memory
rsync -a \
--exclude node_modules \
--exclude '*.test.js' \
plugin/ ~/.openclaw/extensions/crystal-memory/
cd ~/.openclaw/extensions/crystal-memory && npm install
~/.openclaw/openclaw.json under plugins.slots.memory.Never edit ~/.openclaw/openclaw.json while OpenClaw is running. Apply config changes outside the runtime, validate with jq empty ~/.openclaw/openclaw.json, then restart the gateway.
Enable and disable
# Wire the plugin into your OpenClaw config
npm run crystal:enable
# Remove the plugin wiring
npm run crystal:disable
npm run crystal:disable -- --purge
Verify
Run the doctor command to check that the plugin is wired correctly and can reach the memory backend:
Lifecycle hooks
The plugin registers hooks for these OpenClaw lifecycle events:
| Hook | What it does |
|---|
before_agent_start | Injects wake context and relevant recall at session start |
before_tool_call | Surfaces warnings before risky tool calls |
before_dispatch | Rate limiting, proactive recall, and reinforcement injection |
message_received | Captures incoming user messages |
llm_output | Captures assistant responses and extracts durable memories |
session_end | Clears per-session state |
before_compaction and after_compaction to preserve context across OpenClaw’s context compaction boundaries.
The plugin registers these tools, available in your AI session:
Memory tools
crystal_recall — semantic search across long-term memorycrystal_remember — store a durable memory manuallycrystal_recent — fetch recent memory-backed messagescrystal_search_messages — search conversation historycrystal_what_do_i_know — topic knowledge snapshotcrystal_why_did_we — decision archaeologycrystal_checkpoint — milestone memory snapshotcrystal_preflight — pre-flight check before risky actionscrystal_forget — archive or delete a memorycrystal_trace — trace a memory to its source conversationcrystal_wake — session startup briefingcrystal_stats — memory and usage statisticscrystal_set_scope — override channel scope for the sessioncrystal_who_owns — find ownership context for files or modulescrystal_explain_connection — explain relationships between conceptscrystal_dependency_chain — trace dependency chains
Local tools (when local store is available)
crystal_grep — search in-session local history and summariescrystal_describe — inspect a local summary nodecrystal_expand — expand a local summary into underlying context
memory_search — returns crystal/<id>.md pathsmemory_get — reads a memory by ID or path
Configuration
Set these options in your OpenClaw plugin config under plugins.entries.crystal-memory.config:
| Option | Type | Default | Description |
|---|
apiKey | string | — | Your Memory Crystal API key |
convexUrl | string | https://your-deployment.convex.site | Memory Crystal backend URL. Override for self-hosted deployments. |
defaultRecallMode | string | general | Default recall mode. Options: general, decision, project, people, workflow, conversation |
defaultRecallLimit | number | 8 | Number of memories to recall per query (1–20) |
channelScope | string | — | Namespace prefix for tenant, client, or agent isolation. Example: coach |
localSummaryInjection | boolean | true | Inject relevant local summaries into the context window based on the current query |
localSummaryMaxTokens | number | 2000 | Maximum tokens to spend on injected local summaries (0–8000) |
Example config
{
"plugins": {
"entries": {
"crystal-memory": {
"enabled": true,
"config": {
"apiKey": "your-api-key-here",
"defaultRecallMode": "project",
"defaultRecallLimit": 10,
"channelScope": "my-team",
"localSummaryMaxTokens": 3000
}
}
}
}
}
Use channelScope when running multiple agents or teams on the same Memory Crystal account. All API calls will be namespaced as {channelScope}:{peerId}, keeping memories isolated between contexts.
