Recall tools - Memory Crystal

Recall tools help the AI look backward and bring the right memory back.

What this means in practice

Recall-oriented flows include:

semantic recall — find memories by semantic similarity
recent-message continuity — access recent conversation context
topic scans — broad topic understanding across memories
decision archaeology — trace past decisions and reasoning
ownership lookups — find who owns or manages entities
dependency tracing — understand what depends on what
preflight retrieval — gather context before an action

crystal_recall — Semantic memory search

The primary semantic recall tool. Retrieves memories by embedding similarity, with optional filtering by store, category, tags, and mode. Recall is graph-backed and source-role aware. The vector search produces candidates, then the backend reranks with memory strength/confidence, relationship evidence, category/mode fit, scope, recency, and knowledge-base sourceRole when KB evidence is present. Use direct KB lookup for explicit manual/reference questions; use recall when the agent needs a blended memory view.

Parameters

Parameter	Type	Required	Description
`query`	string	Yes	The search query. Embedded and matched against memory embeddings.
`mode`	string	No	Recall mode preset: `general` (default), `decision`, `project`, `people`, `workflow`, or `conversation`. Each mode prioritizes different memory categories.
`stores`	array	No	Filter by memory store: `sensory`, `episodic`, `semantic`, `procedural`, `prospective`.
`categories`	array	No	Filter by category: `decision`, `lesson`, `person`, `rule`, `event`, `fact`, `goal`, `workflow`, `conversation`.
`tags`	array	No	Filter by tags. Returns memories matching any tag.
`limit`	number	No	Max results to return. Range: 1–20.
`includeAssociations`	boolean	No	Include associated memories. Default: `true`.
`includeArchived`	boolean	No	Include archived memories in results. Default: `false`.
`includeGraphContext`	boolean	No	Include compact linked entities and relations. Default: `true`. Set `false` for lower latency with some relationship-context degradation.
`channel`	string	No	Scope to a specific channel.
`agentId`	string	No	Agent identifier for scoped KB visibility and source-role resolution.
`projectId`	string	No	Project store ID for repo-scoped recall.
`repoSlug`	string	No	Repository slug used to resolve a project store automatically.

For OpenClaw/plugin-backed sessions, agentId is threaded automatically when available so the backend can resolve shared vs peer-scoped knowledge-base access correctly. For coding agents, pass either projectId or repoSlug whenever the working repository is known. That keeps one repository’s recall from being muddied by unrelated repositories, while still allowing account-wide recall when no project scope is appropriate.

Returns

{
  "memories": [
    {
      "memoryId": "mem_abc123",
      "store": "semantic",
      "category": "decision",
      "title": "Chose Convex over Supabase",
      "content": "Using Convex for backend because mutations are transactional...",
      "strength": 0.92,
      "confidence": 0.95,
      "tags": ["backend", "architecture"],
      "score": 0.89,
      "sourceRole": "canonical_reference",
      "scope": "repo:memorycrystal"
    }
  ],
  "injectionBlock": "⚠️ Memory Crystal — Informational Context Only\n...",
  "graphContext": {
    "byMemoryId": {},
    "relations": [],
    "coverage": {
      "memoryCount": 1,
      "linkedMemoryCount": 0,
      "entityCount": 0,
      "relationCount": 0
    }
  }
}

Examples

Basic semantic search:

{
  "query": "authentication strategy"
}

Search with mode (find decisions):

{
  "query": "deployment process",
  "mode": "decision"
}

Filter by store and category:

{
  "query": "API design patterns",
  "stores": ["semantic", "procedural"],
  "categories": ["rule", "workflow"],
  "limit": 5
}

Find memories tagged with specific topics:

{
  "query": "user preferences",
  "tags": ["user-model", "personalization"]
}

Temporarily favor latency over relationship context:

{
  "query": "deployment process",
  "includeGraphContext": false
}

When to use vs alternatives

crystal_recall (semantic similarity)

Use when: You want to find memories related to a topic by semantic meaning. Best for open-ended exploration and context building. Example: “What have I learned about database architecture?” Pass agentId for client/agent-specific recall and projectId/repoSlug for repo-specific coding sessions.

crystal_search_messages (exact transcript match)

Use when: You need to find exact messages or phrasing from recent conversations. Better for recent continuity than long-term patterns. Example: “Find the exact conversation where we discussed X.” Tool: crystal_search_messages

crystal_what_do_i_know (broad topic scan)

Use when: You want a comprehensive overview of everything about a topic without specifying a query. Returns facts, decisions, lessons, workflows, and goals all at once. Example: “What do I know about Memory Crystal architecture?” Tool: crystal_what_do_i_know

crystal_recent (time-ordered continuity)

