gRPC

How do I connect to the gRPC API?

Start the server with --grpc to enable the gRPC listener, then connect using any gRPC client with the areev.proto service definition. The gRPC API provides the same AI memory operations as the REST API with lower latency for high-throughput workloads.

The Areev context database exposes 32 gRPC service methods covering grain CRUD, compliance, history, CAL queries, metrics, decision provenance, CDC event streaming, and extraction markers. This is the preferred interface for AI agent memory systems that need to perform thousands of operations per second, as gRPC’s binary framing and HTTP/2 multiplexing reduce per-call overhead compared to JSON over REST. The autonomous memory engine handles all 32 RPCs through the areev.v1.AreevService definition.

Use grpcurl for quick testing, or generate client stubs from the proto file at proto/areev/v1/areev.proto with protoc or buf. The server listens on a separate port from the HTTP API, so both protocols can run simultaneously. gRPC must be explicitly enabled with the --grpc flag.

# Start with gRPC on port 50051
areev serve --http 0.0.0.0:4009 --grpc 0.0.0.0:50051

The service is defined in areev.proto under the areev.v1 package:

syntax = "proto3";
package areev.v1;

service AreevService {
  // Core data operations
  rpc Add(AddRequest) returns (AddResponse);
  rpc Get(GetRequest) returns (GetResponse);
  rpc Forget(ForgetRequest) returns (ForgetResponse);
  rpc Recall(RecallRequest) returns (RecallResponse);
  rpc RecallChain(RecallChainRequest) returns (RecallChainResponse);
  rpc Supersede(SupersedeRequest) returns (SupersedeResponse);
  rpc Accumulate(AccumulateRequest) returns (AccumulateResponse);
  rpc Remember(RememberRequest) returns (RememberResponse);

  // Write buffer
  rpc Flush(FlushRequest) returns (FlushResponse);

  // Admin
  rpc Stats(StatsRequest) returns (StatsResponse);
  rpc Health(HealthRequest) returns (HealthResponse);

  // Compliance
  rpc GrantConsent(ConsentRequest) returns (ConsentResponse);
  rpc RevokeConsent(ConsentRequest) returns (ConsentResponse);
  rpc RestrictProcessing(RestrictRequest) returns (RestrictResponse);
  rpc LiftRestriction(LiftRestrictionRequest) returns (LiftRestrictionResponse);
  rpc ForgetUser(ForgetUserRequest) returns (ErasureProofResponse);
  rpc ExportUser(ExportRequest) returns (ExportResponse);
  rpc ExportPortability(ExportRequest) returns (ExportResponse);
  rpc VerifyCompliance(VerifyRequest) returns (VerifyResponse);
  rpc DetectPii(DetectPiiRequest) returns (DetectPiiResponse);
  rpc DetectPiiDetailed(DetectPiiDetailedRequest) returns (DetectPiiDetailedResponse);

  // History + CAL
  rpc GetHistory(GetHistoryRequest) returns (GetHistoryResponse);
  rpc CalQuery(CalQueryRequest) returns (CalQueryResponse);

  // Metrics
  rpc GetMetrics(GetMetricsRequest) returns (GetMetricsResponse);

  // Provenance (EU AI Act Art. 86)
  rpc ListProvenance(ListProvenanceRequest) returns (ListProvenanceResponse);
  rpc GetProvenance(GetProvenanceRequest) returns (GetProvenanceResponse);
  rpc ProvenanceSummary(ProvenanceSummaryRequest) returns (ProvenanceSummaryResponse);

  // CDC Event Streaming (Axtion integration)
  rpc StreamHookEvents(StreamHookEventsRequest) returns (stream HookEventProto);
  rpc GetHookEvents(GetHookEventsRequest) returns (GetHookEventsResponse);

  // Extraction marker management (Axtion integration)
  rpc GetExtractionMarker(GetExtractionMarkerRequest) returns (GetExtractionMarkerResponse);
  rpc UpdateExtractionMarker(UpdateExtractionMarkerRequest) returns (UpdateExtractionMarkerResponse);
  rpc ListExtractionMarkers(ListExtractionMarkersRequest) returns (ListExtractionMarkersResponse);
}

