MuninnDB

gRPC Reference

MuninnDB exposes a gRPC interface on port 8477. The service supports both unary and server-streaming RPCs. Proto definitions live in proto/muninn/v1/ in the repository.

When to use gRPC: gRPC is ideal for polyglot teams or organizations already standardizing on Protobuf infrastructure. For Go applications, the Go SDK (REST on port 8475) is simpler and has full feature parity. For real-time streaming at scale, gRPC's bidirectional Subscribe is particularly efficient.

Service Definition

proto/muninn/v1/service.proto (abbreviated) 
syntax = "proto3";
package muninn.v1;

service MuninnDB {
  // Unary
  rpc Hello(HelloRequest)   returns (HelloResponse);
  rpc Write(WriteRequest)   returns (WriteResponse);
  rpc Read(ReadRequest)     returns (ReadResponse);
  rpc Forget(ForgetRequest) returns (ForgetResponse);
  rpc Stat(StatRequest)     returns (StatResponse);
  rpc Link(LinkRequest)     returns (LinkResponse);

  // Server-streaming
  rpc Activate(ActivateRequest) returns (stream ActivateResponse);

  // Bidirectional streaming
  rpc Subscribe(stream SubscribeRequest) returns (stream ActivationPush);
}

RPC Methods

Hello
Unary

Auth handshake. Validates the connection and returns server version info.

Write
Unary

Store a new engram. Accepts vault, concept, content, tags, and confidence. Returns the engram ULID.

Read
Unary

Fetch a single engram by ULID. Returns the full record including temporal priority data (access count, last access), Hebbian score, and associations.

Forget
Unary

Soft-delete an engram. Archives it — excluded from activation but restorable for 7 days.

Stat
Unary

Vault statistics: engram count, storage bytes, coherence scores per vault.

Link
Unary

Create a typed association between two engrams. Supports all 15 built-in relation types (supports, contradicts, depends_on, is_part_of, causes, etc.) plus user-defined types.

Activate
Server-streaming

Cognitive retrieval. Results are streamed back as they are scored — useful for large result sets or early termination. Runs the full 6-phase pipeline.

Subscribe
Bidirectional streaming

Real-time push stream. Send SubscribeRequest frames to update your watch context; receive ActivationPush frames when relevant memories are activated above the threshold.

Server configuration:

  • Keepalive ping interval: 10 seconds
  • Keepalive timeout: 5 seconds
  • Max connection idle: 5 minutes
  • Max connection age: 30 minutes

Generate a Client

Grab the proto file from the repo and generate a client for your language:

bash — Python client 
pip install grpcio grpcio-tools

python -m grpc_tools.protoc \
  -I proto/muninn/v1 \
  --python_out=. \
  --grpc_python_out=. \
  proto/muninn/v1/service.proto
bash — Go (already generated, available in repo) 
protoc --go_out=. --go-grpc_out=. \
  proto/muninn/v1/service.proto

For the full proto file, see proto/ on GitHub →

← Previous Next →