Protobuf Schema

Overview

The HEBBS gRPC API is defined in hebbs.proto. The schema defines services, messages, and RPC methods. Use this reference when generating client stubs or implementing custom integrations.

Services

Service	Description
MemoryService	Write and read operations: Remember, Recall, Revise, Forget, Prime.
SubscribeService	Bidirectional streaming for real-time memory push.
ReflectService	Reflection pipeline: Reflect, GetInsights, policy configuration, contradiction review.
HealthService	Liveness, readiness, and metrics.

Schema Location

The canonical schema file is hebbs.proto in the HEBBS repository (hebbs/proto/ or equivalent). Regenerate clients with:

protoc --go_out=. --go-grpc_out=. hebbs.proto
# or equivalent for your language

Full Schema Listing

Tenant Scoping

Every request message includes an optional tenant_id field. In authenticated deployments, the server’s TenantInterceptor validates that the request’s tenant_id (if provided) matches the API key’s bound tenant. The field structure is:

message RememberRequest {
  string content = 1;
  optional float importance = 2;
  google.protobuf.Struct context = 3;
  optional string entity_id = 4;
  repeated Edge edges = 5;
  optional string tenant_id = 6;  // tenant isolation boundary
}

The same tenant_id field appears in GetRequest, RecallRequest, PrimeRequest, ReviseRequest, ForgetRequest, SubscribeRequest, FeedRequest, CloseSubscriptionRequest, ReflectRequest, and GetInsightsRequest.

(Placeholder: Full schema listing will be generated from hebbs.proto or linked to the source file. Key message types include: Memory, RememberRequest, RememberResponse, RecallRequest, RecallResponse, ReviseRequest, ForgetRequest, ForgetResponse, PrimeRequest, PrimeResponse, SubscribeRequest, SubscribePush, ReflectRequest, ReflectResponse, GetInsightsRequest, GetInsightsResponse, ReflectPrepareRequest, ReflectPrepareResponse, ReflectCommitRequest, ReflectCommitResponse, ClusterPrompt, ProducedInsightInput, and health-related messages.)

Agent-Driven Reflect RPCs (Deprecated)

Deprecated

The two-step prepare/commit RPCs below are deprecated. HEBBS now handles reflection and contradiction resolution autonomously using its built-in LLM integration. These RPCs are retained for backward compatibility but will be removed in a future release. Use Reflect for manual triggers instead.

The ReflectService includes additional RPCs that were previously used for agent-driven two-step reflection:

service ReflectService {
  rpc Reflect(ReflectRequest) returns (ReflectResponse);
  rpc GetInsights(GetInsightsRequest) returns (GetInsightsResponse);
  // Deprecated: HEBBS now handles reflection internally.
  rpc ReflectPrepare(ReflectPrepareRequest) returns (ReflectPrepareResponse);
  rpc ReflectCommit(ReflectCommitRequest) returns (ReflectCommitResponse);
  // Deprecated: HEBBS now handles contradiction resolution internally.
  rpc ContradictionPrepare(ContradictionPrepareRequest) returns (ContradictionPrepareResponse);
  rpc ContradictionCommit(ContradictionCommitRequest) returns (ContradictionCommitResponse);
}

ReflectPrepare (Deprecated)

Gathers memories, clusters them, and builds LLM prompts without calling any LLM.

message ReflectPrepareRequest {
  ReflectScope scope = 1;
  optional string tenant_id = 2;
}

message ClusterMemorySummary {
  string memory_id = 1;
  string content = 2;
  float importance = 3;
  optional string entity_id = 4;
  uint64 created_at = 5;
}

message ClusterPrompt {
  uint32 cluster_id = 1;
  uint32 member_count = 2;
  string proposal_system_prompt = 3;
  string proposal_user_prompt = 4;
  repeated string memory_ids = 5;
  string validation_context = 6;
  repeated ClusterMemorySummary memories = 7;
}

message ReflectPrepareResponse {
  string session_id = 1;
  uint64 memories_processed = 2;
  repeated ClusterPrompt clusters = 3;
  uint64 existing_insight_count = 4;
}

ReflectCommit (Deprecated)

Stores agent-produced insights from a previous ReflectPrepare call. No LLM is called.

message ProducedInsightInput {
  string content = 1;
  float confidence = 2;
  repeated string source_memory_ids = 3;
  repeated string tags = 4;
  optional uint32 cluster_id = 5;
}

message ReflectCommitRequest {
  string session_id = 1;
  repeated ProducedInsightInput insights = 2;
  optional string tenant_id = 3;
}

message ReflectCommitResponse {
  uint64 insights_created = 1;
}

Sessions are ephemeral (10-minute TTL). Source memory IDs in ProducedInsightInput must be a subset of the IDs returned in the corresponding ReflectPrepareResponse cluster.

ContradictionPrepare (Deprecated)

Retrieve pending contradiction candidates. In the previous architecture, these were flagged by a heuristic classifier and required external agent review. HEBBS now resolves contradictions autonomously using its built-in LLM.

message ContradictionPrepareRequest {
  optional string tenant_id = 1;
}

message PendingContradictionProto {
  string pending_id = 1;
  string memory_id_a = 2;
  string memory_id_b = 3;
  string content_a_snippet = 4;
  string content_b_snippet = 5;
  float classifier_score = 6;
  string classifier_method = 7;
  float similarity = 8;
  uint64 created_at = 9;
}

message ContradictionPrepareResponse {
  repeated PendingContradictionProto candidates = 1;
}

ContradictionCommit (Deprecated)

Commit agent-reviewed verdicts for pending contradiction candidates.

message ContradictionVerdictInput {
  string pending_id = 1;
  string verdict = 2;       // "contradiction", "revision", or "dismiss"
  float confidence = 3;
  optional string reasoning = 4;
}

message ContradictionCommitRequest {
  repeated ContradictionVerdictInput verdicts = 1;
  optional string tenant_id = 2;
}

message ContradictionCommitResponse {
  uint64 contradictions_confirmed = 1;
  uint64 revisions_created = 2;
  uint64 dismissed = 3;
}

Verdict "contradiction" creates bidirectional CONTRADICTS edges. Verdict "revision" creates a REVISED_FROM edge. Verdict "dismiss" removes the candidate without creating edges.