1. Synopsis
Hold the head loaded and answer lookups over .memhtml/head.sock (mode 0600, JSON over HTTP, routes /v1/status, /v1/search, /v1/read, /v1/neighbors, /v1/exec, /v1/commit, /v1/rebase) until SIGTERM or SIGINT. The server loads its ref’s tip once the cheapest way (snapshot, snapshot+advance, or git), reads the ref before every answer and advances over the changed paths when it moved, so an answer is never older than the ref at the moment of the request, and polls between requests. With an embedder bound (not MEMHTML_EMBED=off) it also holds the vector cache head embed writes, reads it again when the file’s mtime changes, and runs the vector arm for /v1/search and /v1/neighbors the way head search and session put do locally, answering with the same vector field. A /v1/search waits for its query embed at most the body’s embedDeadlineMs, else MEMHTML_EMBED_DEADLINE_MS, else 450 ms, and answers embed-timeout without the arm past it, leaving at most one late embed to finish in the background; and, when MEMHTML_EMBED_WARM_IDLE_MS is set above 0 (it is off by default), no embed has ended for that long, and none is in flight, it issues one one-token embed, so the first search after a quiet stretch is warm (status reports both under embed). An advance that brings records the cache has no vector for embeds them in the background, a bounded batch at a time, and writes them to the cache file as head embed would (status reports vectors.pending and vectors.backfill). head status, head search, session put, session exec, session commit, and session rebase ask it first, and /v1/exec runs the script in a pool of worker threads (MEMHTML_EXEC_POOL_SIZE at once, by default one fewer than the machine’s available parallelism, at least 1 and at most 4; each with a MEMHTML_EXEC_WORKER_HEAP_MB heap; one per session id at a time) so a runaway script never stalls a lookup. /v1/commit commits one session at a time over the version at its base, the same commit the CLI runs locally, then holds the new commit and writes its snapshot, so a run-end commit costs no head load; with --drop-refused a commit behind the tip is rebased onto it and committed again inside the same permit, up to 3 times. The curate commands always load locally. At startup the server logs one line naming the store’s policy source (memhtml.config.json absent: library defaults, the file’s path, or why it does not decode); every request that judges a record reads the file again, and status reports it as of the request under policy. A live server on the socket refuses a second one (ERR_HEAD_SERVER_RUNNING); a socket left by a killed server is replaced; a store whose socket path is past the platform’s limit (107 bytes on Linux, 103 on macOS) is refused before the load with ERR_STORAGE naming the limit, and every client there loads locally. Under win32 the server listens on the named pipe \\.\pipe\memhtml-<the first 16 hex digits of the SHA-256 of the store path> instead of a socket file. The socket is removed on exit, and the envelope reports the ref, final sha, advances, requests, and uptime.
memhtml head serve [options]2. Arguments
This command takes no positional arguments.
3. Flags
| Flag | Type | Default | Values | Description |
|---|---|---|---|---|
--ref |
string | no default | no fixed set | The ref to follow, as a branch name or a full ref; refs/heads/ is prepended when absent. Default: the branch HEAD points at, else main. |
--poll-ms |
integer | 1000 |
no fixed set | How often the server reads the ref between requests, in milliseconds; 0 leaves advancing to requests alone. Every request reads the ref regardless. |
Every command also accepts the global flags.
4. Response
On success the command writes one JSON envelope to stdout, and its type is head.served.
On failure it writes the failure envelope, whose code comes from error codes.
The JSON envelope gives the fields both shapes carry. Response types lists every value type takes across the binary.
5. Further reading
No guide block names this command. The 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.