Architecture Overview

Architecture Overview

MindFry is built on a Zero-GC, Data-Oriented Design (DOD) architecture optimized for microsecond-level cognitive reflexes.

High-Level Architecture

flowchart TB
    subgraph Core["MindFry Core"]
        direction TB
        subgraph Storage["Memory Storage"]
            PA[Psyche Arena<br/><small>Lineages</small>]
            BG[Bond Graph<br/><small>CSR/Adj</small>]
            SA[Strata Arena<br/><small>Engrams</small>]
        end

        DE[Decay Engine<br/><small>Rayon</small>]

        subgraph Services["Services"]
            CX[Cortex<br/><small>Tri-Cortex</small>]
            SY[Synapse Engine<br/><small>Propagation</small>]
            SV[MFBP Server<br/><small>TCP Handler</small>]
        end
    end

    AK[(Akashic Records<br/><small>sled</small>)]

    Storage --> DE
    DE --> Services
    Core --> AK

Core Components

MindFry Struct

The central database instance containing all subsystems:

pub struct MindFry {
    pub psyche: PsycheArena,      // Active memory storage
    pub strata: StrataArena,      // Historical engram storage
    pub bonds: BondGraph,         // Living bond graph
    pub decay: DecayEngine,       // Background decay engine
    pub cortex: Cortex,           // Decision-making brain
    pub synapse: SynapseEngine,   // Signal propagation
    pub store: Option<...>,       // Persistent storage
}

Psyche Arena

Hot storage for active lineages. Pre-allocated TypedArray for O(1) access. Default capacity: 1M lineages.

Bond Graph

CSR (Compressed Sparse Row) adjacency matrix for efficient traversal. Default capacity: 4M bonds.

Strata Arena

Ring-buffer history per lineage. O(1) back-linking and iteration. Default depth: 64 engrams.

Cortex

Tri-Cortex decision engine with Setun ternary logic. Mood + Personality modulate accessibility.

Module Structure

flowchart LR
    subgraph src["src/"]
        lib[lib.rs]

        subgraph arena["arena/"]
            psyche[psyche.rs]
            strata[strata.rs]
        end

        subgraph dynamics["dynamics/"]
            decay[decay.rs]
            synapse[synapse.rs]
        end

        subgraph graph["graph/"]
            bond[mod.rs]
        end

        subgraph setun["setun/"]
            cortex[setun.rs]
        end

        subgraph protocol["protocol/"]
            opcodes[opcodes.rs]
            codec[codec.rs]
            handler[handler.rs]
        end

        subgraph persistence["persistence/"]
            akashic[akashic.rs]
        end
    end

Directory	Files	Purpose
arena/	psyche.rs, strata.rs	Memory storage
dynamics/	decay.rs, synapse.rs	Cognitive processes
graph/	mod.rs	Bond management (CSR)
setun/	setun.rs	Tri-Cortex logic
protocol/	opcodes.rs, codec.rs, …	Network layer
persistence/	akashic.rs	sled-backed storage

Memory Layout (Zero-GC)

MindFry avoids garbage collection through:

1. Pre-allocated Arenas: All storage is allocated upfront
2. Generational Indices: IDs are (index, generation) tuples for safe reuse
3. No Heap Allocations in Hot Path: All operations use stack/arena memory
4. Lazy Decay: Energy computed only on access, not continuously

Lineage Memory Layout

Field	Type	Size
energy	f32	4 bytes
threshold	f32	4 bytes
decay_rate	f32	4 bytes
created_at	u64	8 bytes
accessed_at	u64	8 bytes
rigidity	f32	4 bytes
Total		32 bytes (cache-line friendly)

Feature Flags

MindFry uses Cargo features to enable optional functionality:

Feature	Default	Description
server	✅	TCP server, persistence, protocol
wasm	❌	WebAssembly compilation target
ffi	❌	C FFI bindings

---

Next: Learn about the Tri-Cortex Engine or the MFBP Protocol.