gRPC API overview

Membrane exposes a gRPC service backed by protoc-generated stubs. Public API envelopes are typed protobuf messages; arbitrary content fields use google.protobuf.Value, and memory records, graph nodes, graph edges, capture responses, and retrieval responses are first-class messages.

Connection details

Property	Value
Default address	localhost:9090
Protocol	gRPC (HTTP/2)
Payload encoding	Typed protobuf messages; google.protobuf.Value for arbitrary content
TLS	Optional — set tls_cert_file and tls_key_file in config
Authentication	Bearer token via authorization metadata header
Rate limiting	Token bucket; configurable via rate_limit_per_second

Authentication

When api_key is configured, every RPC must include an authorization metadata header with the value Bearer <your-key>.

grpcurl \
  -H 'authorization: Bearer your-key' \
  -d '{"task_descriptor": "fix build error", "trust": {"max_sensitivity": "medium", "authenticated": true}, "memory_types": ["entity", "semantic", "competence"], "root_limit": 10}' \
  -plaintext \
  localhost:9090 \
  membrane.v1.MembraneService/RetrieveGraph

Note

If no api_key is set in configuration, authentication is disabled and the authorization header is ignored.

TLS

Enable TLS by providing certificate and key paths in your configuration file:

tls_cert_file: "/path/to/server.crt"
tls_key_file: "/path/to/server.key"

When TLS is enabled, use -insecure instead of -plaintext with grpcurl, or supply the CA certificate with --cacert.

All methods

Method	Category	Description
CaptureMemory	Ingestion	Capture a rich memory candidate and any linked entity/semantic records
RetrieveGraph	Retrieval	Retrieve ranked root memories plus a bounded graph neighborhood
RetrieveByID	Retrieval	Fetch a single record by ID
Supersede	Revision	Atomically replace a record with a new version
Fork	Revision	Create a conditional variant of an existing record
Retract	Revision	Mark a record as retracted (salience → 0, audit trail preserved)
Merge	Revision	Combine multiple records into one consolidated record
Contest	Revision	Mark a record as contested by conflicting evidence
Reinforce	Salience	Boost a record's salience
Penalize	Salience	Reduce a record's salience by a specified amount
GetMetrics	Observability	Retrieve a point-in-time metrics snapshot

Connecting with TypeScript

Install the official TypeScript client:

npm install @bennettschwartz/membrane

import { MembraneClient, Sensitivity } from "@bennettschwartz/membrane";

const client = new MembraneClient("localhost:9090", { apiKey: "your-key" });

// Capture a memory candidate
const capture = await client.captureMemory({
  ref: "task#1",
  text: "Refactored auth middleware and verified package tests",
}, {
  sourceKind: "event",
  summary: "Refactored auth middleware",
  tags: ["auth", "tests"],
});

// Retrieve with trust context
const graph = await client.retrieveGraph("auth debugging", {
  trust: {
    max_sensitivity: Sensitivity.MEDIUM,
    authenticated: true,
    actor_id: "ts-agent",
    scopes: [],
  },
  memoryTypes: ["entity", "semantic", "competence"],
});

client.close();

Connecting with Python

Install the Python client:

pip install -e clients/python

from membrane import MembraneClient, Sensitivity, TrustContext

client = MembraneClient("localhost:9090", api_key="your-key")

# Capture a memory candidate
capture = client.capture_memory(
    {"ref": "task#1", "text": "Refactored auth middleware and verified package tests"},
    source_kind="event",
    summary="Refactored auth middleware",
    tags=["auth", "tests"],
)

# Retrieve with trust context
graph = client.retrieve_graph(
    task_descriptor="auth debugging",
    trust=TrustContext(max_sensitivity=Sensitivity.MEDIUM, authenticated=True),
    memory_types=["entity", "semantic", "competence"],
)

Connecting with grpcurl

List available methods:

grpcurl -plaintext localhost:9090 list membrane.v1.MembraneService

Call CaptureMemory:

grpcurl \
  -H 'authorization: Bearer your-key' \
  -d '{
    "source": "build-agent",
    "source_kind": "event",
    "content": {
      "ref": "build#42",
      "text": "Executed go build, failed with linker error"
    },
    "summary": "Executed go build, failed with linker error",
    "tags": ["build", "error"]
  }' \
  -plaintext \
  localhost:9090 \
  membrane.v1.MembraneService/CaptureMemory

Call GetMetrics:

grpcurl \
  -H 'authorization: Bearer your-key' \
  -d '{}' \
  -plaintext \
  localhost:9090 \
  membrane.v1.MembraneService/GetMetrics

Proto definition

The full service definition is at api/proto/membrane/v1/membrane.proto. The Go package is github.com/BennettSchwartz/membrane/api/grpc/gen/membranev1.

syntax = "proto3";

package membrane.v1;

service MembraneService {
    rpc CaptureMemory(CaptureMemoryRequest) returns (CaptureMemoryResponse);
    rpc RetrieveGraph(RetrieveGraphRequest) returns (RetrieveGraphResponse);
    rpc RetrieveByID(RetrieveByIDRequest) returns (MemoryRecordResponse);
    rpc Supersede(SupersedeRequest) returns (MemoryRecordResponse);
    rpc Fork(ForkRequest) returns (MemoryRecordResponse);
    rpc Retract(RetractRequest) returns (RetractResponse);
    rpc Merge(MergeRequest) returns (MemoryRecordResponse);
    rpc Contest(ContestRequest) returns (ContestResponse);
    rpc Reinforce(ReinforceRequest) returns (ReinforceResponse);
    rpc Penalize(PenalizeRequest) returns (PenalizeResponse);
    rpc GetMetrics(GetMetricsRequest) returns (MetricsResponse);
}