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

# search

> Semantic search over past architectural decisions

## Overview

`search` runs a semantic vector search over all decisions in the workspace. It finds decisions by meaning — not just keyword matching — so "how do we handle auth?" returns JWT decisions even if "authentication" wasn't the exact word used.

Decisions are embedded with OpenAI's `text-embedding-3-small` (1536 dimensions) and indexed in pgvector for fast approximate nearest-neighbor search.

## Parameters

| Parameter | Type   | Required | Description                         |
| --------- | ------ | -------- | ----------------------------------- |
| `query`   | string | Yes      | Natural language search query       |
| `limit`   | number | No       | Max results to return (default: 10) |

## Response

```json theme={null}
{
  "results": [
    {
      "id": "dec_abc",
      "title": "Use JWT for authentication",
      "rationale": "Stateless tokens work with our edge deployment. No session store needed.",
      "type": "architecture",
      "made_by": "Developer A",
      "created_at": "2026-04-13T10:00:00Z",
      "files": ["src/auth/login.ts", "src/auth/middleware.ts"],
      "similarity": 0.92
    },
    {
      "id": "dec_def",
      "title": "Rejected: cookie-based sessions",
      "rationale": "Adds Redis infrastructure complexity.",
      "type": "rejection",
      "similarity": 0.87
    }
  ]
}
```

### Response Fields

| Field        | Description                                            |
| ------------ | ------------------------------------------------------ |
| `id`         | Decision ID                                            |
| `title`      | Short description                                      |
| `rationale`  | Full rationale text                                    |
| `type`       | Decision type                                          |
| `made_by`    | User who recorded the decision                         |
| `created_at` | ISO timestamp                                          |
| `files`      | Affected files                                         |
| `similarity` | Cosine similarity score (0–1, higher is more relevant) |

## Examples

### Find auth decisions

```json theme={null}
{
  "tool": "search",
  "arguments": {
    "query": "authentication and session management",
    "limit": 5
  }
}
```

### Find database choices

```json theme={null}
{
  "tool": "search",
  "arguments": {
    "query": "database ORM query layer",
    "limit": 3
  }
}
```

### Check for existing patterns

```json theme={null}
{
  "tool": "search",
  "arguments": {
    "query": "error handling API responses"
  }
}
```

## When to Call `search`

* Before implementing something — "did we already decide on this?"
* When unfamiliar with part of the codebase — "what's the rationale for how this works?"
* Before picking a library — "have we already adopted something for this use case?"
* When debugging — "has anyone dealt with this type of issue before?"

<Tip>
  Use natural language queries. The semantic search understands intent — "how do we validate user input?" will find Zod decisions even if you don't mention Zod.
</Tip>