Skip to content

Interfaces and Protocols

Jump to bottom
Pedro Gomes Branquinho edited this page Feb 15, 2026 · 1 revision

Interfaces & Protocols

Protocol-driven architecture: hive-mcp defines all system boundaries as Clojure defprotocol interfaces. Implementations live in separate packages, enabling the Open Protocols / Closed Implementations pattern.

Total protocols: ~49 | Core (protocols/ dir): 20 | Domain: ~29

Table of Contents

Core Protocols

All core protocols live in src/hive_mcp/protocols/ and follow Interface Segregation (SOLID-I).

Knowledge Graph (KG)

src/hive_mcp/protocols/kg.clj | License: AGPL-3.0

Abstracts Datalog store backends for the Knowledge Graph.

IKGStore

Core graph operations for KG storage backends.

Method Signature Description
ensure-conn! [this] Initialize connection (idempotent, thread-safe)
transact! [this tx-data] Transact data, returns {:db-before :db-after :tx-data}
query [this q] [this q inputs] Execute Datalog query, returns set of tuples
entity [this eid] Get entity by ID, returns map or nil
entid [this lookup-ref] Resolve lookup ref (e.g. [:kg-edge/id "x"]) to entity ID
pull-entity [this pattern eid] Pull entity with pattern (e.g. '[*]')
db-snapshot [this] Get immutable DB value for querying
reset-conn! [this] Reset to fresh/empty database
close! [this] Close connection, release resources

Implementations: DataScriptStore (in-memory, default), DatalevinStore (persistent/LMDB), DatahikeStore (temporal)

Noop: NoopKGStore - writes silently dropped, queries return #{}, lookups return nil

ITemporalKGStore

Optional extension for time-travel queries (Datahike only).

Method Signature Description
history-db [this] DB with all historical facts (including retracted)
as-of-db [this tx-or-time] DB snapshot at a specific point in time
since-db [this tx-or-time] DB with facts added since a point in time

Memory

src/hive_mcp/protocols/memory.clj | License: AGPL-3.0

Abstracts memory storage for persistent knowledge entries.

IMemoryStore

Core CRUD + semantic search for memory entries.

Method Signature Description
connect! [this config] Initialize backend connection, returns {:success? :backend :errors}
disconnect! [this] Close connection, release resources
connected? [this] Lightweight state check (boolean)
health-check [this] Active verification, returns {:healthy? :latency-ms :entry-count}
add-entry! [this entry] Add memory entry, returns entry ID
get-entry [this id] Get entry by ID, returns map or nil
update-entry! [this id updates] Partial update, auto-updates :updated timestamp
delete-entry! [this id] Delete entry, returns boolean
query-entries [this opts] Query with :type, :tags, :project-id, :duration filters
search-similar [this query-text opts] Semantic similarity search (vector-based)
supports-semantic-search? [this] Check if backend supports vector search
cleanup-expired! [this] Delete expired entries, returns {:count :deleted-ids}
entries-expiring-soon [this days opts] Entries expiring within N days
find-duplicate [this type content-hash opts] SHA-256 dedup detection
store-status [this] Backend status and config info
reset-store! [this] Reset to empty (destructive)

Entry shape: {:id :type :content :tags :duration :project-id :created :updated :content-hash :abstraction-level :staleness-alpha :staleness-beta ...}

Implementations: ChromaStore (vector DB, production), DataScriptStore (in-memory, testing), AtomStore (minimal)

IMemoryStoreWithAnalytics

Optional extension for usage tracking.

Method Signature Description
log-access! [this id] Increment :access-count for entry
record-feedback! [this id feedback] Record :helpful or :unhelpful feedback
get-helpfulness-ratio [this id] Calculate helpfulness ratio (0.0-1.0)

IMemoryStoreWithStaleness

Optional extension for Bayesian freshness tracking.

Method Signature Description
update-staleness! [this id staleness-opts] Update Bayesian Alpha/Beta parameters
get-stale-entries [this threshold opts] Entries above staleness probability threshold
propagate-staleness! [this source-id depth] Transitive staleness propagation

