Skip to main content
Memory Crystal captures memories automatically, but these tools let you take direct control — storing important context on demand, correcting mistakes, creating restore points, and managing what your AI knows.

​
crystal_remember

Store a memory manually. Use this when you’ve made a decision, learned something important, or want to ensure a fact is preserved — without waiting for automatic extraction. Every memory you store is embedded and added to the knowledge graph, making it immediately available for future recall.

​
Parameters

​
title
string
required
A short, descriptive title. Must be between 5 and 80 characters. Good titles are specific and searchable: "Chose PostgreSQL over SQLite — needs concurrent write support" not "database decision".
​
content
string
required
The full memory content. Include enough context to be useful when recalled months from now — what was decided, why, what alternatives were rejected, what the outcome was.
​
store
string
The memory store to write to. Each store has different retention rules and search weights. Leave blank to let Memory Crystal infer the store from the content.
  • sensory — raw observations and signals; fades fastest
  • episodic — events and experiences
  • semantic — facts and knowledge (use for most decisions, facts, and lessons)
  • procedural — how-to memory, runbooks, and repeated workflows
  • prospective — plans and future intentions
​
category
string
The memory category. Affects how the memory is weighted during recall. Leave blank to let Memory Crystal infer from the content.
  • decision — architectural or technical decisions
  • lesson — things learned from mistakes or experience
  • person — information about a person
  • rule — constraints, policies, or standing instructions
  • event — something that happened
  • fact — a stable fact
  • goal — a target or intention
  • workflow — a repeatable process
  • conversation — a session summary or notable exchange
​
tags
array
Tags for filtering and organization. Use 3–6 tags mixing specific (convex, embedding) and general (architecture, decision). Pick consistent terms — deploy vs deployment, choose one.
​
confidence
number
Confidence in the memory’s accuracy, from 0 to 1. Defaults to 0.7. Use higher values for well-established facts, lower for uncertain or tentative information.
​
channel
string
Store this memory in a specific channel scope instead of the default scope.

​
Example

// Store an architectural decision
crystal_remember({
  store: "semantic",
  category: "decision",
  title: "Chose Convex over PostgreSQL — real-time subscriptions and multi-tenant isolation",
  content: "Evaluated PostgreSQL (with Supabase) vs Convex. Chose Convex because the real-time subscription model fits the recall injection pattern, and the multi-tenant isolation is built-in rather than implemented manually. Main trade-off: vendor lock-in on Convex query syntax.",
  tags: ["database", "architecture", "convex", "decision"]
})

// Save a lesson
crystal_remember({
  store: "semantic",
  category: "lesson",
  title: "Embedding cache bug — stale vectors returned after content updates",
  content: "After updating memory content, the embedding cache was not invalidated. Recalled memories had outdated vectors that caused low-relevance matches. Fix: flush the embedding cache on any memory update mutation. Detection: recall returning memories that don't match the query.",
  tags: ["embedding", "cache", "bug", "lesson"]
})

// Store a procedural workflow
crystal_remember({
  store: "procedural",
  category: "workflow",
  title: "Deploy Convex changes — run dev mode check before deploy",
  content: "Always run `npx convex dev` and verify no schema errors before running `npx convex deploy`. Schema mismatches fail silently in some environments and corrupt the index. After deploy, run `npm run test:smoke` to verify recall is working.",
  tags: ["deploy", "convex", "workflow"]
})

​
crystal_wake

Call crystal_wake at the start of every session. It returns a briefing with active goals, recent decisions, and any standing guardrails — giving your AI immediate context before you start working.
In the OpenClaw plugin, crystal_wake is called automatically at session start via the before_agent_start hook. If you’re using the MCP server, call it yourself at the beginning of each session.

​
Parameters

​
channel
string
Load the briefing for a specific channel scope. Useful when working across multiple projects or clients.

​
Example

// Standard session start
crystal_wake({})

// Start a session scoped to a specific project
crystal_wake({ channel: "project:alpha" })

​
crystal_checkpoint

Save a labeled snapshot of the current memory state. Use checkpoints at project milestones, before risky changes, or whenever you want a named restore point. You can also use mode: "list" to view existing checkpoints.

​
Parameters

​
label
string
required
A descriptive label for the checkpoint. Required when mode is create. Describe what just happened or what state you’re capturing: "Finished auth refactor — all tests passing".
​
mode
string
create (default) to create a new checkpoint, or list to view existing checkpoints.
​
description
string
An optional longer description of the checkpoint.
​
tags
array
Tags for the checkpoint.
​
memoryIds
array
Specific memory IDs to include in the snapshot. Omit to include all current memories automatically.
​
limit
number
When listing checkpoints: maximum number to return (1–100). When creating: maximum memories to include in the snapshot.
​
channel
string
Scope the checkpoint to a specific channel.

