Introduction to CORTEX
Relevant source files
The following files were used as context for generating this wiki page:
CORTEX is a cognitive architecture that provides synthetic cognition infrastructure for AI agents. It functions as a living memory system grounded in computational neuroscience, moving beyond traditional vector databases and RAG pipelines to implement learning, consolidation, and reconsolidation processes. Sources: README.md:1-10, paper/drafts/cortex-v2-4-technical-note.md:15-20
The system models the mammalian hippocampal-cortical circuit to manage long-term agent memory. It enables agents to maintain identity, update beliefs, and improve skills over time through specific subsystems including hippocampal encoding, emotional valence weighting, and synthetic dream cycles. Sources: README.md:20-35, REFERENCES.md:1-5
System Architecture
CORTEX operates through a layered cognitive architecture that processes information from ingestion to long-term consolidation. It utilizes PostgreSQL with the pgvector extension to store episodic and associative data. Sources: README.md:120-135, src/index.ts:35-45
Core Processing Flow
The diagram shows the high-level data flow from input to storage and the subsequent retrieval and maintenance cycles. Sources: README.md:95-115
Subsystem Components
| Component | Function | Biological Analogue |
|---|---|---|
| Dentate Gyrus (DG) | Performs pattern separation via sparse coding to distinguish similar inputs. | Hippocampal DG |
| CA1 | Detects novelty by comparing query embeddings against predicted states. | Hippocampal CA1 |
| CA3 | Executes autoassociative pattern completion for memory recall. | Hippocampal CA3 |
| Dream Cycle | Runs nightly maintenance for resonance analysis, pruning, and consolidation. | SWS/REM Sleep |
| Reconsolidation | Opens a labile window for updating recalled memories with new evidence. | Memory Lability |
Sources: README.md:120-145, paper/drafts/cortex-v2-4-technical-note.md:38-65, REFERENCES.md:10-50
Memory Retrieval and Scoring
CORTEX retrieves memories using a 7-factor hybrid scoring system. This system avoids simple vector proximity by incorporating temporal, emotional, and structural weights. Sources: README.md:218-225, paper/drafts/cortex-v2-4-technical-note.md:73-85
Hybrid Scoring Formula
The retrieval engine calculates relevance using the following linear combination:
- 0.45 * Semantic Similarity (Cosine)
- 0.18 * Text Match (Exact substring)
- 0.12 * Recency (Exponential decay with 30-day half-life)
- 0.10 * Resonance (Ebbinghaus stability-adjusted score)
- 0.10 * Emotional Boost (Based on VAD recall boost)
- 0.05 * Priority Boost (Range P0 to P4)
Sources: src/mcp/server.ts:60-85, paper/drafts/cortex-v2-4-technical-note.md:75-82
CA3 Pattern Completion
During retrieval, CORTEX executes two iterations of recurrent activation through the synapse graph. This process pulls in strongly-connected neighbor memories that might not have high semantic similarity to the query but are contextually related. Sources: paper/drafts/cortex-v2-4-technical-note.md:60-65, REFERENCES.md:35-45
Synthetic Dream Cycle
The Dream Cycle is an offline maintenance process consisting of two stages: Slow-Wave Sleep (SWS) and Rapid Eye Movement (REM). Sources: README.md:231-235, src/mcp/server.ts:380-400
Maintenance Phases
- Resonance Analysis (SWS): Applies Ebbinghaus stability-adjusted decay to all active memories.
- Adaptive Pruning (SWS): Deletes or archives memories based on percentile resonance thresholds (P5/P15) instead of hardcoded values.
- Consolidation (SWS): Clusters high-resonance memories and generates abstractive summaries via LLM.
- Free Association (REM): Randomly activates memory nodes to discover novel cross-domain connections.
- Synthesis (REM): Generates new insights from the synapses formed during free association.
Sources: README.md:238-250, src/mcp/server.ts:385-405, REFERENCES.md:65-85
Integration and Interfaces
CORTEX provides multiple interfaces for agent interaction, primarily through a Model Context Protocol (MCP) server and a REST API. Sources: src/index.ts:15-30, src/mcp/server.ts:20-40
Core API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/api/v1/search | POST | Executes 7-factor hybrid search. |
/api/v1/ingest | POST | Chunks, embeds, and encodes new data. |
/api/v1/recall | POST | Retrieves context within a specific token budget. |
/api/v1/dream | POST | Triggers a manual dream cycle. |
/api/v1/reconsolidate | POST | Updates a memory within its labile window. |
Sources: src/index.ts:40-60, src/mcp/server.ts:45-350
MCP Tools
Agents (such as Claude Code or Cursor) utilize tool calls to interact with CORTEX:
cortex_init: Boots session by loading top memories and system health.cortex_search: Standard hybrid retrieval.cortex_ingest: Stores new content with hippocampal encoding.cortex_procedural_store: Saves repeatable workflows or skills.
Sources: src/mcp/server.ts:45-550, README.md:195-215
Conclusion
CORTEX serves as a specialized cognitive layer that enables AI agents to retain long-term information while maintaining cognitive integrity. By implementing neuroscientific principles like pattern separation and sleep-dependent consolidation, it achieves high retrieval performance on benchmarks like LongMemEval and LoCoMo without requiring expensive LLM reranking. The architecture ensures that agent beliefs remain up-to-date and that important memories are protected from decay. Sources: README.md:40-60, BENCHMARKS.md:5-20, paper/drafts/cortex-v2-4-technical-note.md:150-165