Workflow

src/hive_mcp/protocols/workflow.clj | License: AGPL-3.0 | 🆕 NEW in 0.12.0

Workflow engine protocol for multi-step process execution. Backed by hive.events.fsm (EDN-defined FSM workflow specs compiled via SCI).

IWorkflowEngine

Method Signature Description
load-workflow [this workflow-name opts] Load workflow def by name, returns {:workflow-id :steps :loaded?}
validate-workflow [this workflow] Validate DAG (no cycles), returns {:valid? :dependency-order}
execute-step [this workflow step-id opts] Execute single step, returns {:success? :result :context}
execute-workflow [this workflow opts] Execute all steps in topological order
get-status [this workflow-id] Query execution status (:pending :running :completed :failed :cancelled)
cancel-workflow [this workflow-id opts] Cancel with optional cleanup hooks

Implementations: FSMWorkflowEngine (EDN specs + SCI compilation), NoopWorkflowEngine (fallback)

IWorkflowPersistence

Optional extension for durable workflow state.

Method Signature Description
save-state [this workflow-id state] Persist execution state
load-state [this workflow-id] Load persisted state
list-workflows [this opts] List workflow executions

Channel

src/hive_mcp/protocols/channel.clj | License: AGPL-3.0

Messaging abstractions for agent coordination and event distribution.

IChannel

Core pub/sub messaging (14 methods).

Method Signature Description
channel-id [this] Unique identifier for this channel
channel-info [this] Metadata including :type, :capabilities
send! [this topic payload] [this topic payload opts] Send message to topic
send-async! [this topic payload opts] Fire-and-forget send
broadcast! [this payload opts] Send to all subscribers
receive! [this topic] [this topic opts] Blocking receive
receive-batch! [this topic opts] Batch receive
subscribe! [this topic handler] [this topic handler opts] Subscribe with handler (wildcards supported)
unsubscribe! [this subscription-id] Remove subscription
subscriptions [this] List active subscriptions
open? [this] Check if channel is operational
close! [this] Close channel, release resources
drain! [this opts] Graceful drain before close
channel-status [this] Comprehensive status + metrics

Implementations: AsyncChannel (core.async), RedisChannel, MqttChannel, WebSocketChannel, NoopChannel

IChannelWithAck

Optional: reliable delivery with acknowledgment.

Method Signature Description
ack! [this message-id] Acknowledge message processing
nack! [this message-id opts] Negative ack with optional requeue
pending-acks [this] Messages awaiting acknowledgment

IChannelWithReplay

Optional: message replay for event sourcing.

Method Signature Description
replay! [this topic opts] Replay historical messages with handler
history [this topic opts] Query message history without handlers

IVoice

Voice/call communication for agent coordination.

Method Signature Description
voice-id [this] Unique voice instance identifier
start-call [this participants opts] Initiate voice call
end-call [this call-id] End active call
mute [this call-id] Mute local audio
unmute [this call-id] Unmute local audio
call-status [this call-id] Query call status

Implementations: WebRTCVoice, SIPVoice, NoopVoice

IRouter

Message routing dispatch layer above individual channels.

Method Signature Description
router-id [this] Unique router identifier
router-info [this] Router metadata + strategy
route-message [this topic payload opts] Route to appropriate channel(s)
register-route! [this channel-id channel opts] Register channel with topic patterns
unregister-route! [this channel-id] Remove channel from router
router-channels [this] List registered channels
resolve-route [this topic] Preview routing without sending

Implementations: TopicRouter, RoundRobinRouter, PriorityRouter, NoopRouter

Agent Bridge

src/hive_mcp/protocols/agent_bridge.clj | License: AGPL-3.0 | 🆕 NEW in 0.12.0

Backend-agnostic abstractions for programmatic agent interaction. Enables hive-mcp to control external agent SDKs (Claude Agent SDK, OpenAI, etc.) through a unified interface.

IAgentSession