Example using grpcurl:

# Health check
grpcurl -plaintext localhost:50051 areev.v1.AreevService/Health

# Add a grain
grpcurl -plaintext -d '{
  "grain_type": "belief",
  "fields_json": "{\"subject\":\"john\",\"relation\":\"likes\",\"object\":\"coffee\"}"
}' localhost:50051 areev.v1.AreevService/Add

# Recall
grpcurl -plaintext -d '{
  "query": "coffee",
  "limit": 5
}' localhost:50051 areev.v1.AreevService/Recall

What are the core data messages?

The 8 core RPCs (Add, Get, Forget, Recall, RecallChain, Supersede, Accumulate, Remember) handle all grain CRUD operations, with fields passed as JSON-encoded strings in fields_json. The Flush RPC commits the write buffer.

The Add RPC accepts a grain_type, fields_json, and optional AddOptions (extract_event_date, auto_relate, extract_memories, sync), returning the 64-character hex content-address hash. The Get RPC retrieves a grain by hash. The Recall RPC provides the full search capability with 60 filter parameters matching the REST API’s hybrid search (free-text BM25, structural filters, temporal expressions, contradiction detection, scoped memory, exhaustive recall, session census, and more). The RecallChain RPC decomposes a complex question into sub-queries and merges results.

The Supersede RPC creates a new version of a grain, linking it to the original in the version chain. The Accumulate RPC atomically applies numeric deltas to a grain’s fields with tip resolution. The Remember RPC ingests natural language text as memory. The Forget RPC deletes a grain by hash. Both Forget and Supersede respect the sealed policy — if the policy prohibits deletion without a reason or requires consent, the RPC returns an error status. The RecallResponse contains a count and a repeated SearchHit message with grain hash, type, relevance score, fields JSON, source namespace, scope depth, score breakdown, explanation, relative time, conflict status, supersession status, and recall source.

AddRequest / AddResponse — Store a new grain.

message AddRequest {
  string grain_type = 1;  // belief, event, state, workflow, action, etc.
  string fields_json = 2; // e.g. {"subject":"john","relation":"likes","object":"coffee"}
  optional AddOptions options = 3;
}
message AddOptions {
  optional bool extract_event_date = 1;
  optional bool auto_relate = 2;
  optional bool extract_memories = 3;
  optional bool sync = 4;
}
message AddResponse {
  string hash = 1;  // 64-char hex content-address hash
}

GetRequest / GetResponse — Retrieve a grain by hash.

message GetRequest {
  string hash = 1;
}
message GetResponse {
  string hash = 1;
  string grain_type = 2;
  string fields_json = 3;
}

RecallRequest / RecallResponse — Query grains with full filter support. The RecallRequest has 60 fields; the most commonly used are shown below. See areev.proto for the complete definition including deduplication, query expansion, HyDE, exhaustive recall, session census, conflict resolution, and more.

message RecallRequest {
  string query = 1;                        // Free-text search (BM25)
  string subject = 2;                      // Structural filter
  string relation = 3;
  string object = 4;
  string namespace = 5;
  string user_id = 6;
  string grain_type = 7;
  optional int64 time_start = 8;           // Unix timestamp (seconds)
  optional int64 time_end = 9;
  optional double confidence_threshold = 10;
  optional double importance_threshold = 11;
  uint32 limit = 12;
  string temporal_expr = 13;               // "today", "last 7 days", etc.
  repeated string tags = 14;
  repeated string exclude_tags = 15;
  bool detect_contradictions = 16;
  string scope_path = 17;                  // e.g. "acme/prod/bot1"
  bool include_siblings = 18;
  bool deduplicate = 19;                   // Dedup similar (subject, relation, object)
  bool exclude_superseded = 23;            // Exclude superseded grains (default: true)
  bool explanation = 29;                   // Include per-result explanation
  optional double recency_weight = 30;     // Per-query recency weight [0.0–1.0]
  optional string entity = 33;             // Entity-centric recall
  bool query_expansion = 36;              // Rule-based query expansion
  bool hyde = 37;                          // HyDE for vector search
  bool query_decompose = 48;              // Rule-based query decomposition
  bool exhaustive = 53;                    // Exhaustive entity-class recall
  bool session_census = 55;               // Session-census retrieval
  bool aggregation_intent = 59;           // Keep superseded for aggregation
  // ... 60 fields total — see areev.proto for full definition
}

