Search

Hybrid BM25 + vector search over brain documents. Use search for targeted lookups; use recall for fused, prompt-ready memory.

GET /v1/brain/search runs hybrid BM25 + vector retrieval and returns ranked document hits. It is the targeted lookup primitive — use it when you want raw hits with scores, not a fused prompt block.

Make the call

import { BrainClient } from "@unisonlabs/sdk";

const brain = new BrainClient({ token: process.env.UNISON_TOKEN });

const results = await brain.search("pgmq migration", { limit: 5 });
for (const hit of results.results) {
  console.log(hit.doc.path, hit.score, hit.highlight);
}

from unisonlabs import UnisonBrain

client = UnisonBrain()
results = client.search("pgmq migration", limit=5)
for hit in results.results:
    print(hit.doc.path, hit.score, hit.highlight)

curl 'https://brain.unisonlabs.ai/v1/brain/search?q=pgmq+migration&k=5' \
  -H "Authorization: Bearer $UNISON_TOKEN"

Response shape

{
  "results": [
    {
      "doc": { "path": "/workspace/decisions/adr-007-pgmq.md", "title": "ADR-007: pgmq migration" },
      "score": 0.88,
      "highlight": "…migrated worker to pgmq, dropped redis…",
      "sources": ["bm25", "vector"]
    }
  ]
}

Each hit reports sources — which retrieval methods matched (bm25, vector, or both). Hits matching both are ranked higher.

Search vs recall

	Search	Recall
Output	ranked hits	fused `contextMd` block
Entity expansion	no	yes
`weakEvidence` flag	no	yes
Use when	you want raw docs to inspect or re-rank	you want to inject memory into a prompt

Default to recall for agent prompting. Use search when you need to inspect individual documents, build custom re-ranking logic, or drive a retrieval UI.

Scoping and filtering

Both search and context accept pathPrefix to confine results to a subtree:

curl 'https://brain.unisonlabs.ai/v1/brain/search?q=deploy+process&pathPrefix=%2Fworkspace%2Fteams%2Fplatform%2F&k=5' \
  -H "Authorization: Bearer $UNISON_TOKEN"

CLI: unison search "deploy process" --path-prefix /workspace/teams/platform/ -k 5

For exact-string or regex matches across document bodies, use GET /v1/brain/grep?pattern=<regex> (or unison grep "<regex>"). Grep is file-system-level — it ignores relevance ranking and returns every document containing the pattern.

See also: Context recall · API reference

Make the call

Response shape

Search vs recall

Scoping and filtering

Exact-string grep

On this page