gRPC Communication

All ContextUnity services communicate via gRPC — a high-performance RPC framework using Protocol Buffers for type-safe serialization. Every RPC uses the universal ContextUnit envelope as both input and output.

Proto File Structure

packages/core/protos/
├── contextunit.proto   # ContextUnit message (shared by all)
├── brain.proto          # BrainService RPCs
├── router.proto         # RouterService RPCs
├── worker.proto         # WorkerService RPCs
├── shield.proto         # ShieldService RPCs
└── admin.proto          # AdminService RPCs (ContextView)

Key Design: Unified Envelope

All RPCs use ContextUnit as both input and output. Domain-specific data goes in the payload field:

rpc QueryMemory(contextcore.ContextUnit) returns (stream contextcore.ContextUnit);

This means every call carries provenance, security scopes, and tracing metadata automatically.

Services at a Glance

Service	Proto	Key RPCs
BrainService	`brain.proto`	Search, Upsert, QueryMemory, GraphSearch, KG, episodic memory, taxonomy, blackboard — 18 RPCs
RouterService	`router.proto`	ExecuteAgent, StreamAgent, RegisterManifest, ToolExecutorStream, ExecuteNode — 8 RPCs
WorkerService	`worker.proto`	StartWorkflow, GetTaskStatus, ExecuteCode, RegisterSchedules — 4 RPCs
ShieldService	`shield.proto`	Scan, EvaluatePolicy, MintToken, secrets management — 12 RPCs
AdminService	`admin.proto`	Health checks, agent management, traces, analytics — 18 RPCs

For the complete RPC definitions, import patterns, and proto compilation instructions, see:

👉 gRPC Contracts Reference

Token Transmission

Authorization tokens are passed via gRPC metadata:

metadata = [("authorization", f"Bearer {token_data}")]
response = stub.QueryMemory(request, metadata=metadata)

Every service has a ServicePermissionInterceptor that extracts, decrypts, and verifies the token’s permissions before the RPC handler runs.

Compiling Protos

After editing any .proto file, regenerate Python stubs:

cd packages/core
./compile_protos.sh