Architecture Overview

Architecture Overview

AuRoRA's cognitive system is organized as a Semantic Cognitive System (SCS) — a biologically-inspired stack of specialized modules that mirror the structure of the human brain. Each layer has a single responsibility and communicates through well-defined interfaces.

---

Cognitive Layers

flowchart TD
    GUI["GUI — AGi.html\nrosbridge WebSocket bridge"]
 
    CNC["CNC — Central Neural Core\nROS2 node · asyncio event loop · vLLM streaming · _busy gate"]
 
    MCC["MCC — Memory Coordination Core\nAssembles context · owns eviction handoff · single memory interface for CNC"]
 
    WMC["WMC — Working Memory Cortex\nDeque · Miller's Law 7±2 · chunk-bounded"]
 
    EMC["EMC — Episodic Memory Cortex\nSQLite WAL · theta-rhythm encoding · dual-path recall · RRF"]
 
    MSB["MSB — Memory Storage Bank\nEncodingEngine · EngramComplex · sqlite-vec KNN · FTS5 · RRF\nShared substrate — no domain knowledge"]
 
    GUI -->|"/cns/neural_input"| CNC
    CNC --> MCC
    MCC --> WMC
    MCC --> EMC
    WMC -.->|"evicted PMTs"| EMC
    WMC --> MSB
    EMC --> MSB

Loading

Biological analogy: CNC = prefrontal cortex (executive control), MCC = PFC working space (active memory coordinator), WMC = phonological loop (short-term buffer), EMC = hippocampus (episodic encoding and recall), MSB = neural tissue substrate (shared mechanisms).

---

Data Flow — One Conversation Turn

sequenceDiagram
    participant GUI
    participant CNC
    participant MCC
    participant WMC
    participant EMC
    participant Cosmos
 
    GUI->>CNC: /cns/neural_input
    activate CNC
 
    CNC->>MCC: assemble_memory_context(user_prompt)
    activate MCC
 
    par sync
        MCC->>WMC: recall_pmt_schema()
        WMC-->>MCC: active turns
    and async isolated thread
        MCC->>EMC: reinstate_episodes(cue)
        EMC-->>MCC: recalled episodes via RRF
    end
 
    MCC-->>CNC: messages[ system + EMC episodes + WMC turns + user ]
    deactivate MCC
 
    CNC->>Cosmos: POST /v1/chat/completions (SSE)
    loop stream tokens
        Cosmos-->>CNC: token delta
        CNC-->>GUI: /gce/response chunk
    end
 
    CNC->>MCC: register_memory(user)
    CNC->>MCC: register_memory(assistant)
    MCC->>WMC: fill_pmt()
 
    alt PMTs evicted
        WMC-->>MCC: evicted PMTs
        MCC-)EMC: _bind_to_episodic_buffer() [run_in_executor]
        EMC-)EMC: theta rhythm → encode → consolidate
    end
 
    deactivate CNC

Loading

---

Component Reference

CNC — Central Neural Core

src/scs/scs/cnc.py

The ROS2 node — entry and exit point for all cognition. Owns the asyncio event loop, the vLLM HTTP client, and the _busy flag that enforces single-turn processing. CNC never accesses WMC or EMC directly — all memory operations go through MCC.

MCC — Memory Coordination Core

src/scs/scs/mcc.py

The memory manager. CNC calls three methods: register_memory(), assemble_memory_context(), and report_memory_stats(). MCC handles everything else — coordinating WMC and EMC, managing eviction handoff, and assembling the unified context window sent to Cosmos.

WMC — Working Memory Cortex

src/scs/scs/wmc.py

Fast, in-memory, bounded buffer. Holds the active conversation as a deque of PMTs (Phonological Memory Traces). Capacity is governed by two limits: Miller's Law slot count (7±2 PMTs, tunable) and a global chunk limit tied to the cognitive engine's context window. When either limit is exceeded, the oldest PMT is evicted and returned to MCC for binding to EMC.

EMC — Episodic Memory Cortex

src/scs/scs/emc.py

Long-term episodic store. Receives evicted PMTs from MCC, encodes them as semantic vectors via a background theta-rhythm encoding cycle, and consolidates them into SQLite. On each turn, recalls relevant past episodes via dual-path retrieval (semantic + lexical) fused by RRF, then reinstates them into the context window as a system message.

MSB — Memory Storage Bank

src/scs/scs/msb.py

Shared substrate for all memory cortices. Contains the EncodingEngine (sentence-transformers wrapper), EngramComplex (all SQLite operations), and _converge_memories() (RRF fusion). MSB has no domain knowledge — it only knows how to encode, store, and retrieve. EMC, SMC (M2), and PMC (M3) all run on top of it.

---

Memory Terminology

Term	Meaning
PMT	Phonological Memory Trace — one paired turn (user prompt + AI response)
Engram	One encoded and stored memory record in the engram complex
Binding Stream	Private deque inside EMC — evicted PMTs queue here before encoding
Recall Stream	Shared stream — recalled episodes surface here before context injection
Theta Rhythm	Background event that wakes the encoding cycle to drain the binding stream
Sharp-Wave Ripple	Triggered consolidation event (planned M2 — Dream Cycle)
RRF	Reciprocal Rank Fusion — fuses semantic and lexical ranked results
Engram Complex	The SQLite database holding all encoded memory traces
Chunk	Unit of context window capacity (~4 characters per chunk)

---

Storage Layout

~/.aurora/
└── neural_gateway/
    └── engram_complex/
        └── emc.db
            ├── emc_storage   # primary episodic records
            ├── emc_vector    # sqlite-vec KNN index (semantic)
            ├── emc_lexical   # FTS5 index (lexical)
            └── emc_staging   # crash-safe buffer for unencoded PMTs

---

Thread Model

Thread	Purpose
ROS2 executor	Handles ROS2 callbacks — calls _on_input()
cnc-asyncio	Dedicated asyncio event loop — runs _handle() and _stream_cosmos()
cnc-pool (×2)	ThreadPoolExecutor — runs blocking I/O off the event loop
emc-encoding-cycle	Background daemon — theta-rhythm encoding, deprioritized via os.nice(19)

Single-turn safety is enforced by CNC._busy — set at the start of _handle(), cleared in finally. The encoding cycle is explicitly deprioritized so it never competes with active cognition latency.

---

Inference Stack

Component	Detail
Model	Cosmos Reason2 2B (embedl W4A16 quantized)
Serving	vLLM — OpenAI-compatible /v1/chat/completions
Transport	SSE streaming via httpx
Hardware	Jetson Orin Nano Super 8GB, JetPack 6.2.2, CUDA 12.6
Embedding	BAAI/bge-small-en-v1.5, 384-dim, CPU-only
Vector DB	sqlite-vec (vec0 virtual table, exact KNN)