---
title: memhtml head search
description: "Retrieval over the version at HEAD, or over the head server's version of its ref when one answers, RRF-fused: BM25, plus a vector arm (cosine over Cohere Embed v4 vectors, weight 1.0 as in v1's search) when `.memhtml/vectors/` holds a cache for the configured embedder and `MEMHTML_EMBED` is not `off`. Recency is the tie-break: only hits with exactly equal fused scores are ordered newest first, so it never lifts a weaker match over a better one. The query is embedded once with the query input type. The query embed has a deadline, `MEMHTML_EMBED_DEADLINE_MS` (450 ms by default): past it the search answers without the arm rather than wait. When the arm cannot run (embedder off, no cache yet, an unreadable cache, the query embed failed or passed its deadline) the search answers from BM25 alone and `vector` reports `used: false` with a `reason`; it never fails for it. Each hit's `arms` names the arms it scored on, and `recency` when an exact tie was broken by it. No index database."
---

## 1. Synopsis

Retrieval over the version at HEAD, or over the head server's version of its ref when one answers, RRF-fused: BM25, plus a vector arm (cosine over Cohere Embed v4 vectors, weight 1.0 as in v1's search) when `.memhtml/vectors/` holds a cache for the configured embedder and `MEMHTML_EMBED` is not `off`. Recency is the tie-break: only hits with exactly equal fused scores are ordered newest first, so it never lifts a weaker match over a better one. The query is embedded once with the query input type. The query embed has a deadline, `MEMHTML_EMBED_DEADLINE_MS` (450 ms by default): past it the search answers without the arm rather than wait. When the arm cannot run (embedder off, no cache yet, an unreadable cache, the query embed failed or passed its deadline) the search answers from BM25 alone and `vector` reports `used: false` with a `reason`; it never fails for it. Each hit's `arms` names the arms it scored on, and `recency` when an exact tie was broken by it. No index database.

```sh
memhtml head search <query> [options]
```

## 2. Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `query` | yes | Free text to rank against. |

## 3. Flags

| Flag | Type | Default | Values | Description |
| --- | --- | --- | --- | --- |
| `--limit` | integer | `10` | *no fixed set* | Hits to return. |
| `--server` | flag | `true` | *no fixed set* | Ask the head server on .memhtml/head.sock first (`memhtml head serve`), falling back to loading the head here when no server accepts within 100 ms or answers within 10 s; `--no-server` always loads here. The payload's `head.source` is `server` when the server answered. |

Every command also accepts the [global flags](/reference/global-flags/).

## 4. Response

On success the command writes one JSON envelope to stdout, and its `type` is `head.search`.

On failure it writes the failure envelope, whose `code` comes from [error codes](/reference/error-codes/).

[The JSON envelope](/reference/envelope/) gives the fields both shapes carry. [Response types](/reference/response-types/) lists every value `type` takes across the binary.

## 5. Further reading

No guide block names this command. The [guide](/reference/guide/) is the workflow prose the CLI ships beside the command table: which command to reach for, and in what order.

## 6. Provenance

A loader generates this page from `apps/cli/src/commands.ts` while the site builds, so no file in the repository holds it: the `COMMANDS` array there is the one source of argument parsing, of `memhtml manifest`, and of `AGENTS.md`. Change the registry and this page changes with it.