Database Schema & Models

Relevant source files

The following files were used as context for generating this wiki page:

• src/db/schema.ts
• src/db/index.ts
• src/mcp/server.ts
• src/dream/dream-cycle.ts
• src/api/graph.ts
• README.md

CORTEX uses a PostgreSQL database with the pgvector extension to store and manage synthetic cognition. The system organizes data into 16 tables that represent different cognitive layers, including episodic memory, associative synapses, hippocampal sparse codes, and emotional valence. This architecture enables hybrid search, dream-cycle consolidation, and belief reconsolidation.

Sources: README.md:255-257, src/db/index.ts:50-51

Core Architecture

The database serves as the long-term memory store for AI agents. It integrates vector similarity search with relational metadata to support 7-factor hybrid scoring. The schema includes specialized tables for neuroscience-inspired features like pattern separation (Dentate Gyrus) and emotional salience.

Entity Relationship Diagram

This diagram shows the primary relationships between agents, episodic memory nodes, and their associated cognitive attributes.

Memory Storage Layer

The storage layer contains the primary episodic and associative data structures.

Memory Nodes

memory_nodes stores discrete chunks of information. Each node contains raw text, a 1024-dimensional vector embedding, and temporal validity metadata (valid_from, valid_until).

Field	Type	Description
content	text	The raw text of the memory.
embedding	vector(1024)	VoyageAI or OpenAI vector representation.
priority	integer	Importance level (P0-P4).
resonance_score	real	Stability-adjusted score for decay calculations.
status	varchar	Lifecycle state: active, archived, or deleted.

Sources: src/db/schema.ts:46-77, src/db/index.ts:109-112

Memory Synapses

memory_synapses represents associative connections between memories. The system uses these to calculate connectivity scores and perform CA3 pattern completion.

• Connection Types: causal, temporal, semantic, entity_shared.
• Decay: Synapses have a decay_rate and connection_strength that changes during dream cycles.

Sources: src/db/schema.ts:93-108, src/dream/dream-cycle.ts:223-238

Neuro-Cognitive Layers

CORTEX implements specific tables to handle hippocampal modeling and emotional context.

Hippocampal Codes

This table stores sparse representations generated by the Dentate Gyrus (DG) model. It uses sparse_indices and sparse_values to enable pattern separation, ensuring similar inputs do not confuse the agent.

export const hippocampalCodes = pgTable("hippocampal_codes", {
  id: serial("id").primaryKey(),
  memoryId: integer("memory_id").references(() => memoryNodes.id).notNull().unique(),
  sparseIndices: integer("sparse_indices").array().notNull(),
  sparseValues: real("sparse_values").array().notNull(),
  sparseDim: integer("sparse_dim").default(4096),
  noveltyScore: real("novelty_score"),
});

Sources: src/db/schema.ts:122-140, src/db/index.ts:58-69

Emotional Valence

emotional_valence tracks 6D emotional vectors for every memory. These dimensions affect memory salience and recall priority.

• Dimensions: Valence, Arousal, Dominance, Certainty, Relevance, Urgency.
• Impact: High intensity or decay_resistance prevents memories from being pruned during sleep.

Sources: src/db/schema.ts:149-165, src/db/index.ts:71-87

Data Flow: Memory Ingestion

When the cortex_ingest tool runs, the system populates several tables in a specific sequence to ensure cognitive integrity.

Performance Optimization & Indexing

CORTEX utilizes specialized indexes to handle large-scale memory retrieval and background maintenance.

• Vector Search: Uses hnsw index on memory_nodes(embedding) with vector_cosine_ops.
• Sparse Codes: Uses GIN index on hippocampal_codes(sparse_indices).
• Search Filtering: Composite index on (agent_id, status, priority) to speed up hybrid queries.
• Synapse Traversal: Composite indexes on (memory_a, connection_strength) and (memory_b, connection_strength).

Sources: src/db/index.ts:117-128

Background & State Tables

These tables support autonomous reasoning and social modeling.

• procedural_memories: Stores skills and workflows with success_rate and execution_count.
• cognitive_artifacts: Logs structured insights, decisions, and consolidation results from dream cycles.
• relationship_graph: Tracks contact history and personality_model for individual entities.
• dream_cycle_logs: Stores statistics from nightly resonance analysis and pruning phases.

Sources: src/db/schema.ts:182-260, src/api/graph.ts:118-135

Conclusion

The CORTEX database schema provides a multi-layered structure that moves beyond simple vector storage. By linking episodic nodes with sparse codes, emotional valence, and associative synapses, the database enables a cognitive architecture that learns, forgets, and evolves based on neuroscience principles.