crystal_trace

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

Parameter	Type	Required	Default	Description
memoryId	string	Yes	—	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

Error	Cause	Resolution
”Invalid arguments”	memoryId not provided or null	Ensure memoryId is a non-empty string
”memoryId is required”	memoryId is empty or not a string	Provide a valid memory ID from crystal_recall or crystal_what_do_i_know
Memory not found	memoryId does not exist or was deleted	Verify the ID is correct; recall memories to find valid IDs
API connection error	Convex endpoint unavailable	Retry; 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

Tools Overview

Memory Lookup

Memory Writing

Reasoning Helpers

Knowledge Bases

Stats & Ideas

HTTP API

What it does

Parameters

Returns

Examples

Basic usage

Advanced usage

When to use this vs alternatives

Error handling

Notes

​What it does

​Parameters

​Returns

​Examples

​Basic usage

​Advanced usage

​When to use this vs alternatives

​Error handling

​Notes

What it does

Parameters

Returns

Examples

Basic usage

Advanced usage

When to use this vs alternatives

Error handling

Notes