​

Why Did We

​

What it does

​

Parameters

​

Returns

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

{
  "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")

​

Investigating a product choice

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

​

Tracing a technical constraint

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

​

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

​

Notes

​

Peer scoping (new in 0.7.15)

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