> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memorycrystal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# crystal_trace

> Trace a memory back to its source conversation.

## 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

```json theme={"system"}
{
  "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

```javascript theme={"system"}
// 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

```javascript theme={"system"}
// 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