message RecallResponse {
  uint32 count = 1;
  repeated SearchHit results = 2;
  repeated SearchHit sources = 3;          // Source grains (when include_sources=true)
  optional uint32 total_candidates = 4;
  optional string topic_coverage = 5;      // "none", "partial", or "full"
  optional uint32 entity_count = 8;
  repeated string entities = 9;
  optional ExhaustiveMetadata exhaustive_metadata = 10;
  optional SessionCensusMetadata session_census_metadata = 11;
  optional double session_coverage_ratio = 12;
}

message SearchHit {
  string hash = 1;
  string grain_type = 2;
  double score = 3;
  string fields_json = 4;
  string source_namespace = 5;             // Scoped memory source
  uint32 scope_depth = 6;
  optional ScoreBreakdown score_breakdown = 7;
  string explanation = 8;
  optional string relative_time = 9;
  optional string conflict_status = 10;    // "current" or "outdated"
  optional string supersession_status = 11; // "current" or "superseded"
  optional string recall_source = 12;      // "primary", "expansion", or "census"
}

SupersedeRequest / SupersedeResponse — Update a grain (creates a new version).

message SupersedeRequest {
  string old_hash = 1;
  string grain_type = 2;
  string fields_json = 3;
}
message SupersedeResponse {
  string new_hash = 1;
}

ForgetRequest / ForgetResponse — Delete a grain by hash.

message ForgetRequest {
  string hash = 1;
}
message ForgetResponse {}

What compliance RPCs are available?

Ten compliance RPCs provide consent management, crypto-erasure, data export, verification, and PII detection through the gRPC interface.

The consent RPCs (GrantConsent, RevokeConsent) record and revoke per-user, per-purpose consent grains. RestrictProcessing freezes all operations for a user (GDPR Art. 18), and LiftRestriction resumes them. ForgetUser performs crypto-erasure (GDPR Art. 17) by destroying the user’s encryption key, returning an ErasureProofResponse with the user ID, grain count, key fingerprint, and timestamp.

ExportUser and ExportPortability fulfill subject access and data portability requests, returning all grains as a JSON string. VerifyCompliance runs the 87+ automated checks with an optional regulation filter. DetectPii returns category labels, and DetectPiiDetailed returns full match details with byte positions and confidence scores. All PII processing runs locally in-process with no external network calls.

# Grant consent
grpcurl -plaintext -d '{"user_id":"john","purpose":"memory_storage"}' \
  localhost:50051 areev.v1.AreevService/GrantConsent

# Revoke consent
grpcurl -plaintext -d '{"user_id":"john","purpose":"memory_storage"}' \
  localhost:50051 areev.v1.AreevService/RevokeConsent

# Restrict processing (GDPR Art. 18)
grpcurl -plaintext -d '{"user_id":"john","reason":"pending investigation"}' \
  localhost:50051 areev.v1.AreevService/RestrictProcessing

# Lift restriction
grpcurl -plaintext -d '{"user_id":"john"}' \
  localhost:50051 areev.v1.AreevService/LiftRestriction

# Crypto-erasure (GDPR Art. 17) -- returns erasure proof
grpcurl -plaintext -d '{"user_id":"john"}' \
  localhost:50051 areev.v1.AreevService/ForgetUser
# Returns: {user_id, count, key_fingerprint, timestamp}