Session interaction cycle (query/interrupt/stream).

Method Signature Description
session-id [this] Unique session identifier
query! [this prompt opts] Send prompt, returns core.async channel of responses
interrupt! [this] Interrupt current query
receive-messages [this] core.async channel of streaming messages
receive-response [this] core.async channel yielding final response

IAgentBackend

Backend lifecycle management.

Method Signature Description
backend-id [this] Keyword identifier (:noop, :claude-sdk, :openai-sdk)
available? [this] Check if backend is ready
capabilities [this] Set of capabilities (:streaming, :tools, :sessions, :saa, etc.)
execute! [this task opts] One-shot task execution
connect! [this opts] Create and return IAgentSession
disconnect! [this session] Clean up session

External implementations: ClaudeSDKBackend (libpython-clj + Claude Agent SDK)

IAgentTools

Custom tool registration.

Method Signature Description
register-tool! [this session tool-spec] Register Clojure fn as agent tool
register-mcp-server! [this session server-config] Register MCP server with session
list-tools [this session] List available tools

IAgentPermissions

Permission control.

Method Signature Description
set-permission-mode! [this session mode] Set mode (:default, :accept-edits, :bypass)
set-permission-handler! [this session handler-fn] Custom per-tool permission handler

ISAAOrchestrator

SAA (Silence-Abstract-Act) three-phase orchestration.

Method Signature Description
run-silence! [this session task opts] Phase 1: observe with read-only tools
run-abstract! [this session observations opts] Phase 2: synthesize observations into plan
run-act! [this session plan opts] Phase 3: execute plan with full tool access
run-full-saa! [this session task opts] Complete SAA cycle

Noop: NoopAgentBackend implements IAgentBackend + IAgentTools + IAgentPermissions + ISAAOrchestrator

Connectors

src/hive_mcp/protocols/connector.clj | License: AGPL-3.0

External system integration abstractions.

IConnector

Connection lifecycle for APIs, brokers, IoT, webhooks.

Method Signature Description
connector-id [this] Unique keyword identifier
connector-info [this] Metadata + :system-type + :capabilities
connect! [this opts] Establish connection with credentials/endpoint
disconnect! [this] Close connection
connected? [this] Lightweight state check
health-check [this] Active health verification
reconnect! [this opts] Re-establish lost connection
get-status [this] Comprehensive status + metrics
send [this data opts] Send data to external system
receive [this opts] Pull data from external system
sync! [this opts] Bidirectional synchronization

Noop: NoopConnector

IDataMapper

Bidirectional data transformation (external <-> hive internal).

Method Signature Description
mapper-id [this] Unique keyword identifier
mapper-info [this] Metadata + :source-type + :target-type
inbound [this external-data opts] External -> hive-mcp format
outbound [this internal-data opts] Hive-mcp -> external format
validate-inbound [this external-data] Lightweight validation pre-transform
supported-formats [this] Set of supported formats

Default: IdentityMapper (passthrough, auto-registered)

IAuthProvider

Token-based authentication lifecycle.

Method Signature Description
authenticate [this credentials] Obtain token from credentials
refresh-token [this token] Renew expired token
valid? [this token] Check token validity

Noop: NoopAuthProvider (always succeeds, mock tokens)

Automation

src/hive_mcp/protocols/automation.clj | License: AGPL-3.0

Browser automation and web scraping abstractions.

IAutomationSession

Session identity and lifecycle.

Method Signature Description
session-id [this] Unique session identifier
session-info [this] Metadata (browser, headless?, viewport)
active? [this] Check if session is usable

IBrowserAutomation

Core browser control operations.

Method Signature Description
launch! [this opts] Launch browser, create session
close! [this] Close browser, release resources
navigate! [this url opts] Navigate to URL
click! [this selector opts] Click element by CSS/XPath selector
type-text! [this selector text opts] Type into input element
screenshot! [this opts] Capture page screenshot
get-page-source [this] Get page HTML source
wait-for-selector [this selector opts] Wait for element to appear
evaluate-js [this expression opts] Execute JavaScript in browser context

