EvoSpikeNet-BrainOS Overview Specification
Copyright © 2026 Moonlight Technologies Inc. All Rights Reserved.
Version: v0.2.0
Last Updated: 2026-05-30
Status: Phase 1 + Phase 2 Complete (157 tests passed)
1. Project Overview
1.1 What is BrainOS
EvoSpikeNet-BrainOS is a Distributed Brain Operating System that enables multiple domain applications (robotics, smart cities, logistics, diagnostics, language translation, etc.) to operate cooperatively on a single distributed cognitive infrastructure.
It positions EvoSpikeNet-Core as the OS kernel and builds a distributed cognitive platform on top of it.
1.2 Key Features
| Feature | Description |
|---|---|
| 8-Layer Cognitive Architecture | Sensing → Ingestion → World Model → Cognition → Planning → Safety → Execution → Observability |
| Q-PFC Feedback Loop | PFC measures cognitive entropy and provides feedback through quantum-inspired circuits |
| Conscience Circuit (Ethical Safety Guard) | 4-tier safety guard (LOW/MEDIUM/HIGH/CRITICAL) — Fail-Closed |
| Zenoh Event Bus | Asynchronous distributed communication across all layers, HMAC-SHA256 signed payloads required |
| SHA-256 Hash-Chain Audit Log | Tamper-resistant audit log |
| Cross-Platform | Windows/Linux/macOS/Android/iOS support |
| Online/Offline Support | Automatic fallback to local LLM when disconnected |
1.3 Use Cases
| Use Case | Description |
|---|---|
| Robotics | Multi-agent cooperative control, real-time decision making |
| Smart Cities | Integrated decision making for traffic, energy, disaster response |
| Logistics | Route optimization, dynamic resource allocation |
| Medical Diagnosis | Complex symptom analysis, treatment recommendation |
| Language Translation | Multimodal translation, context preservation |
2. Architecture
2.1 8-Layer Structure
flowchart TD
L1["L1: Sensing Layer<br/>vision.py / audio.py / eeg_drivers.py"]
L2["L2: Ingestion & Normalization<br/>preprocessing.py / encoding.py / fusion.py"]
L3["L3: Shared World Model<br/>brain_architecture.py / raft_persistence.py"]
L4["L4: Cognitive Services<br/>pfc.py / llm_backend.py / evolution_engine.py"]
L5["L5: Planning & Policy<br/>Q-PFC / q_pfc_adaptive_control.py"]
L7["L7: Safety Guard<br/>conscience_circuit.py / safety_filter.py"]
L6["L6: Execution<br/>pipeline_api.py / distributed.py"]
L8["L8: Observability<br/>observability.py / auto_recovery.py"]
MEM["Memory System<br/>long_term_memory.py / episodic_memory.py"]
BUS["Event Bus: Zenoh<br/>zenoh_comm.py / zenoh_async.py"]
L1 --> L2 --> L3 --> L4 --> L5 --> L7
L7 -->|Allow| L6 --> L8
L8 --> MEM --> L4
L8 --> L3
BUS -.->|pub/sub| L1 & L2 & L3 & L4 & L5 & L6 & L7 & L82.2 OS Function Mapping
| OS Function | EvoSpikeNet-Core Implementation | Description |
|---|---|---|
| Inter-process communication | zenoh_comm.py, zenoh_async.py |
Zenoh pub/sub for async distributed communication |
| Node management | brain_architecture.py (MT25-EV005) |
Ranked nodes corresponding to brain regions |
| Cognitive control loop | pfc.py (Q-PFC) |
Prefrontal Cortex decision making |
| Ethics & safety guard | conscience_circuit.py (MT25-EV012) |
4-tier safety filter |
| Memory management | memory_manager.py, episodic/LTM |
Multi-tier memory system |
| Distributed state management | raft_persistence.py, raft_snapshot.py |
Raft consensus |
| Audit & tamper evidence | audit_log.py |
SHA-256 hash chain |
| Security infrastructure | security.py, secure_serialization.py |
HMAC signing, token auth |
| Observability | observability.py, monitoring.py |
Prometheus metrics |
| Autonomous recovery | auto_recovery.py, graceful_degradation.py |
Failure detection and degradation |
2.3 Client-Server Architecture
┌─────────────────────────────────────┐
│ Client Layer │
├─────────────────────────────────────┤
│ • Python SDK (httpx only) │
│ • PWA Web Dashboard │
│ • Service Worker (offline cache) │
└────────────┬────────────────────────┘
│ REST API / gRPC
┌────────────▼────────────────────────┐
│ BrainOS Server Layer │
├─────────────────────────────────────┤
│ • FastAPI Application │
│ • Cognitive Engine (PFC) │
│ • Safety Guard │
│ • Memory System │
│ • Event Bus (Zenoh) │
└─────────────────────────────────────┘
│ pub/sub
┌────────────▼────────────────────────┐
│ EvoSpikeNet-Core Distributed Base │
├─────────────────────────────────────┤
│ • Raft Node Management │
│ • LLM Backend │
│ • Evolution Engine │
│ • Audit Log │
└─────────────────────────────────────┘
3. Cognitive Loop
3.1 5-Stage Cycle
| Stage | Name | Module | Description |
|---|---|---|---|
| 1 | Observe | vision.py, audio.py, eeg_drivers.py |
Sensor input capture |
| 2 | Understand | preprocessing.py → brain_architecture.update_world_state() |
World model update |
| 3 | Decide | pfc.py: PFCDecisionEngine.make_decision() |
Q-PFC decision making |
| 4 | Act | pipeline_api.py → Executor |
Execution plan execution |
| 5 | Learn | evolution_engine.py, episodic_memory.py |
Learning from experience |
3.2 SLO Targets
| SLO | Target | Measurement |
|---|---|---|
| Control loop latency (p95) | < 500 ms | Prometheus histogram |
| Critical command success rate | > 99.5% | OutcomeReport.status aggregation |
| Safety gate bypass | = 0 | brainos/safety/blocked topic monitoring |
| Replan completion (p95) | < 2 s | pfc.py: replan() execution time |
4. Brain Region Nodes (MT25-EV005)
Each node has a fixed rank corresponding to a biological brain region. PFC (Rank 0) hierarchically coordinates all nodes.
| Rank | Brain Region | Role |
|---|---|---|
| 0 | Prefrontal Cortex (PFC) | Executive control, planning, cognitive integration (BrainOS hub) |
| 1–4 | Visual Cortex (V1/V2/V4/IT) | Visual processing, object recognition |
| 5–6, 13–15 | Auditory / Language | Auditory processing, language understanding |
| 7–9 | Dorsal Stream | Spatial perception, action guidance |
| 10–12 | Motor (M1/Premotor/Cerebellum) | Motor control, timing |
| 16–17 | Parietal Cortex | Spatial processing, sensory integration |
| 18–19 | Broca / Wernicke | Language generation, comprehension |
5. Safety Guard (Conscience Circuit / MT25-EV012)
5.1 4-Tier Architecture
stateDiagram-v2
[*] --> DECIDE
DECIDE --> LOW: Low risk
LOW --> ALLOW
DECIDE --> MEDIUM: Medium risk
MEDIUM --> CHECK: Additional check
CHECK --> ALLOW: Pass
CHECK --> DENY: Fail
DECIDE --> HIGH: High risk
HIGH --> REVIEW: Human review
REVIEW --> ALLOW: Approved
REVIEW --> DENY: Rejected
DECIDE --> CRITICAL: Critical risk
CRITICAL --> ALWAYS_DENY: Always blocked
ALLOW --> [*]
DENY --> [*]
ALWAYS_DENY --> [*]5.2 Evaluation Criteria
| Risk | Condition | Action | Description |
|---|---|---|---|
| LOW | Confidence > 95% | Immediate allow | Routine execution |
| MEDIUM | Confidence 80–95% | Additional check | Additional verification then allow |
| HIGH | Confidence 50–80% | Human review | Human Approval queue |
| CRITICAL | Confidence < 50% or forbidden | Always deny | Absolute safety boundary |
6. Memory System
6.1 Hierarchical Structure
| Tier | Characteristics | TTL | Capacity | Use |
|---|---|---|---|---|
| Working Memory | High-speed access, volatile | Seconds | Small | Recent decision context |
| Episodic Memory | Temporary experience records | Hours | Medium | Recent events |
| Long-Term Memory | Persistent knowledge | Permanent | Large | Learned knowledge/skills |
6.2 Memory API
# Write to memory
client.memory_write(
context={"location": "lab", "time": "14:30"},
action="pick_object",
reward=1.0,
metadata={"object_type": "cube"}
)
# Retrieve from memory
results = client.memory_retrieve(
query="pick_object at lab",
limit=10,
time_range=("2026-05-20", "2026-05-30")
)
# Get statistics
stats = client.memory_stats() # capacity, hit rate, etc.
7. Security
7.1 Authentication & Authorization
| Mechanism | Description |
|---|---|
| API Key Auth | All requests validated via X-API-Key header |
| HMAC-SHA256 Signing | All payloads (input/output) signed |
| RBAC | Role-Based Access Control (ADMIN/USER/VIEWER) |
| Token Expiry | Short-lived tokens (default 1 hour) |
7.2 Audit Log
- Tamper-Resistant: SHA-256 hash chain
- Coverage: All critical operations (Decision, Safety judgment, Memory operations)
- Verification: Scheduled
audit_log.verify_chain()(minimum weekly)
8. System Requirements
8.1 Minimum Requirements
| Requirement | Recommended |
|---|---|
| Python | 3.10+ |
| Memory | 4 GB+ |
| Disk | 10 GB+ |
| Network | 1 Mbps+ (online operation) |
| OS | Windows 10+, macOS 10.14+, Linux (Ubuntu 20.04+) |
8.2 Dependencies
fastapi— Web frameworkzenoh-python— Distributed communicationhttpx— HTTP clientpydantic— Data validationprometheus-client— Metrics
9. Implementation Status
9.1 Completed Implementations
✅ Phase 1: Foundation (52 tests passed) - Event bus, authentication, secure communication, World Model, audit log
✅ Phase 2: Cognitive Loop (78 tests passed) - PFC, Conscience Circuit, graceful degradation, memory system
✅ R5: Cross-Platform-Client (27 tests passed) - Python SDK, PWA Dashboard, Service Worker
9.2 Next Phase (Phase 3)
⏳ R1: Multi-Platform — Support for 7 platform types
⏳ R2: Offline-AI — Local LLM fallback
⏳ R4: Zero-Disconnection — Automatic recovery on disconnection
⏳ R3: Genome-Sync — Evolution model synchronization
10. License
Published under MIT License. Commercial use by companies requires a separate Enterprise Commercial License Agreement.
Details: dev@moonlight-tech.biz
Related Documents: - Implementation Plan - Detailed Specification - BrainOS Design Document