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
{
"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
{
"tool": "search",
"arguments": {
"query": "authentication and session management",
"limit": 5
}
}
Find database choices
{
"tool": "search",
"arguments": {
"query": "database ORM query layer",
"limit": 3
}
}
Check for existing patterns
{
"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?”
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.
