MFBP Specification

MFBP Protocol Specification

MFBP (MindFry Binary Protocol) is a custom binary protocol designed for microsecond-level cognitive reflexes over TCP.

Design Goals

Goal	Approach
Low latency	Binary encoding, no text parsing
High throughput	Pipelining (non-blocking dispatch)
Simple parsing	Length-prefixed frames, 1-byte OpCodes
Extensibility	Reserved OpCode ranges

Frame Format

Every MFBP frame follows this structure:

packet-beta
  0-31: "Length (4 bytes, LE)"
  32-39: "OpCode"
  40-95: "Payload (variable)"

Field	Size	Description
Length	4 bytes (u32 LE)	Total frame size (includes OpCode + Payload)
OpCode	1 byte (u8)	Command identifier
Payload	Variable	Command-specific data

Wire Example

Request: LINEAGE.CREATE fire 0.9

Offset	Hex	Description
0x00	`05 00 00 00`	Length: 5
0x04	`10`	OpCode: `0x10` (LineageCreate)
0x05	`04 00`	key_len: 4
0x07	`66 69 72 65`	key: “fire”
0x0B	`66 66 66 3F`	energy: 0.9 (f32)

Response: OK

Offset	Hex	Description
0x00	`01 00 00 00`	Length: 1
0x04	`F0`	OpCode: `0xF0` (OK)

OpCode Reference

Lineage Operations (0x10-0x1F)

OpCode	Name	Payload	Description
`0x10`	`LINEAGE.CREATE`	`[key_len:u16, key:bytes, energy:f32]`	Create new lineage
`0x11`	`LINEAGE.GET`	`[key_len:u16, key:bytes, flags?:u8]`	Get lineage details
`0x12`	`LINEAGE.STIMULATE`	`[key_len:u16, key:bytes, delta:f32, flags?:u8]`	Inject energy
`0x13`	`LINEAGE.FORGET`	`[key_len:u16, key:bytes]`	Soft-delete
`0x14`	`LINEAGE.TOUCH`	`[key_len:u16, key:bytes]`	Update access time

Bond Operations (0x20-0x2F)

OpCode	Name	Payload	Description
`0x20`	`BOND.CONNECT`	`[src_len:u16, src:bytes, tgt_len:u16, tgt:bytes, strength:f32, polarity:i8]`	Create bond
`0x21`	`BOND.REINFORCE`	`[src_len:u16, src:bytes, tgt_len:u16, tgt:bytes, delta:f32]`	Strengthen bond
`0x22`	`BOND.SEVER`	`[src_len:u16, src:bytes, tgt_len:u16, tgt:bytes]`	Remove bond
`0x23`	`BOND.NEIGHBORS`	`[key_len:u16, key:bytes]`	Get connected lineages

Query Operations (0x30-0x3F)

OpCode	Name	Payload	Description
`0x30`	`QUERY.CONSCIOUS`	`[min_energy:f32]`	Get lineages above threshold
`0x31`	`QUERY.TOPK`	`[k:u32]`	Top K by energy
`0x32`	`QUERY.TRAUMA`	`[min_rigidity:f32]`	High-rigidity lineages
`0x33`	`QUERY.PATTERN`	`[pattern_len:u16, pattern:bytes]`	Pattern match keys

System Operations (0x40-0x4F)

OpCode	Name	Payload	Description
`0x40`	`SYS.PING`	(empty)	Keep-alive
`0x41`	`SYS.STATS`	(empty)	Database statistics
`0x42`	`SYS.SNAPSHOT`	`[name_len:u16, name:bytes]`	Create checkpoint
`0x43`	`SYS.RESTORE`	`[name_len:u16, name:bytes]`	Restore from checkpoint
`0x44`	`SYS.FREEZE`	`[state:u8]`	Pause/resume decay
`0x45`	`PHYSICS.TUNE`	`[param_id:u8, value:f32]`	Adjust physics constants
`0x46`	`SYS.MOOD.SET`	`[mood:f32]`	Set Cortex mood

Response Codes (0xF0-0xFF)

OpCode	Name	Payload	Description
`0xF0`	`RESPONSE.OK`	(varies)	Success
`0xF1`	`RESPONSE.ERROR`	`[error_code:u8, msg_len:u16, msg:bytes]`	Error
`0xF2`	`RESPONSE.EVENT`	`[event_type:u8, ...]`	Subscription notification

Response Status

flowchart LR
    GET[LINEAGE.GET] --> |0x00| FOUND[Found]
    GET --> |0x01| NF[Not Found]
    GET --> |0x02| REP[Repressed]
    GET --> |0x03| DORM[Dormant]

Status	Value	Meaning
`FOUND`	`0x00`	Lineage returned successfully
`NOT_FOUND`	`0x01`	Key does not exist
`REPRESSED`	`0x02`	Below consciousness threshold
`DORMANT`	`0x03`	Deep subconscious, requires bypass

Query Flags

Flag	Value	Effect
`BYPASS_FILTERS`	`0x01`	Skip mood/threshold checks
`INCLUDE_REPRESSED`	`0x02`	Include below-threshold memories
`NO_SIDE_EFFECTS`	`0x04`	Skip Observer Effect
`NO_PROPAGATE`	`0x01` (stimulate)	Skip cascade propagation

Combine with bitwise OR: FORENSIC = 0x07 (all bypass flags).

Connection Flow

sequenceDiagram
    participant Client
    participant Server

    Client->>Server: TCP Connect (port 9527)
    Client->>Server: SYS.PING
    Server->>Client: RESPONSE.OK + uptime

    Client->>Server: LINEAGE.CREATE "fire" 0.9
    Server->>Client: RESPONSE.OK

    Client->>Server: LINEAGE.GET "fire"
    Server->>Client: RESPONSE.OK + LineageInfo

    Client->>Server: TCP Close

Pipelining

MFBP supports pipelining for high throughput:

sequenceDiagram
    participant Client
    participant Server

    Client->>Server: LINEAGE.CREATE "a"
    Client->>Server: LINEAGE.CREATE "b"
    Client->>Server: BOND.CONNECT "a" → "b"

    Server->>Client: RESPONSE.OK (for "a")
    Server->>Client: RESPONSE.OK (for "b")
    Server->>Client: RESPONSE.OK (for bond)

Responses are returned in FIFO order.

Next: See the complete OpCodes Reference or Wire Format Examples.