Future implementations: PlaywrightAutomation, PuppeteerAutomation

Noop: NoopBrowserAutomation, NoopAutomationSession

Dispatch

src/hive_mcp/protocols/dispatch.clj | License: AGPL-3.0

Polymorphic dispatch context for agent communication.

IDispatchContext

Method Signature Description
resolve-context [this] Returns consumable map {:prompt <string>} + optional :refs, :kg-nodes
context-type [this] Returns :text, :ref, or :graph-ref

Records:

Record Type Description
TextContext :text Plain text prompt (backward compatible)
RefContext :ref Pass-by-reference context (~25x smaller than text)
GraphContext :graph-ref Graph-native traversal (degrades to TextContext if backend unavailable)

Factory functions: ->text-context, ->ref-context, ->graph-context, ensure-context

Domain Protocols

Protocols outside protocols/ dir, co-located with their domain modules.

Agent Lifecycle

src/hive_mcp/agent/protocol.clj | License: AGPL-3.0

IAgent

Core agent lifecycle (10 methods).

Method Signature Description
spawn! [this opts] Spawn agent instance
dispatch! [this task opts] Send task to agent
kill! [this opts] Terminate agent
status [this] Get agent status
agent-type [this] Return type keyword (:ling, :drone)
can-chain-tools? [this] Whether agent supports tool chaining
claims [this] Get file ownership claims
claim-files! [this files] Claim file ownership
release-claims! [this] Release all file claims
upgrade! [this new-opts] Upgrade agent configuration

IAgentRegistry

Agent registry operations.

Method Signature Description
register! [this agent] Register agent
unregister! [this agent-id] Unregister agent
get-agent [this agent-id] Get agent by ID
list-agents [this] List all agents
list-agents-by-type [this type] Filter agents by type

LLMBackend

LLM model abstraction.

Method Signature Description
chat [this messages opts] Send chat messages
model-name [this] Return model identifier

Ling Strategy

src/hive_mcp/agent/ling/strategy.clj | License: AGPL-3.0 | 🆕 NEW in 0.12.0

Strategy pattern for mode-specific ling spawn/dispatch operations. The Ling record delegates mode-specific calls to its strategy, keeping mode-independent operations (claims, agent-type) on the record itself.

ILingStrategy

Method Signature Description
strategy-spawn! [this ling-ctx opts] Spawn using strategy's mechanism
strategy-dispatch! [this ling-ctx task-opts] Dispatch task to running ling
strategy-status [this ling-ctx ds-status] Get mode-specific status
strategy-kill! [this ling-ctx] Terminate via strategy's mechanism

Implementations: VtermStrategy (Emacs buffer), HeadlessStrategy (ProcessBuilder subprocess), AgentSDKStrategy (Claude Agent SDK)

Agora (Coordination)

src/hive_mcp/agora/protocol.clj | License: AGPL-3.0

Multi-agent dialogue and consensus protocols.

ICoordination

Method Signature Description
add-participant [this participant] Add agent to dialogue
remove-participant [this participant-id] Remove agent
get-participants [this] List participants
signal [this participant-id signal] Send coordination signal
check-consensus [this] Check Nash equilibrium
next-turn [this] Get next turn
get-turns [this] Get turn history
get-id [this] Dialogue identifier

Implementations: DialogueCoordination, DebateCoordination

ISignalable

Method Signature Description
emit [this event] Emit event
subscribe [this handler] Subscribe to events

IConsensus

Method Signature Description
threshold [this] Get consensus threshold
evaluate [this signals] Evaluate if consensus reached

IDebateExtension

Method Signature Description
get-methodology [this] Get debate methodology
get-turn-order [this] Get structured turn order

Swarm Registry

src/hive_mcp/swarm/protocol.clj | License: AGPL-3.0

ISwarmRegistry

DataScript-backed swarm state management.

