Protocols & Interfaces

MuninnDB starts four listeners on launch. Each serves a different use case and client type.

MBP

:8474

Binary TCP

fastest

REST

:8475

HTTP/JSON

easy

gRPC

:8477

Protobuf RPC

standard

MCP

:8750

AI agent tools

agents

MBP — Muninn Binary Protocol

MBP is MuninnDB's native binary protocol over TCP. It uses length-prefixed frames with msgpack serialization and supports pipelining — send multiple requests without waiting for responses. Use MBP for production AI agents where latency matters.

Note: MBP is a raw binary protocol intended for native integrations that need maximum throughput. The Go SDK connects via REST (port 8475) and has full feature parity. For most applications, use the Go or Python SDK — they're simpler and don't require implementing the MBP framing protocol.

REST API

The REST API is available at port 8475 and accepts JSON. It's great for quick integration, scripting, and testing. All endpoints follow a consistent resource model.

bash — curl examples

# Store an engram
curl -X POST http://localhost:8475/api/engrams \
  -H "Authorization: Bearer mk_xK9m..." \
  -H "Content-Type: application/json" \
  -d '{"concept": "api key rotated", "content": "...", "tags": ["security"]}'

# Activate — cognitive retrieval
curl -X POST http://localhost:8475/api/activate \
  -H "Authorization: Bearer mk_xK9m..." \
  -H "Content-Type: application/json" \
  -d '{"context": "what security events happened?", "limit": 5}'

Full REST API reference: REST API Reference →

gRPC

gRPC on port 8477 uses Protobuf for serialization. Good for teams who standardize on gRPC, or when building clients in languages other than Go. The proto definitions are in the repo at proto/muninn.proto.

MCP — Model Context Protocol

MCP (Model Context Protocol) is a standard that lets AI agents like Claude and Cursor connect to external tools. MuninnDB ships with a built-in MCP server on port 8750 — no separate process needed. Run muninn init to auto-configure your AI tools, or add the endpoint manually. 19 MCP tools — full parameter reference: MCP Tools Reference →

Tool	Description
muninn_remember	Store a new memory engram
muninn_remember_batch	Store up to 50 memories in one call (bulk insert)
muninn_guide	Get vault-aware usage instructions (call on first connect)
muninn_recall	Cognitive retrieval — full 6-phase pipeline
muninn_read	Point read by engram ID
muninn_forget	Soft-delete an engram (restorable for 7 days)
muninn_link	Create a typed, weighted association between engrams
muninn_traverse	Graph traversal from a starting engram
muninn_contradictions	Check vault for known contradictions
muninn_evolve	Update memory with versioned history
muninn_state	Transition engram lifecycle state
muninn_decide	Record a decision with rationale and evidence links
muninn_consolidate	Merge multiple engrams into one
muninn_restore	Recover a soft-deleted engram
muninn_explain	Score breakdown for an engram against a query
muninn_session	Recent activity summary since a given time
muninn_status	Vault statistics and health
muninn_list_deleted	List soft-deleted engrams within restore window
muninn_retry_enrich	Re-queue engram for plugin processing

Full parameter reference: MCP Tools Reference →

claude_desktop_config.json — Add MuninnDB MCP server

{"mcpServers": {
  "muninndb": {
    "type": "http",
    "url": "http://localhost:8750/mcp",
    "headers": {
      "Authorization": "Bearer mk_xK9m..."
    }
  }
}