Content
# binary-mesh
Private semantic binary mesh agent — autonomous AI system for code analysis, vulnerability hunting, and automated fix generation using physics-inspired deterministic intelligence.
## Architecture
binary-mesh implements **deterministic intelligence** — a physics-based approach where AI doesn't "generate" solutions but navigates pre-computed solution spaces:
- **Pattern Slots**: Binary-encoded successful patterns (fixes, refactors, invariants)
- **Mesh Query**: Semantic search across 16K+ slots → DIRECT HIT (sim ≥ 0.85) = 0 LLM calls, <1ms
- **Flywheel Learning**: Distills successful solutions into reusable binary format
- **Quality Matrix**: L0-L9 composite scoring (Stability, Usefulness, Reuse, Latency, Completion)
### Core Components
| Component | Path | Purpose |
|-----------|------|---------|
| bin_gg | `cmd/binarymesh` | Main server: HTTP API (:1337), cluster (:1447), orchestrator |
| binary-mesh-mcp | `cmd/mcp` | MCP server for OpenCode integration (57 tools) |
| Embedder | `pkg/embed` | 384-dim int8 quantized embeddings |
| Mesh | `pkg/mesh` | Semantic search over PatternSlots |
| Orchestrator | `pkg/orchestrator` | Unified pipeline: DIRECT → ENRICH → INFERENCE |
| Binary Runtime | `pkg/do` | Execution engine (28 opcodes, C-backed I/O) |
| Hunt | `pkg/hunt` | Automated vulnerability discovery with SuperInvariants |
| RAG | `pkg/rag` | 5-signal hybrid search (semantic, AST, kw, md, comment) |
| Project Map | `pkg/projectmap` | SQLite O(1) symbol/package lookup |
## Quick Start
### Build
```bash
cd embryo
# Main binary (CGO_ENABLED=0 for static build)
CGO_ENABLED=0 go build -ldflags="-s -w" -o bin_gg ./cmd/binarymesh
# MCP server
CGO_ENABLED=0 go build -ldflags="-s -w" -o binary-mesh-mcp ./cmd/mcp
```
### Run Server
```bash
# Set required env vars
export INFERENCE_KEY="sk-..."
export INFERENCE_URL="https://proxy.gonka.gg/v1/chat/completions"
export INFERENCE_MODEL="Qwen/Qwen3-235B-A22B-Instruct-2507-FP8"
export EMBEDDER_URL="http://localhost:1227"
# Start server
./bin_gg gg --addr=:1337 --data-dir=/data
```
### MCP Integration
```bash
# MCP binary location
/home/user/bin/binary-mesh-mcp
# OpenCode config (embryo/.opencode.json):
{
"mcp": {
"binary-mesh": {
"type": "local",
"command": "/home/user/bin/binary-mesh-mcp",
"enabled": true
}
}
}
```
## Key Commands
```bash
# Mesh operations
./bin_gg query --task "fix concurrent map write"
./bin_gg stats
# Hunt vulnerabilities
./bin_gg hunt --protocol gonka --gap memory_safety --depth 50
# Solve tasks (end-to-end)
./bin_gg solve --task "description here" --workspace /path/to/repo
# Distill patterns
./bin_gg distill --invariant "concurrent access requires mutex" --domain go
# Ingest repositories
./bin_gg ingest --repo /root/binary-mesh-data/repos/gonka.git
./bin_gg ingest-all
```
## MCP Tools (57 available)
### Core Operations
- `binary-mesh_solve` — Full pipeline: mesh_query → DIRECT HIT or INFERENCE → patch
- `binary-mesh_hunt` — Vulnerability hunter with SuperInvariants (~3000 tokens)
- `binary-mesh_dual_solve` — 2 approaches + AI review + effectiveness comparison
### Mesh Operations
- `binary-mesh_mesh_query` — Semantic search (sim ≥ 0.85 = DIRECT HIT)
- `binary-mesh_mesh_enrich` — Enrich task with mesh patterns
- `binary-mesh_mesh_distill` — Distill solution into mesh
- `binary-mesh_mesh_add_slot` — Manually add pattern slot
### RAG & Project Map
- `binary-mesh_rag_search` — 5-signal hybrid search (semantic, AST, kw, md, comment)
- `binary-mesh_project_map_lookup` — O(1) symbol/package lookup
- `binary-mesh_project_map_flow` — Call graph analysis
### Analysis & Quality
- `binary-mesh_code_quality_audit` — Full package analysis (unused exports, violations)
- `binary-mesh_full_file_analysis` — File + indexed context
- `binary-mesh_project_inference` — Classify code: app vs framework vs vendor
### Git & Deploy
- `binary-mesh_git_status` / `_add` / `_commit` / `_push`
- `binary-mesh_deploy_status` / `_pull` / `_restart` / `_cycle`
### Monitoring
- `binary-mesh_health` — Quick health check
- `binary-mesh_observer_stats` — Hunt statistics
- `binary-mesh_quality` — QualityMatrix L0-L9 scores
- `binary-mesh_buckets` — Findings by protocol/gap
- `binary-mesh_survival` — Git blame survival analysis
## Port Assignments (X_X7 pattern)
| Port | Service | Description |
|------|---------|-------------|
| 1227 | Embedder | Vector embedding service |
| 1337 | GG API | Plain HTTP API (59 routes, reserved) |
| 1447 | Cluster | bin_gg cluster/serve |
| 2022 | SSH | Server access (root@10.0.0.10) |
| | UI | Docker-served web UI |
| 2022 | SSH | Server access (root@10.0.0.10) |
## Runtime Environment
Critical env vars (enforced via `embryo/install.sh`):
```bash
NATIVE_TOOL_CALLS=false
SIMULATE_TOOL_CALLS=true
HASH_ALL_ACTION_BYTES=true
BYTE_INTEGRITY_CHECK=sha256
TOOL_CALL_PARSER=simulate
```
## CI/CD
- **Branches**: `embryo` (dev), `git_dumb` (deploy)
- **GitHub Actions**: Go 1.24, setup-go@v5
- **Deploy flow**: push to `git_dumb` → SSH to server → docker cp → restart
## Test Commands
```bash
cd embryo
# Unit tests (pkg/dumb and pkg/do only)
go test ./pkg/dumb/... ./pkg/do/... -v -timeout 120s
# Note: pkg/do requires CGO with li bcore for full functionality
# pkg/dumb tests PASS (10/10 tests)
```
## Distill Sources
Configured in `embryo/repos.json`:
- gonka (gonka-ai/gonka)
- kubernetes (kubernetes/kubernetes)
- moby (moby/moby)
- golang (golang/go)
- vllm (vllm-project/vllm)
- consul (hashicorp/consul)
- etcd (etcd-io/etcd)
- containerd (containerd/containerd)
- prometheus (prometheus/prometheus)
- traefik (traefik/traefik)
- opentelemetry-go (open-telemetry/opentelemetry-go)
- ethereum (ethereum/go-ethereum)
## Key Architecture Facts
- **Entry point**: `embryo/cmd/binarymesh` → `bin_gg` (21MB static binary)
- **MCP server**: `embryo/cmd/mcp` → `binary-mesh-mcp` (8.9MB)
- **Data directory**: `/data` (server), `/root/binary-mesh-data/repos` (cloned repos)
- **Docker image**: `golang:1.24-bookworm` builder → `debian:bookworm-slim` runtime
- **Protocol**: Gonka-ai de-ai-dapi (autonomous mainstream protocol)
## Physics-Based Intelligence
binary-mesh implements fundamental physics principles:
1. **Principle of Least Action**: Trajectories minimize S = α·Cost + β·Time + γ·Risk
2. **Quantum Interference**: Successful patterns amplify (constructive), failures create "black holes"
3. **Conservation Laws**: Invariants (type safety, determinism) preserved across transformations
4. **Phase Transitions**: Distillation crystallizes successful traces into PatternSlots
5. **Bayesian Inference**: posterior = sim(query, centroid) × prior
See `PHYSICS_ARCHITECTURE_MAPPING.md` for detailed mathematical modeling.
## Project Status
Current metrics (from running system):
- **Mesh**: 298,135 slots across 36 maps
- **Survival Index**: 69.2% (top commit: 29K surviving lines)
- **Quality**: Composite 4738 (L0=8000 Stability, L6=2300 Reuse, L9=7072 Completion)
- **RAG**: 180,684 Qdrant points (38K AST, 117K keywords, 6K markdown, 5K comments)
- **Hunt**: 700 rejected findings across gonka + go-ethereum protocols
## References
- `AGENTS.md` — Compact guide for OpenCode sessions
- `PHYSICS_ARCHITECTURE_MAPPING.md` — Physics-based architecture (541 lines)
- `GAP_NANOOPS_MANIFEST.md` — Gap strategy (73690 bytes)
- `INIT.DOC` — Binary format documentation
- `embryo/install.sh` — Runtime enforcer script
- `embryo/docs/` — Additional documentation (architecture, CLI, GONKAGATE API)
