Skip to main content
Memory Crystal exposes 18+ tools across five families. Each tool addresses a specific use case in the memory lifecycle: recalling context, writing memories, reasoning about what you know, and working with knowledge bases. For OpenClaw/plugin-backed sessions, tool calls can also carry agent-aware scope implicitly:
  • peer-scoped agents search/write under scope:{peerId}
  • shared agents search/write under scope:main

​
Tool Families

​
Memory Lookup (5 tools)

Semantic and lexical search over stored memories and messages.
  • crystal_recall — Vector search over memories (both STM and LTM) by semantic query
  • crystal_search_messages — Exact/keyword search over raw message transcripts
  • crystal_recent — Fetch N most recent messages without embedding cost
  • crystal_trace — Follow memory back to its source conversation and extract context
  • crystal_wake — Session initialization: fetch last session summary + recent messages

​
Memory Writing & Maintenance (5 tools)

Capture, update, and manage the memory store.
  • crystal_remember — Extract and save a new memory (or batch of memories)
  • crystal_checkpoint — Label a significant session milestone with label + description
  • crystal_edit — Update existing memory (content, tags, metadata)
  • crystal_forget — Archive or permanently delete a memory by ID
  • crystal_import_knowledge — Batch-import external documents into a knowledge base

​
Reasoning Helpers (6 tools)

Introspect, explain, and traverse the memory graph.
  • crystal_what_do_i_know — Broad topic scan: summarize everything known about a concept
  • crystal_why_did_we — Decision archaeology: trace why a choice was made
  • crystal_who_owns — Ownership lookup: find who manages a project, person, or entity
  • crystal_explain_connection — Trace how two entities are related
  • crystal_dependency_chain — Map task or goal dependencies
  • crystal_preflight — Pre-action checklist: rules and lessons before destructive/production actions

​
Knowledge Base Management (3 tools)

Create, organize, and query external knowledge bases.
  • crystal_list_knowledge_bases — List all knowledge bases in the workspace
  • crystal_query_knowledge_base — Vector search a single knowledge base
  • crystal_import_knowledge — Bulk-import chunks into a knowledge base

​
Stats & Ideas (2 tools)

Observe system state and brainstorm.
  • crystal_stats — Memory store health: count by category/store, tier usage, TTL status
  • crystal_ideas — Generate contextual ideas or action items from memory graph

​
Decision Tree: Pick Your Tool

“I want to find a memory by meaning” → Use crystal_recall with semantic query “I want exact transcript / phrase search” → Use crystal_search_messages or crystal_recent “I want a broad topic summary” → Use crystal_what_do_i_know “I want to understand why we did something” → Use crystal_why_did_we (decisions) or crystal_explain_connection (entities) “I want to save new memories” → Use crystal_remember “I want to update or delete a memory” → Use crystal_edit or crystal_forget “I want to mark a session milestone” → Use crystal_checkpoint “I want to use external documents” → Use crystal_import_knowledge then crystal_query_knowledge_base “I want to check rules before a risky action” → Use crystal_preflight “I want to see what’s stored” → Use crystal_stats

​
Quick Reference Table

When building agentic workflows, follow this pattern:
  1. crystal_preflight — Check rules/lessons before risky actions (create, modify, deploy)
  2. crystal_recall — Load relevant context at turn start
  3. [Do work] — Your agent logic
  4. crystal_remember — Capture key facts/decisions
  5. crystal_checkpoint — Mark session end if significant
This ensures safety checks run first, context is primed early, and captures happen last.

​
Integration Points

Memory Crystal is available via:
  • MCP — Claude, Codex, Gemini via model context protocol (stdio or HTTP)
  • HTTP API — Direct endpoint calls with bearer token auth
  • OpenClaw plugin — Automatic hooks (recall before response, capture after response)
All integrations expose the same conceptual tool surface, though some may filter tools by capability or tier.

​
Scope-aware behavior

The hosted/plugin-backed tools now support a one-key mixed-scope pattern:
  • private/client agents → peer-scoped memories and KBs
  • shared/internal agents → shared :main KBs and memories
In normal OpenClaw use, the plugin resolves this automatically from the active agent/session config.

​
Source of Truth

  • Implementation: convex/crystal/mcp.ts, convex/crystal/knowledgeHttp.ts
  • MCP server: mcp-server/src/tools/
  • Schema: convex/schema.ts (valid store/category values)