# Export user data
grpcurl -plaintext -d '{"user_id":"john"}' \
  localhost:50051 areev.v1.AreevService/ExportUser

# Portable export (GDPR Art. 20)
grpcurl -plaintext -d '{"user_id":"john"}' \
  localhost:50051 areev.v1.AreevService/ExportPortability

# Run compliance verification
grpcurl -plaintext -d '{"regulation":"gdpr"}' \
  localhost:50051 areev.v1.AreevService/VerifyCompliance
# Returns: {total, pass, fail, warn, skip, checks[]}

# PII detection (simple labels)
grpcurl -plaintext -d '{"text":"Email john@example.com"}' \
  localhost:50051 areev.v1.AreevService/DetectPii
# Returns: {detections: ["EMAIL"]}

# PII detection (detailed with positions)
grpcurl -plaintext -d '{"text":"Email john@example.com"}' \
  localhost:50051 areev.v1.AreevService/DetectPiiDetailed
# Returns: {matches: [{category, matched_text, start, end, confidence, source}], count}

Compliance message types

What history, CAL, metrics, provenance, and CDC RPCs are available?

Eleven RPCs cover version history (GetHistory), CAL queries (CalQuery), operational metrics (GetMetrics), decision provenance (ListProvenance, GetProvenance, ProvenanceSummary), CDC event streaming (StreamHookEvents, GetHookEvents), and extraction markers (GetExtractionMarker, UpdateExtractionMarker, ListExtractionMarkers).

GetHistory retrieves the version chain for a grain, returning a list of VersionEntry messages with the hash, grain type, fields, creation timestamp, and relation (“original”, “superseded”, or “supersedes”). This supports AI memory auditing by showing how a grain evolved through successive supersede operations.

CalQuery executes a Context Assembly Language query and returns the result as JSON, along with the query hash, statement type, execution time, result count, and any warnings. GetMetrics returns an operational health snapshot for a specified domain (ops, intel, billing, or all), including color-coded metric counts (green/yellow/red) and the full metrics payload as JSON.

GetHistory — Retrieve the version chain for a grain (current or superseded).

grpcurl -plaintext -d '{"hash":"a3f8c1..."}' \
  localhost:50051 areev.v1.AreevService/GetHistory

message GetHistoryResponse {
  repeated VersionEntry versions = 1;
}
message VersionEntry {
  string hash = 1;
  string grain_type = 2;
  string fields_json = 3;
  int64 created_at = 4;        // Unix timestamp
  string relation = 5;          // "original", "superseded", or "supersedes"
}

CalQuery — Execute a CAL (Context Assembly Language) query.

grpcurl -plaintext -d '{
  "query": "RECALL beliefs WHERE subject = \"john\" LIMIT 10"
}' localhost:50051 areev.v1.AreevService/CalQuery

message CalQueryResponse {
  string query = 1;            // Query as supplied
  string query_hash = 2;       // SHA-256 of trimmed query
  string result_json = 3;      // Result payload as JSON
  repeated string warnings = 4;
  string statement_type = 5;   // "recall", "exists", etc.
  uint64 execution_time_ms = 6;
  uint64 result_count = 7;
}

GetMetrics — Get operational health, intelligence, and billing metrics.

grpcurl -plaintext -d '{"domain":"ops"}' \
  localhost:50051 areev.v1.AreevService/GetMetrics

message GetMetricsResponse {
  uint64 computed_at = 1;      // Unix timestamp
  string domain = 2;           // "ops", "intel", "billing", "all"
  string metrics_json = 3;     // Full metrics snapshot as JSON
  uint32 total = 4;            // Total metric count
  uint32 green = 5;            // Healthy metrics
  uint32 yellow = 6;           // Warning metrics
  uint32 red = 7;              // Critical metrics
  uint32 not_computed = 8;
}

All 32 RPCs at a glance

Related

• HTTP REST — JSON-based REST alternative
• SDKs — Python, TypeScript, and Rust clients
• CLI — enable gRPC with areev serve --grpc 0.0.0.0:50051