Skip to main content

​
What it does

Retrieves the original conversation snapshot that created a specific memory. Use this to verify a memory’s provenance, understand its context, or see exactly what was discussed when the memory was extracted. Returns the full conversation turn(s) that led to the memory capture.

​
Parameters

ParameterTypeRequiredDefaultDescription
memoryIdstringYes—The ID of the memory to trace back to its source. Must be non-empty.

​
Returns

{
  "memoryId": "string",
  "sourceConversation": {
    "turns": [
      {
        "role": "user|assistant",
        "content": "string",
        "timestamp": 1234567890000
      }
    ],
    "sessionId": "string",
    "extractedAt": 1234567890000,
    "extractionModel": "gpt-4o-mini"
  },
  "memory": {
    "title": "string",
    "content": "string",
    "store": "sensory|episodic|semantic|procedural|prospective",
    "category": "decision|lesson|person|rule|event|fact|goal|workflow|conversation"
  }
}
Field descriptions:
  • sourceConversation.turns — Array of conversation messages that led to this memory
  • extractedAt — Timestamp when the memory was extracted
  • extractionModel — Which model performed the extraction (usually gpt-4o-mini)
  • memory — The extracted memory metadata including store and category

​
Examples

​
Basic usage

// Trace a memory back to the conversation that created it
crystal_trace({ memoryId: "mem_abc123def456" })

// Result:
// {
//   "memoryId": "mem_abc123def456",
//   "sourceConversation": {
//     "turns": [
//       {
//         "role": "user",
//         "content": "We decided to switch to Convex because Supabase had auth issues",
//         "timestamp": 1713283200000
//       },
//       {
//         "role": "assistant",
//         "content": "Good call. Convex handles retries automatically.",
//         "timestamp": 1713283210000
//       }
//     ],
//     "sessionId": "session_xyz789",
//     "extractedAt": 1713283220000,
//     "extractionModel": "gpt-4o-mini"
//   },
//   "memory": {
//     "title": "Chose Convex over Supabase for auth reliability",
//     "content": "...",
//     "store": "semantic",
//     "category": "decision"
//   }
// }

​
Advanced usage

// Trace multiple memories to build a timeline of decisions
const memoryIds = ["mem_1", "mem_2", "mem_3"];
for (const id of memoryIds) {
  const trace = await crystal_trace({ memoryId: id });
  console.log(`${trace.memory.title} — extracted at ${new Date(trace.extractedAt)}`);
}

​
When to use this vs alternatives

  • crystal_trace — When you need to see the original conversation context for a specific memory
  • crystal_recent — When you want recent conversation messages without linking to a specific memory
  • crystal_what_do_i_know — When you want a broad topic summary across all related memories

​
Error handling

ErrorCauseResolution
”Invalid arguments”memoryId not provided or nullEnsure memoryId is a non-empty string
”memoryId is required”memoryId is empty or not a stringProvide a valid memory ID from crystal_recall or crystal_what_do_i_know
Memory not foundmemoryId does not exist or was deletedVerify the ID is correct; recall memories to find valid IDs
API connection errorConvex endpoint unavailableRetry; check CONVEX_URL environment variable

​
Notes

  • The conversation snapshot is frozen at the time of extraction — it reflects what the extraction model saw, not necessarily all context
  • Some memories may have been extracted from partial conversations if the turn limit was hit
  • Tracing a memory does not modify it
  • If a memory was updated or edited after extraction, the trace still shows the original source
  • Use this before acting on a memory to verify it’s not outdated or taken out of context