Mind AI Protocol (MAP)
MAP is a line-oriented protocol designed for AI agents to interact with MIND tooling. It enables agents to compile, patch, query, and validate IR modules via a simple request-response pattern.
Design Principles
- Line-oriented: Each request/response is a single line (with optional heredoc for large payloads)
- Sequence numbers: Every request has a sequence number for reliable correlation
- 4.3x fewer tokens than JSON-RPC for the same operations
- Stateful sessions: Server maintains module state between requests
Benchmark: MAP vs JSON-RPC
| Protocol | Size (bytes) | Tokens | vs JSON-RPC |
|---|---|---|---|
| JSON-RPC | 1,004 | 251 | baseline |
| MAP | 234 | 58 | 4.3x fewer tokens |
MAP saves 193 tokens per session compared to JSON-RPC, reducing AI agent costs by 77%.
Protocol Format
# Request format @<seq> <command> [args...] # Response format (success) =<seq> ok [data...] # Response format (error) =<seq> err msg="<error message>"
Commands
| Command | Description | Example |
|---|---|---|
| hello | Establish session, negotiate versions | @1 hello mic=1 map=1 |
| load | Load MIC module into session | @2 load <<EOF...EOF |
| patch | Insert/modify nodes in module | @3 patch after=N5 N6 relu N5 T0 |
| check | Validate current module | @4 check |
| dump | Export current module as MIC | @5 dump |
| query | Query node information | @6 query N5 |
| bye | Close session | @7 bye |
Example Session
# Client establishes connection @1 hello mic=1 map=1 # Server responds with capabilities =1 ok version=1.0.0 mic=1 map=1 features=[patch,check,dump,query] # Client loads a module @2 load <<EOF mic@1 T0 f32 N0 const.f32 1.0 T0 N1 const.f32 2.0 T0 N2 add N0 N1 T0 O N2 EOF =2 ok nodes=3 # Client patches the module @3 patch after=N2 N3 mul N2 N2 T0 =3 ok # Client validates the module @4 check =4 ok valid=true nodes=4 # Client exports the module @5 dump =5 ok <<EOF mic@1 T0 f32 N0 const.f32 1.0 T0 N1 const.f32 2.0 T0 N2 add N0 N1 T0 N3 mul N2 N2 T0 O N3 EOF # Client closes session @6 bye =6 ok
Session Modes
| Mode | Description |
|---|---|
| strict | All operations validated immediately |
| lenient | Allow partial modules, validate on check |
Error Codes
# Version mismatch =1 err msg="version mismatch: server supports mic=1 map=1" # Parse error =2 err msg="parse error at line 3: unknown opcode 'foo'" # Invalid reference =3 err msg="invalid reference: N99 not defined" # Validation error =4 err msg="type mismatch: expected f32, got i64"
Running the MAP Server
# Start MAP server on stdio mind-ai # Start MAP server on TCP port mind-ai --tcp 9999 # Connect with netcat nc localhost 9999
Integration with AI Agents
MAP is designed for integration with AI code assistants. The protocol enables agents to:
- Incrementally build neural network architectures
- Validate changes before committing
- Query existing module structure
- Export production-ready MIC files
Learn More
See the full MAP specification at RFC-0002: Mind AI Protocol.