Repository navigation
API Reference
Every function in libgalahad.so, grouped by what you are trying to do.
| Functions |
104, all exported from libgalahad.so: 91 in merlin.h (Taliesin and storage), 13 in galahad_blaise.h (Blaise) |
| Headers |
merlin.h and galahad_blaise.h: the only two you include |
| ABI | 1.31 (29 September 2026) |
| Verified | 29 September 2026: the release library exports exactly these 104 functions |
The C functions use the merlin_ prefix. That is only the name of the C
interface; the product is Galahad. See Names.
⚠ This is the index, not the manual. Each function's full contract, its error codes and its argument rules are in the header. This page tells you which function you want.
Every call that can fail returns merlin_status. Nothing throws, ever.
merlin_status st = merlin_lookup(...);
if (st != MERLIN_OK) {
fprintf(stderr, "%s: %s\n", merlin_status_string(st), merlin_last_error());
}merlin_status_string() names the code (MERLIN_OK, MERLIN_ERR_*).
merlin_last_error() adds the detail for the last failure on this thread.
| Function | What it is for |
|---|---|
merlin_init |
start the library. See Install for the two required fields |
merlin_shutdown |
stop it. ⚠ Skipping this loses access counters, which warm start ordering depends on |
merlin_rehydrate |
reload what is stored on disk after a restart |
merlin_checkpoint |
write pending records to disk |
merlin_abi_version · merlin_version_string
|
what your copy is |
merlin_last_error · merlin_status_string
|
why the last call failed |
merlin_index_rank_stores |
several GPUs: make what the other GPU processes saved findable here. The vLLM connector calls it for you (ABI 1.31) |
⚠ merlin_init, merlin_rehydrate and merlin_shutdown are not thread
safe. Call them from one thread at startup and shutdown. Everything else on
this page is safe to call concurrently.
This is the loop a serving host runs for every request.
| Function | What it is for |
|---|---|
merlin_hash_tokens |
turn a tokenised prompt into a lookup key |
merlin_lookup |
is this in memory? → miss / in VRAM / on disk |
merlin_lookup_confirmed |
the same, with a second independent check |
merlin_load_block |
read a block's bytes back |
merlin_deposit_from_context · merlin_deposit_bytes
|
store what you just computed |
merlin_register_vram · merlin_register_vram_confirmed
|
tell Galahad a block is held in GPU memory |
merlin_release_context |
done with this context |
merlin_should_graft |
is reuse worth it here, on this hardware? |
merlin_min_useful_prefix |
below this length, reuse does not pay |
merlin_lookup_longest |
the longest stored prefix of this prompt |
merlin_lookup_stepped |
the same, on a step size you pass |
merlin_grid_snap · merlin_grid_points · merlin_grid_snap_aligned
|
the prompt lengths to save at, so that a later lookup finds them |
merlin_window_first_block |
for sliding window models: the first page a reading of this length still needs |
⭐ Prefer the _confirmed variants. A reuse decision then rests on two
independent checks rather than one. A wrong reuse produces fluent, wrong output
rather than an error. See Collision Safety.
For fleets of agents that share a long common preamble. See Prefix Sharing.
| Function | What it is for |
|---|---|
merlin_hash_prefix_chain |
key a sequence by its prefix chain |
merlin_lookup_prefix |
find the longest stored prefix of this prompt |
merlin_deposit_chain |
store a sequence so later prefixes of it can be found |
⚠ Chunks must be at least 64 tokens. A smaller chunk is refused with
MERLIN_ERR_INVALID_ARG.
⚙ With vLLM you do not call these yourself. One setting turns prefix sharing on in the connector; see Prefix Sharing.
| Function | What it is for |
|---|---|
merlin_fork_branch |
a new branch from an existing one, sharing its memory |
merlin_list_branches · merlin_discard_branch
|
manage them |
merlin_snapshot_branch |
mark a moment you can return to |
merlin_restore_snapshot |
return to it, bit for bit, even after a restart |
merlin_checkpoint_branch |
a fast in-process mark, gone when the process ends |
merlin_rewind · merlin_set_rewind_permission
|
step a session back |
On a serving engine (vLLM, SGLang) the plug-in uses these instead:
| Function | What it is for |
|---|---|
merlin_branch_configure · merlin_branch_reset
|
set the limits (memory held, time to live) |
merlin_branch_point_tokens |
where a branch point falls in a prompt |
merlin_branch_fork · merlin_branch_pin_update · merlin_branch_discard
|
open a branch, record what it holds, close it |
merlin_branch_take_releases |
the pages the engine may now free |
merlin_branch_snapshot · merlin_branch_snapshot_poll · merlin_branch_restore
|
name a moment, commit it, return to it |
merlin_branch_get_stats |
forks, snapshots, restores, refusals |
⚠ merlin_rewind is half of the job. You must truncate your own
conversation history too. Both, or neither: the library cannot see your history.
For separate trust domains sharing one machine. See Tenant Isolation.
| Function | What it is for |
|---|---|
merlin_set_tenant_salt · merlin_get_tenant_salt
|
give a tenant its own keyspace, unreachable from another |
merlin_reserve_tenant_vram |
guarantee a tenant some capacity |
merlin_get_tenant_stats · merlin_reset_tenant_stats
|
per tenant hits, misses, evictions caused and suffered |
merlin_forget_tenant |
erase a tenant's data. The GDPR call |
⚙ Reservations are off unless you set them. The default reservation is zero, which means an unconfigured deployment has no protection against one noisy tenant. Per tenant pressure is visible by default; it is not prevented by default.
See Encryption at Rest.
| Function | What it is for |
|---|---|
merlin_set_key_provider |
supply your key manager. ⚠ Call this BEFORE merlin_init, or init refuses |
merlin_use_file_key_provider |
a key from a file, for trying it out only: it sits beside the data and the library says UNSAFE every time |
merlin_key_failure_count |
how many key operations have failed |
⚠ On failure your provider must return 0, never 1 with partial key material. Half a key is worse than no key.
See Agent Connectors and Replay.
| Function | What it is for |
|---|---|
merlin_record_step |
record one step of an agent run |
merlin_attribute_failure |
which layer caused it: application, model, or memory |
merlin_replay_start_trace · merlin_replay_stop_trace
|
record a run to a bundle |
merlin_replay_trace_output · merlin_replay_trace_tool
|
what the run produced |
merlin_replay_compare |
replay a bundle and find the first divergence |
merlin_replay_check_scope |
is this bundle replayable here? |
merlin_replay_last_report |
the detail of the last comparison |
⚠ A scope mismatch is not a test failure. Check scope first; a bundle recorded on different hardware is telling you something different from a bundle that genuinely diverged.
| Function | What it is for |
|---|---|
merlin_mark_immutable · merlin_clear_immutable · merlin_is_immutable
|
protect a block from eviction |
merlin_begin_idle · merlin_end_idle
|
mark a window where background work may run |
merlin_set_host_allocator |
supply your own host memory allocator |
merlin_set_transport_cost · merlin_router_set_calibration
|
teach Galahad your hardware's real costs |
merlin_get_stats |
hits, misses, bytes, evictions |
merlin_get_savings |
what reuse avoided, in seconds and money. See Cost Reporting |
merlin_set_disk_budget · merlin_disk_bytes_written
|
cap what Galahad may write, and always leave some disk free |
merlin_pinned_budget · merlin_pinned_round · merlin_pinned_slots
|
how much host memory Galahad may reserve for loading, sized from the machine |
merlin_telemetry_stats_get · merlin_telemetry_set_host_kinds
|
Galahad's own event log, and which events your host logs itself |
For hosts whose KV lives in pages, such as vLLM.
| Function | What it is for |
|---|---|
merlin_set_paged_layout · merlin_get_paged_layout
|
describe how your KV pages are laid out |
merlin_set_paged_layout_bounds |
the limits of that description |
merlin_gather_blocks · merlin_scatter_blocks
|
move pages in and out |
⚠ Always set struct_size on the layout struct. A caller that does not is
refused, so the library never reads past the end of your struct.
| Function | What it is for |
|---|---|
merlin_fuse_blocks |
use several stored blocks together in one context |
merlin_dedup_text |
remove repeated text before it is stored |
merlin_reload_licence |
pick up a new licence without restarting |
#include "galahad_blaise.h". Blaise keeps your documents as exact text. See
Names.
| Function | You pass | You get |
|---|---|---|
galahad_blaise_available |
nothing | 1 if this library was built with Blaise, 0 if not |
galahad_blaise_create |
a pointer to fill | a new, empty library handle |
galahad_blaise_destroy |
the handle | nothing; the handle is freed |
galahad_blaise_add_document |
the handle, a title, the text and its length | the ids of the chapters the document received |
galahad_blaise_chapter_count |
the handle | how many chapters are held |
galahad_blaise_map |
the handle and a buffer | a text overview of the chapters held |
galahad_blaise_chapter_code |
a chapter id | that chapter's short code |
galahad_blaise_chapter_of_code |
a short code | the chapter id it stands for |
galahad_blaise_find |
the handle, a question and k
|
up to k chapter ids with scores, best first |
galahad_blaise_text |
the handle, a chapter id and a buffer | that chapter's exact text, byte for byte as added |
galahad_blaise_label |
the handle, a chapter id and a buffer | that chapter's label: title and heading |
galahad_blaise_get_stats |
the handle and a stats struct (set struct_size) |
documents, chapters and bytes held |
galahad_blaise_status_string |
a status code | its name |
Calls that fill a buffer use two calls. Pass out = NULL first to learn the
size in *out_len, then call again with a buffer that big. A buffer that is too
small returns GALAHAD_BLAISE_BUFFER_SMALL.
find returning zero chapters is a real answer ("nothing matches"), not an
error.
GALAHAD_BLAISE_NO_STRUCTURE from add_document is a warning, not a
failure. The text is stored.
One handle is for one thread at a time. Separate handles are independent.
⚠ A library built without Blaise still exports these names; every call
returns GALAHAD_BLAISE_DISABLED. Check galahad_blaise_available() at run
time.
int major = 0, minor = 0;
merlin_abi_version(&major, &minor);
printf("ABI %d.%d -- %s\n", major, minor, merlin_version_string());MAJOR breaks, MINOR adds. A library with the same MAJOR and a MINOR at least
as new as the features you use will link and run. A newer MINOR is always
accepted: that is what the struct_size fields are for.
⭐ New capability arrives as a new function, never as a new argument on an old one. Code you compiled against an older header keeps working.
- Install: get this far first
- Agent Connectors · Branching and Snapshots · Prefix Sharing