Skip to main content

​
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

ParameterTypeRequiredDescription
decisionstringYesThe decision to investigate (minimum 3 characters). Example: “use Convex instead of Supabase”
limitnumberNoMaximum number of memories to return (1-20, default: 8)

​
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: 
{
  "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

ErrorCauseResolution
decision is requiredNo decision parameter providedProvide a decision string (minimum 3 characters)
limit must be a numberInvalid limit typePass a number between 1-20
embedding service unavailableOpenAI embeddings service downRetry in a few moments

​
Notes

  • 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”