Skip to main content
Recall tools let you query what Memory Crystal knows. They search across short-term messages, long-term extracted memories, and the knowledge graph — returning relevant context your AI can use when answering questions or making decisions.

​
crystal_recall

Semantic search across all long-term memory. This is the general-purpose recall tool for questions like “what do we know about X?” or “what was decided about Y?” crystal_recall embeds your query, runs hybrid BM25 + vector search across LTM, re-ranks results by relevance, strength, and freshness, and returns the top matches.

​
Parameters

​
query
string
required
The search query. What you want to recall.
​
mode
string
Recall mode preset. Controls which memory stores and categories are weighted most heavily.
  • general — broad recall across all stores (default)
  • decision — prioritizes decisions, lessons, and rules
  • project — pulls goals, workflows, facts, and active implementation context
  • people — focuses on person memories and ownership context
  • workflow — surfaces procedural rules and reusable how-to patterns
  • conversation — favors recent conversational context and session continuity
​
limit
number
Maximum number of results to return. Must be between 1 and 20. Defaults to the plugin’s defaultRecallLimit setting (8 by default).
​
stores
array
Filter results to specific memory stores. Valid values: sensory, episodic, semantic, procedural, prospective. Omit to search all stores.
​
categories
array
Filter results to specific memory categories. Valid values: decision, lesson, person, rule, event, fact, goal, workflow, conversation. Omit to search all categories.
​
tags
array
Filter results to memories with specific tags.
​
includeAssociations
boolean
Whether to include graph-associated memories that are connected to the top results. Defaults to true.
​
includeArchived
boolean
Whether to include archived memories in results. Defaults to false.
​
channel
string
Override the channel scope for this query. Useful for cross-channel lookups.

​
Example

// General recall
crystal_recall({ query: "authentication approach" })

// Decision-mode recall for a specific topic
crystal_recall({
  query: "why did we switch to Convex",
  mode: "decision",
  limit: 5
})

// Filter to procedural memories tagged with deploy
crystal_recall({
  query: "deployment steps",
  stores: ["procedural"],
  tags: ["deploy"]
})

​
crystal_what_do_i_know

Returns a broad topic snapshot — everything Memory Crystal knows about a given topic across all stores. Use this when you want a comprehensive view of what’s stored about a subject, rather than a ranked search.

​
Parameters

​
topic
string
required
The topic to scan. Must be at least 3 characters.
​
stores
array
Limit the scan to specific memory stores. Valid values: sensory, episodic, semantic, procedural, prospective.
​
tags
array
Filter to memories with specific tags.
​
limit
number
Maximum number of memories to return. Must be between 1 and 20.

​
Example

crystal_what_do_i_know({ topic: "embedding pipeline" })

crystal_what_do_i_know({
  topic: "session storage",
  stores: ["semantic", "procedural"],
  limit: 10
})

​
crystal_why_did_we

Decision archaeology. Searches specifically through decision-category memories to understand the reasoning behind a past choice. Returns the most relevant decisions and a synthesized reasoning summary.

​
Parameters

​
decision
string
required
A description of the decision to investigate. Must be at least 3 characters. Example: "use Convex over PostgreSQL", "switch to Gemini embeddings".
​
limit
number
Maximum number of decision memories to return. Must be between 1 and 20. Defaults to 8.

​
Example

crystal_why_did_we({ decision: "use Convex over PostgreSQL" })

crystal_why_did_we({
  decision: "remove the local SQLite fallback",
  limit: 5
})

​
crystal_recent

Fetches the most recent messages from short-term memory (STM). Use this when you need raw conversational context from earlier in the current session or recent sessions.

​
Parameters

​
limit
number
Number of recent messages to return. Must be between 1 and 100. Defaults to 20.
​
channel
string
Filter to messages from a specific channel scope.
​
sessionKey
string
Filter to messages from a specific session.
​
sinceMs
number
Return only messages newer than this Unix timestamp in milliseconds.

​
Example

// Get the last 20 messages
crystal_recent({})

// Get 50 messages from the last hour
crystal_recent({
  limit: 50,
  sinceMs: Date.now() - 60 * 60 * 1000
})

​
crystal_search_messages

Search verbatim conversation history in STM using hybrid BM25 + vector search. Use this when you need to find specific things that were said in past conversations — exact quotes, specific exchanges, or messages containing a particular term. Unlike crystal_recall, which searches extracted LTM memories, crystal_search_messages searches raw message text.

​
Parameters

​
query
string
required
The search query. Searches against verbatim message content.
​
limit
number
Maximum number of messages to return. Defaults to 10.
​
channel
string
Filter to messages from a specific channel scope.
​
sinceMs
number
Return only messages newer than this Unix timestamp in milliseconds.

​
Example

crystal_search_messages({ query: "rate limiting approach" })

crystal_search_messages({
  query: "failed deployment",
  limit: 5,
  sinceMs: Date.now() - 7 * 24 * 60 * 60 * 1000  // last 7 days
})

​
crystal_preflight

Pre-flight check before risky actions. Call this before making config changes, API writes, file deletions, or any production system modification. It searches your stored rules, lessons, and decisions for anything relevant to what you’re about to do and returns a checklist.
You should call crystal_preflight before any destructive or irreversible action. It returns warnings from your own experience — past mistakes, rules you’ve set, and decisions that bear on the action.

​
Parameters

​
action
string
required
A description of the action you are about to take. Must be at least 3 characters. Be specific — this is used as the search query.
​
limit
number
Maximum number of relevant memories to include in the checklist. Must be between 1 and 20. Defaults to 10.

​
Example

crystal_preflight({ action: "delete all conversation history records" })

crystal_preflight({ action: "push to production without a staging review" })

crystal_preflight({ action: "rotate the API key used by the MCP server" })

​
crystal_who_owns

Find who owns, manages, or is responsible for a given entity in your knowledge graph. Returns ownership chains with confidence scores and supporting evidence.

​
Parameters

​
entity
string
required
The entity name to look up. Can be a file path, module name, system, or person. Examples: "authentication system", "src/api/users.ts", "billing pipeline".

​
Example

crystal_who_owns({ entity: "authentication system" })

crystal_who_owns({ entity: "src/convex/crystal" })

crystal_who_owns({ entity: "billing pipeline" })

​
crystal_explain_connection

Explains how two entities are related in your knowledge graph. Returns direct relationships, indirect paths through intermediate nodes, and the supporting memories that evidence the connection.

​
Parameters

​
entityA
string
required
The first entity.
​
entityB
string
required
The second entity.

​
Example

crystal_explain_connection({
  entityA: "Convex",
  entityB: "embedding pipeline"
})

crystal_explain_connection({
  entityA: "Andy",
  entityB: "deploy system"
})

​
crystal_dependency_chain

Traces the dependency chain for a goal, project, or task in the knowledge graph. Returns a tree of dependencies with depth levels and supporting evidence.

​
Parameters

​
entity
string
required
The goal, project, or task to trace dependencies for. Examples: "billing integration", "v2 launch".
​
maxDepth
number
Maximum depth to traverse. Must be between 1 and 5. Defaults to 3.

​
Example

crystal_dependency_chain({ entity: "billing integration" })

crystal_dependency_chain({
  entity: "v2 launch",
  maxDepth: 4
})