System Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
CORTEX is a cognitive architecture for AI agents grounded in computational neuroscience. It provides a synthetic cognition infrastructure that enables agents to learn, consolidate, and evolve beliefs rather than simply performing vector search. The system models the mammalian hippocampal-cortical circuit to handle memory encoding, novelty detection, and long-term consolidation.
Sources: README.md:1-15, paper/drafts/cortex-v2-4-technical-note.md:14-20
Memory Processing Pipeline
The architecture processes incoming information through a multi-stage ingestion pipeline. This pipeline transforms raw data into a structured cognitive representation including dense embeddings, sparse hippocampal codes, and emotional valence vectors.
The ingestion process involves chunking text, generating embeddings, and performing hippocampal encoding via the Dentate Gyrus (DG) and CA1 subregions.
Sources: README.md:95-105, src/ingestion/ingest-markdown.ts:86-125
Hippocampal Encoding
CORTEX implements biological hippocampal functions to manage memory interference and novelty.
- Dentate Gyrus (DG): Performs pattern separation by projecting 1024-dimensional dense embeddings into a 4096-dimensional sparse space with 5% sparsity. This ensures similar inputs result in distinct sparse codes.
- CA1 Novelty Detection: Compares new sparse codes against existing memories. High novelty increases the resonance floor and priority of the memory.
- CA3 Pattern Completion: During retrieval, the system uses recurrent activation through the synapse graph to converge on full memory patterns from partial cues.
Sources: paper/drafts/cortex-v2-4-technical-note.md:37-56, REFERENCES.md:14-50
Hybrid Retrieval System
CORTEX utilizes a 7-factor hybrid scoring system for memory recall. This system balances semantic relevance with temporal factors, emotional weight, and associative strength.
| Factor | Weight | Description |
|---|---|---|
| Cosine Similarity | 0.45 | Semantic relevance via dense embeddings |
| Text Match | 0.18 | Exact keyword or substring hits |
| Recency | 0.12 | Exponential decay with a 30-day half-life |
| Resonance | 0.10 | Ebbinghaus stability-adjusted importance |
| Emotional Boost | 0.10 | Salience based on 6D emotional vectors |
| Priority Boost | 0.05 | Manual or system-assigned priority (P0 to P4) |
Sources: src/mcp/server.ts:60-84, paper/drafts/cortex-v2-4-technical-note.md:63-75
Dream Cycle and Consolidation
The system performs offline memory maintenance through a two-phase "Dream Cycle," mimicking Slow-Wave Sleep (SWS) and Rapid Eye Movement (REM) sleep.
Sleep Phases
- Resonance Analysis (SWS): Updates memory scores using an Ebbinghaus stability-adjusted forgetting curve. Frequently accessed or highly connected memories decay slower.
- Adaptive Pruning (SWS): Removes or archives low-resonance memories based on percentile thresholds (P5 for deletion, P15 for archiving).
- Consolidation (SWS): Clusters high-resonance memories and generates abstractive summaries using an LLM.
- Free Association (REM): Randomly activates memory nodes to discover novel connections in dense and sparse spaces.
- Synthesis (REM): Generates new insights and cognitive artifacts from recently formed synapses.
Sources: src/dream/dream-cycle.ts:33-100, README.md:136-150, REFERENCES.md:57-105
Core Cognitive Layers
The architecture is distributed across several specialized subsystems that interact via a shared PostgreSQL schema.
Emotional Valence
Every memory node is attached to a six-dimensional emotional vector: Valence, Arousal, Dominance, Certainty, Relevance, and Urgency. High emotional intensity grants decay resistance and recall boosts.
Sources: README.md:118-121, src/mcp/server.ts:316-328
Reconsolidation
Retrieved memories enter a labile window (typically one hour). During this time, the agent can update the memory content. The system preserves the original version as an audit trail while marking the new version as current.
Sources: README.md:123-126, src/mcp/server.ts:586-613
Procedural Memory
Skills and workflows are stored in a decay-resistant layer. The system tracks proficiency through execution counts and success rates, allowing agents to improve specific behaviors over time.
Sources: README.md:131-133, src/mcp/server.ts:646-665
System Interfaces
CORTEX exposes its functionality through two primary interfaces:
- MCP Server: Implements the Model Context Protocol, allowing agents like Claude Code or Cursor to call tools such as
cortex_search,cortex_ingest, andcortex_dream. - REST API: Provides endpoints for graph visualization (
/api/v1/graph), health monitoring, and manual memory operations.
Sources: src/mcp/server.ts:10-25, src/index.ts:25-45, src/api/graph.ts:98-120
CORTEX transforms AI memory from a static retrieval layer into a dynamic, neuroscience-grounded learning system that maintains identity and compounds intelligence through continuous consolidation.
Sources: README.md:20-35