Method Signature Description
add-slave! [this slave-data] Register agent
get-slave [this slave-id] Get agent record
update-slave! [this slave-id updates] Update agent state
remove-slave! [this slave-id] Unregister agent
get-all-slaves [this] List all agents
get-slaves-by-status [this status] Filter by status
get-slaves-by-project [this project-id] Filter by project
add-task! [this task-data] Add task record
get-task [this task-id] Get task record
update-task! [this task-id updates] Update task state
get-tasks-for-slave [this slave-id] Get agent's tasks

Graph Store

src/hive_mcp/graph/protocol.clj | License: AGPL-3.0

GraphStore

Legacy KG interface (predates IKGStore).

Method Signature Description
transact! [this tx-data] Transact data
query [this q] [this q inputs] Execute query
entity [this eid] Get entity
find-similar [this entry opts] Similarity search
history [this entry-id] Entry history
persist! [this path] Persist to file
restore! [this path] Restore from file

Infrastructure

Additional protocols scattered across the codebase:

Protocol File Methods Purpose
EmbeddingProvider chroma.clj embed-text, embed-batch, embedding-dimension Vector embedding generation
ITransport transport.clj connect!, disconnect!, connected?, send!, recv!, get-stream Low-level transport
IServer transport.clj stop-server!, server-running?, get-clients Server management
IAddon addons/core.clj addon-name, addon-version, addon-info, init!, shutdown!, addon-tools, addon-capabilities Plugin system
ITDDParticipant tdd/protocol.clj participant-id, participant-type, execute-task!, get-preset TDD workflow roles
IAdapter migration/adapter.clj adapter-id, adapter-info, export-transform, import-transform, validate-external Migration adapters
CircuitBreaker resilience.clj — Resilience pattern
IEmacsDaemon emacs/daemon.clj — Multi-daemon management
IDebateParticipant agora/debate.clj — Debate role participant
PromptStore prompt/storage.clj — Prompt template storage
ReplEvaluator evaluator.clj — REPL evaluation abstraction
DiagramAdapter diagrams/core.clj — Diagram rendering
KanbanRenderer org_clj/render.clj — Kanban → Org-mode rendering

New in 0.12.0

Release 0.12.0 introduces several new protocols and implementations:

New Protocols

Protocol Domain Purpose
IWorkflowEngine Workflow Multi-step workflow execution with FSM backing
IWorkflowPersistence Workflow Durable workflow state for resume/audit
IAgentSession Agent Bridge Streaming agent session interaction
IAgentBackend Agent Bridge Backend-agnostic agent lifecycle
IAgentTools Agent Bridge Custom tool registration with agents
IAgentPermissions Agent Bridge Permission mode/handler configuration
ISAAOrchestrator Agent Bridge Silence-Abstract-Act phase orchestration
ILingStrategy Agent Strategy pattern for ling spawn modes

New Implementations

Implementation Protocol Description
FSMWorkflowEngine IWorkflowEngine EDN FSM specs compiled via SCI
VtermStrategy ILingStrategy Emacs vterm buffer spawn
HeadlessStrategy ILingStrategy ProcessBuilder subprocess spawn
AgentSDKStrategy ILingStrategy Claude Agent SDK spawn via libpython-clj
ClaudeSDKBackend IAgentBackend Claude Agent SDK bridge (external)
NoopAgentBackend IAgentBackend No-op fallback (implements 4 protocols)
NoopWorkflowEngine IWorkflowEngine No-op fallback

New Records

Record Protocol Description
TextContext IDispatchContext Plain text dispatch (backward compat)
RefContext IDispatchContext Pass-by-reference context (~25x savings)

Architecture: Open Protocols / Closed Implementations

hive-mcp follows a strict open protocol / closed implementation pattern that maps to its licensing boundary:

