Skip to main content

​
What this means in practice

Reasoning tools help the AI explore Memory Crystal’s knowledge graph to understand context beyond simple retrieval. Instead of just finding a memory, these tools answer:
  • What do I know about X?
  • Who owns or manages Y?
  • Why did we make decision Z?
  • How is concept A connected to concept B?
  • What depends on what?

​
How it actually works

These tools operate on Memory Crystal’s semantic graph layer:
  • Vector search finds candidate memories by semantic similarity
  • Graph traversal explores relationships between memories (mentions, decides_in, depends_on, owns, etc.)
  • Ranking prioritizes results by recency, strength, and relationship type
  • Scope filtering (for multi-tenant systems) ensures memories from different channels/projects don’t bleed together
Key repo surfaces:
  • convex/crystal/recall.ts — Core recall logic shared across all reasoning tools
  • convex/crystal/recallRanking.ts — Ranking and filtering logic
  • convex/crystal/graph.ts — Knowledge graph mutations and queries
  • convex/crystal/mcp.ts — MCP tool definitions

​
Commands / examples

Representative tool names:
  • crystal_what_do_i_know — Broad topic scan
  • crystal_why_did_we — Reason archaeology for decisions
  • crystal_who_owns — Ownership and responsibility lookup
  • crystal_explain_connection — Relationship explorer between two entities
  • crystal_dependency_chain — Find what depends on what

​
When to use each

Key difference: Recall is reactive (triggered before every response), while reasoning tools are exploratory (called when you need to understand structure or relationships).

​
Common mistakes

  • Using crystal_recall when you should use crystal_what_do_i_know for broad topic scans
  • Forgetting that reasoning tools require explicit queries — they don’t auto-trigger like recall
  • Conflating crystal_why_did_we (decision archaeology) with crystal_recall (memory retrieval)
  • Using crystal_who_owns for a concept that doesn’t have explicit ownership metadata

​
Source of truth

Primary files behind this page:
  • convex/crystal/recall.ts
  • convex/crystal/recallRanking.ts
  • convex/crystal/graph.ts
  • convex/crystal/mcp.ts