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

# Why did we

export const metadata = {
  title: "crystal_why_did_we",
  description: "Investigate the reasoning and evidence behind past decisions"
};

# Why Did We

Decision archaeology across Memory Crystal decision memories.

## What it does

Searches your decision memory store to understand the reasoning, evidence, and context behind a past decision. Returns the decision thread along with supporting memories across all memory stores.

## Parameters

| Parameter  | Type   | Required | Description                                                                                                                  |
| ---------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `decision` | string | Yes      | The decision to investigate (minimum 3 characters). Example: "use Convex instead of Supabase"                                |
| `limit`    | number | No       | Maximum number of memories to return (1-20, default: 8)                                                                      |
| `channel`  | string | No       | Peer-scoped channel key (e.g. `peer-coach:511172388`). When set, filters results to memories in that channel. New in 0.7.15. |

## Returns

Returns a structured response containing:

* **reasoning**: A summary of the primary decision thread
* **relatedMemories**: Array of decision memories with store, title, content, and strength

Example response:

```json theme={"system"}
{
  "reasoning": "Primary threads around \"chose PostgreSQL over SQLite\"",
  "relatedMemories": [
    {
      "memoryId": "v1234...",
      "store": "semantic",
      "title": "PostgreSQL for concurrent writes",
      "content": "We chose PostgreSQL because our session storage needs concurrent writes with ACID guarantees...",
      "strength": 0.95
    }
  ]
}
```

## Examples

### Understanding an architecture decision

```
crystal_why_did_we(decision="chose Convex mutations over HTTP actions")
```

Returns the original reasoning, trade-offs considered, and supporting memories from your decision record.

### Investigating a product choice

```
crystal_why_did_we(decision="use Obsidian vault for memory export")
```

Returns why you selected Obsidian, what alternatives were evaluated, and any constraints that drove the decision.

### Tracing a technical constraint

```
crystal_why_did_we(
  decision="session storage architecture",
  limit=5
)
```

Returns the top 5 memories related to your session storage decisions, including the reasoning thread.

## When to use

* **Understanding past decisions** — When you need to remember why a technical choice was made
* **Evaluating alternatives** — Before reconsidering a past decision, see what trade-offs drove it
* **Onboarding** — Help new team members understand the reasoning behind key decisions
* **Audit trail** — Maintain a record of decision rationale for compliance or documentation
* **Preventing rework** — Avoid revisiting decisions that were already carefully evaluated

## Errors

| Error                           | Cause                          | Resolution                                       |
| ------------------------------- | ------------------------------ | ------------------------------------------------ |
| `decision is required`          | No decision parameter provided | Provide a decision string (minimum 3 characters) |
| `limit must be a number`        | Invalid limit type             | Pass a number between 1-20                       |
| `embedding service unavailable` | OpenAI embeddings service down | Retry in a few moments                           |

## Notes

### Peer scoping (new in 0.7.15)

Hosted / API-key consumers can now pass an explicit `channel` to scope results to a peer. Previously this tool's API-key path silently ignored channel and returned cross-channel results; as of 0.7.15, the HTTP recall branch forwards the filter consistently with JWT clients. Omit `channel` only when you intend the broadest (management-style) result set.

* The decision archaeology process filters to decision-category memories, then performs vector similarity search
* API-key clients (hosted mode) use the HTTP recall endpoint; JWT clients use the Convex action path
* Results are ranked by similarity to your query and memory strength
* Empty results indicate no decision memories matching the query — check your search terms
* The reasoning summary is synthesized from matching memories; if no memories match, you'll get "No clear decision thread was surfaced"