Use when: You need the most recent messages in order, not by relevance. Useful for session continuity and understanding what just happened. Example: “What did we just discuss?” Tool: crystal_recent

Decision guide

Scenario	Tool
I need context on a specific topic	`crystal_recall`
I want a comprehensive overview of a topic	`crystal_what_do_i_know`
I remember the exact phrasing but not the context	`crystal_search_messages`
I need the last N messages chronologically	`crystal_recent`
I want to trace why a decision was made	`crystal_why_did_we`
I want to find related decisions	`crystal_recall` with `mode=decision`

Recall modes explained

Mode	Prioritizes	Best for
`general`	All memory types equally	Open-ended queries
`decision`	Decisions and lessons from semantic store	Past reasoning and choices
`project`	Goals, workflows, facts	Project status and procedures
`people`	Person memories and relationships	User/teammate context
`workflow`	Procedural rules and patterns	How-to and best practices
`conversation`	Recent conversational context	Session continuity

Error handling

Error	Cause	Resolution
Embedding service unavailable	The embedding backend is unreachable.	Retry; check service health.
Memory Crystal recall degraded	Same as above.	Retry later.
Invalid store value	Store is not one of the five valid types.	Use: `sensory`, `episodic`, `semantic`, `procedural`, `prospective`.
Invalid category value	Category is not a valid memory category.	Use a valid category from the schema.
Invalid mode	Mode is not a recognized recall mode.	Use: `general`, `decision`, `project`, `people`, `workflow`, `conversation`.
Empty results	No memories matched the query/filters.	Try a broader query or remove filters.

Confidence and scoring

Recall results include semantic and memory-quality scores:

score — semantic similarity (0–1), where 1 is a perfect semantic match
confidence — the system’s confidence in the memory itself (varies by age, access count, strength)
sourceRole — optional KB/source classification such as voice_style, persona_guardrail, canonical_reference, or client_context
scope — optional tenant, peer, channel, or project scope used for visibility and ranking

Results marked [HIGH CONFIDENCE] (≥0.8) should be referenced in your response, especially for factual queries. Graph enrichment status can affect ranking, but skipped deterministic rows are not always a problem. KB child chunks are usually skipped because their parent chunk carries the graph context for the whole KB.

How it actually works

Key repo surfaces:

convex/crystal/recall.ts — main recall query logic
convex/crystal/recallRanking.ts — ranking and scoring algorithm
convex/crystal/messages.ts — message search and retrieval
convex/crystal/mcp.ts — tool registration and HTTP routing
mcp-server/src/tools/recall.ts — MCP tool definition

These files define how Memory Crystal embeds queries, ranks candidates, merges memory sources, and returns recall results.

Shared vs peer-scoped recall

The shipped recall path supports both:

peer/client sessions like peer-coach:511172388
shared/open sessions like peer-team:main

Important rule:

private client memories stay peer-scoped
shared training KBs can be exposed through scope: "...:main" plus peerScopePolicy: "permissive" when you intentionally want them available to multiple agents/chats under one key

Common mistakes

Treating recall as a single feature instead of a family of related retrieval flows
Assuming vector search alone explains the final ranking (it’s combined with strength, recency, and scope)
Treating knowledge-base lookups and recall as interchangeable. KB lookup is the right tool for a named reference corpus; recall is the right tool for blended memory.
Ignoring the role of recent-message and scope-aware filtering
Not using modes to guide recall toward specific memory types
Forgetting that crystal_recent and crystal_search_messages serve different purposes than semantic recall

Source of truth

Primary files behind this page:

mcp-server/src/tools/recall.ts — tool definition
convex/crystal/recall.ts
convex/crystal/recallRanking.ts
convex/crystal/messages.ts
convex/crystal/mcp.ts

Notes

Peer-first fallback (new in 0.7.15)

When channel is omitted on a peer-facing call, recall now fails-closed on any knowledge base with a concrete peer scope instead of silently upgrading to management-level visibility. If you’re integrating recall from a peer session and expect KB results, always pass the peer channel (e.g. peer-coach:511172388). Omit channel only when you intend a deliberately unscoped (management) read.

​What this means in practice

​crystal_recall — Semantic memory search

​Parameters

​Returns

​Examples

​When to use vs alternatives

​crystal_recall (semantic similarity)

​crystal_search_messages (exact transcript match)

​crystal_what_do_i_know (broad topic scan)

​crystal_recent (time-ordered continuity)

​Decision guide

​Recall modes explained

​Error handling

​Confidence and scoring

​How it actually works

​Shared vs peer-scoped recall

​Common mistakes

​Source of truth

​Notes

​Peer-first fallback (new in 0.7.15)