​
Example

// Create a checkpoint at a milestone
crystal_checkpoint({
  label: "Finished embedding pipeline refactor — switched to Gemini, all tests passing",
  tags: ["milestone", "embedding"]
})

// List recent checkpoints
crystal_checkpoint({ mode: "list", limit: 10 })

​
crystal_edit

Update an existing memory. Use this to correct errors, add new information, recategorize a memory, or update its status. Provide the memoryId and only the fields you want to change.

​
Parameters

​
memoryId
string
required
The ID of the memory to update. Get this from crystal_recall or crystal_stats results.
​
title
string
New title for the memory.
​
content
string
New content for the memory.
​
tags
array
New tags for the memory. Replaces the existing tag list.
​
store
string
New store for the memory. Valid values: sensory, episodic, semantic, procedural, prospective.
​
category
string
New category for the memory. Valid values: decision, lesson, person, rule, event, fact, goal, workflow, conversation.

​
Example

// Fix an incorrect title
crystal_edit({
  memoryId: "jd7abc123",
  title: "Chose Convex over PostgreSQL — real-time subscriptions required"
})

// Add tags and recategorize
crystal_edit({
  memoryId: "jd7abc123",
  tags: ["convex", "database", "architecture", "decision"],
  category: "decision"
})

​
crystal_forget

Archive or permanently delete a memory. The default is a soft archive — the memory is hidden from recall but recoverable. Use permanent: true only when you are certain the memory should be irretrievably deleted.
permanent: true is irreversible. The memory cannot be recovered. Use it only for memories that contain sensitive information you need removed, not just memories you no longer want surfaced in recall.

​
Parameters

​
memoryId
string
required
The ID of the memory to archive or delete.
​
permanent
boolean
If true, permanently and irretrievably deletes the memory. Defaults to false (soft archive).
​
reason
string
Optional reason for archiving or deleting. Stored in the audit log.

​
Example

// Soft archive — hidden from recall but recoverable
crystal_forget({ memoryId: "jd7abc123" })

// Permanent deletion
crystal_forget({
  memoryId: "jd7abc123",
  permanent: true,
  reason: "Contains sensitive API key that was accidentally stored"
})

​
crystal_trace

Trace a memory back to the source conversation that created it. Returns the conversation snapshot — the raw messages from the turn where the memory was extracted. Use this to verify a memory’s provenance or understand the context in which it was captured.

​
Parameters

​
memoryId
string
required
The ID of the memory to trace.

​
Example

crystal_trace({ memoryId: "jd7abc123" })

​
crystal_stats

Returns health metrics and store statistics for your Memory Crystal account. Use it to understand memory usage, how memories are distributed across stores, capture activity, and which memories are strongest. No parameters required.

​
Example

crystal_stats({})
Returns total memory count, archived count, average strength, captures in the last 24 hours, per-store counts, and a list of your strongest memories.

​
crystal_set_scope

Override the channel scope for the current session. By default, Memory Crystal uses the channelScope set in plugin configuration. Use crystal_set_scope to temporarily switch to a different namespace — for example, to work on a different client project without changing the plugin config.
crystal_set_scope is only available in the OpenClaw plugin. The MCP server uses channel parameters on individual tool calls instead.

​
Parameters

​
scope
string
required
The scope string to apply for the remainder of the session. Use the same format as channelScope in plugin config (e.g. "project:alpha", "client:acme").

​
Example

crystal_set_scope({ scope: "project:alpha" })

​
crystal_ideas

Lists recent discoveries made by Memory Crystal’s Organic system — cross-memory connections, patterns, contradictions resolved, and insights found between sessions.

​
Parameters

​
status
string
Filter by idea status.
  • pending — unread discoveries (default)
  • starred — ideas you’ve saved as valuable
  • all — everything
​
limit
number
Maximum number of ideas to return. Must be between 1 and 20. Defaults to 5.

​
Example

// View unread discoveries
crystal_ideas({})

// View all starred ideas
crystal_ideas({ status: "starred", limit: 20 })

​
crystal_idea_action

Take action on an Organic idea — star it as valuable, dismiss it, or mark it as read.

​
Parameters

​
ideaId
string
required
The ID of the idea to act on. Get this from crystal_ideas results.
​
action
string
required
The action to take.
  • star — save as valuable; surfaces in crystal_ideas({ status: "starred" })
  • dismiss — hide from future results
  • read — mark as acknowledged without starring or dismissing

​
Example

// Star a valuable discovery
crystal_idea_action({
  ideaId: "idea_abc123",
  action: "star"
})

// Dismiss a low-value idea
crystal_idea_action({
  ideaId: "idea_xyz789",
  action: "dismiss"
})