gRPC overview - HyphaeDB

gRPC is the primary protocol surface for HyphaeDB. The same application core also serves REST, MCP, and — opt-in — A2A; gRPC is the lowest-overhead way to reach it and the surface the Rust, Python, and TypeScript SDKs are built on. This page is a conceptual guide. It does not hand-document every message — the proto files are the source of truth.

View the proto definitions

proto/hyphaedb/v1/ — package hyphaedb.v1, across service.proto, nodes.proto, gossip.proto, and query.proto.

The service

All RPCs live on one service, hyphaedb.v1.Hyphae. It exposes eleven unary RPCs plus one bidirectional stream.

Unary RPCs

RPC	Request → Response	Notes
`Info`	`Empty` → `ServerInfo`	Version and capability set. The unauthenticated handshake an SDK runs at connect to negotiate compatibility.
`Store`	`StoreRequest` → `StoreResponse`	Persist a cell; returns its `node_id`.
`Recall`	`RecallRequest` → `NodeList`	Vector recall by query text; returns fully hydrated nodes in rank order.
`Query`	`QueryRequest` → `NodeList`	Structured query; returns fully hydrated nodes.
`StartSession`	`StartSessionRequest` → `SessionRef`	Open a session for the authenticated agent.
`EndSession`	`SessionRef` → `Empty`	Close a session.
`PlaceBeacon`	`PlaceBeaconRequest` → `BeaconRef`	Place a standing-interest beacon.
`ListBeacons`	`Empty` → `BeaconList`	List the caller’s beacons.
`ListScenes`	`ProjectRef` → `SceneList`	List scenes in the caller’s read scope.
`GetScene`	`SceneRef` → `Scene`	Fetch one scene.
`ConsolidateScene`	`SceneRef` → `ConsolidationReport`	Consolidate a scene. gRPC/REST only — not an MCP tool.

ConsolidateScene is available over gRPC and REST but is intentionally not exposed as an MCP tool. It is a maintenance operation rather than an agent-facing memory operation.

The inbox stream

rpc Inbox(stream InboxRequest) returns (stream InboxItem);

Inbox is how an agent receives knowledge that propagates to its node. The exchange is asymmetric: the client sends exactly one InboxRequest to open the stream, then the server pushes InboxItems for as long as the stream stays open. The single request carries a last_seen watermark (an RFC 3339 timestamp):

Send it empty to replay your full delivery history first — everything that ever reached your node or your beacons — before live delivery begins.
On reconnect, send your last processed watermark. The server replays the items you missed, then transitions to live delivery.

The stream is scoped to you as an agent — deliveries to your own node and to beacons you own: it carries a cross-agent filter so you only receive your own deliveries, and items are de-duplicated so a replay overlap never surfaces the same diff twice.

Authentication

Every RPC except the Info handshake is authenticated per call by the x-hyphae-key metadata header. Identity is resolved from that credential and never read from the request body, so a client cannot assert another agent’s identity (INV-5).

metadata:
  x-hyphae-key: hyk_<kid>_<secret>

A quick unauthenticated handshake with grpcurl:

grpcurl -plaintext localhost:50051 hyphaedb.v1.Hyphae/Info

And an authenticated unary call, passing the key as metadata:

grpcurl -plaintext \
  -H 'x-hyphae-key: hyk_...' \
  -d '{"text":"storage engine","k":5}' \
  localhost:50051 hyphaedb.v1.Hyphae/Recall

Health checks

The standard grpc.health.v1.Health service is registered alongside Hyphae, so any gRPC health-checking client or load balancer can probe the server without going through the application API.

Versioning

The Info RPC returns the server version and its advertised capability tokens. SDKs use this at connect to enforce a minimum supported server version and to gate features that depend on a capability the server may not have. The proto package is hyphaedb.v1; breaking changes ship under a new package version. See API versioning for the compatibility policy and deprecation process.

Rust SDK — the gRPC-native client.
MCP tools — the agent-facing tool surface over the same core.
API reference — the REST surface and its conventions.
Gossip propagation — what the Inbox stream delivers.

Source

This page restates the protocol layer and proto schema; it defines no new behavior.

protocol-layer spec §5.5, §6 — the gRPC service, auth, and the inbox stream.
proto/hyphaedb/v1/ — the canonical message and service definitions.

View the proto definitions

​The service

​Unary RPCs

​The inbox stream

​Authentication

​Health checks

​Versioning

​Related pages

​Source

The service

Unary RPCs

The inbox stream

Authentication

Health checks

Versioning

Related pages

Source