Architecture

How memory works

Based on the Atkinson-Shiffrin model from cognitive psychology, adapted for AI agents.

Sensory Register Raw input • 48h TTL • Attention filter

↓ rehearsal

Short-Term Memory Working context • Active rehearsal • 7-day half-life

↓ consolidation

Long-Term Memory Semantic vectors • Sister fusion • 60-day half-life

Biologically inspired, practically engineered

Every piece of information flows through three stores, each with its own retention rules and access patterns.

Sensory Register captures everything, discards noise in 48 hours
STM holds 7±2 active items with exponential decay
Rehearsal (retrieval, updates) resets decay timers
Consolidation promotes STM to LTM via semantic similarity
Sister memories fuse discriminatively: keep what differs, merge what overlaps
Ebbinghaus forgetting curve controls natural memory pruning
Prediction error gating rejects redundant input at write time

NEXO Brain Architecture Diagram — showing memory flow from sensory register through STM to LTM with cognitive pipelines

Full architecture: sensory register, STM, LTM, input pipeline, retrieval, and proactive systems

Science

The psychology behind NEXO Brain

Not just engineering — applied cognitive psychology. Every feature maps to a real research concept.

Psychological Concept	How NEXO Brain Implements It
Atkinson-Shiffrin (1968)	Three memory stores: sensory register, STM, and LTM with distinct retention rules
Ebbinghaus Forgetting Curve (1885)	Exponential decay: strength = strength * e^(-lambda * time)
Rehearsal Effect	Accessing a memory resets its strength to 1.0
Memory Consolidation	Nightly process promotes frequently-used STM to LTM
Prediction Error	Only surprising (novel) information gets stored — redundant input is gated
Spreading Activation (Collins & Loftus, 1975)	Retrieving a memory co-activates related memories through an associative graph
HyDE (Gao et al., 2022)	Hypothetical document embeddings improve semantic recall
Prospective Memory (Einstein & McDaniel, 1990)	Context-triggered intentions fire when cue conditions match
Metacognition	Guard system checks past errors before acting
Cognitive Dissonance (Festinger, 1957)	Detects and verbalizes conflicts between old and new knowledge
Theory of Mind	Models user behavior, preferences, and mood
Synaptic Pruning	Automated cleanup of weak, unused memories
Associative Memory	Semantic search finds related concepts, not just matching words
Memory Reconsolidation	Dreaming process discovers hidden connections during sleep

New in v1.5.0

Modular Package Architecture

The two largest files have been decomposed into focused, testable modules while maintaining full backwards compatibility.

db/ package (11 modules)

core, fts, schema, sessions, reminders, learnings, credentials, tasks, entities, episodic, evolution. All re-exported via __init__.py — existing imports unchanged.

cognitive/ package (6 modules)

core, search, ingest, decay, trust, memory. Each module is independently testable. The search pipeline chains: embed → BM25 → temporal boost → KG boost → rerank.

KG-Boosted Search

Memories with more Knowledge Graph connections rank higher. Logarithmic boost bridges semantic (vector) and structural (graph) retrieval.

HNSW Vector Indexing

Optional hnswlib integration. Auto-activates at 10,000+ memories for sub-millisecond approximate nearest neighbor search. Graceful fallback to brute-force.

Claim Graph

Decompose blob memories into atomic verifiable claims. Each claim has provenance, confidence, and verification status. Contradiction detection across sources.

24 Pytest Tests

Migrations, CRUD, cosine similarity, KG boost, graph traversal, temporal boost. Each test uses isolated temp databases — zero interference with production.