┌─────────────────────────────────────────────────────────────────┐
│  OPEN (AGPL-3.0) — hive-mcp                                    │
│                                                                 │
│  defprotocol IKGStore        defprotocol IMemoryStore          │
│  defprotocol IWorkflowEngine defprotocol IChannel              │
│  defprotocol IAgentBackend   defprotocol IConnector            │
│                                                                 │
│  DataScriptStore (testing)   NoopChannel                       │
│  NoopWorkflowEngine          NoopConnector                     │
│  NoopAgentBackend                                              │
│                                                                 │
├─────────────────────────── requiring-resolve ────────────────────┤
│                                                                 │
│  ADDONS — separate repos, loaded via classpath discovery        │
│                                                                 │
│  DatalevinStore (production)  ClaudeSDKBackend                  │
│  DistributedWorkflowEngine   lsp-mcp, scc-mcp, clj-kondo-mcp  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Principles

  1. Protocols are always AGPL: Every defprotocol is in hive-mcp and fully open
  2. Noop fallbacks everywhere: hive-mcp works standalone with NoopWorkflowEngine, NoopChannel, etc.
  3. requiring-resolve stub pattern: Enhanced implementations are loaded at runtime via requiring-resolve, falling back to noop if not on classpath
  4. No compile-time coupling: hive-mcp never (:require ...) proprietary namespaces

Implementing a Protocol

To implement any hive-mcp protocol:

;; 1. Require the protocol
(require '[hive-mcp.protocols.kg :as kg])

;; 2. Implement with defrecord
(defrecord MyKGStore [conn-atom]
  kg/IKGStore
  (ensure-conn! [this] ...)
  (transact! [this tx-data] ...)
  (query [this q] ...)
  (query [this q inputs] ...)
  (entity [this eid] ...)
  (entid [this lookup-ref] ...)
  (pull-entity [this pattern eid] ...)
  (db-snapshot [this] ...)
  (reset-conn! [this] ...)
  (close! [this] ...))

;; 3. Register at init time
(kg/set-store! (->MyKGStore (atom nil)))

Active Atom Management Pattern

Every core protocol follows the same lifecycle pattern:

(defonce ^:private active-store (atom nil))

(defn set-store! [store]      ;; Set during initialization
  {:pre [(satisfies? IKGStore store)]}
  (reset! active-store store))

(defn get-store []             ;; Get with error if unset
  (or @active-store (throw ...)))

(defn store-set? []            ;; Check if configured
  (some? @active-store))

(defn clear-store! []          ;; Reset (testing)
  (when-let [s @active-store]
    (close! s))
  (reset! active-store nil))

Design Patterns

Pattern: Interface Segregation (SOLID-I)

Protocols are small and focused. Example from Agent Bridge:

IAgentSession      — Session interaction (query, interrupt, stream)
IAgentBackend      — Backend lifecycle (connect, disconnect, capabilities)
IAgentTools        — Tool registration
IAgentPermissions  — Permission control
ISAAOrchestrator   — SAA phase orchestration

A backend can implement all 5, or just IAgentBackend. NoopAgentBackend implements all 5 in one record.

Pattern: Noop Fallback

Every protocol has a no-op implementation that ensures the system runs without real backends:

Protocol Noop Record Behavior
IKGStore NoopKGStore Queries return #{}
IMemoryStore (none, uses AtomStore) In-memory only
IWorkflowEngine NoopWorkflowEngine Returns :loaded? false
IChannel NoopChannel Sends succeed silently
IBrowserAutomation NoopBrowserAutomation Returns :success? false
IAgentBackend NoopAgentBackend Returns empty capabilities
IConnector NoopConnector Mock send/receive

Pattern: CLARITY-Y (Yield Safe Failure)

Methods never throw exceptions. They return result maps:

{:success? false
 :errors ["NoopWorkflowEngine: No workflow engine configured."]
 :result nil}

This makes error handling uniform and composable across the entire system.

Pattern: Registry + Active Atom

Large protocol families (Channel, Connector, Automation) use dual management:

  • Registry: Multiple instances, keyed by ID (e.g. :redis-channel, :mqtt-channel)
  • Active Atom: Single "currently active" instance for convenience

Last updated: 2026-02-07 | Release: 0.12.0

Clone this wiki locally