Model Context Protocol (MCP)
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) implementation in CORTEX exposes the cognitive architecture's internal operations as native tools for AI agents. It allows MCP-compatible clients, such as Claude Code, Cursor, and Windsurf, to interact directly with long-term episodic memory, procedural skills, and autonomous cognition subsystems.
The MCP server acts as a bridge between the TypeScript-based CORTEX flagship and external Large Language Model (LLM) interfaces. It converts complex neuroscience-grounded logic—including hippocampal encoding, dream cycles, and memory reconsolidation—into standardized tool calls that an agent can invoke during a session.
Sources: README.md:120-125, src/mcp/server.ts:4-10
Architecture and Integration
CORTEX uses the @modelcontextprotocol/sdk to implement a Stdio-based server. The server initializes a connection to the PostgreSQL database using Drizzle ORM and exposes a suite of over 20 specialized tools.
System Interaction Flow
The following sequence diagram illustrates how an LLM agent interacts with CORTEX via the MCP server to search for and retrieve information.
The diagram shows the synchronous flow of a search request, including embedding generation and database interaction.
Sources: src/mcp/server.ts:16-55, src/mcp/server.ts:60-150, package.json:56-60
Configuration
To enable CORTEX tools in an agent, you must add the server to the agent's .mcp.json configuration file. The server requires environment variables for the database connection and embedding API keys.
{
"mcpServers": {
"cortex": {
"command": "npx",
"args": ["tsx", "/path/to/cortex/src/mcp/server.ts"],
"env": {
"DATABASE_URL": "your-postgresql-url",
"VOYAGE_API_KEY": "your-key"
}
}
}
}
Sources: README.md:273-286
Core Memory Tools
The core tools manage the lifecycle of episodic memories, covering initialization, ingestion, and multi-factor retrieval.
Memory Ingestion Pipeline
When an agent calls cortex_ingest, the system processes content through several cognitive layers before storage.
The flowchart depicts the transformation of raw text into a multi-dimensional memory node with synaptic connections.
Sources: src/mcp/server.ts:411-482, src/ingestion/ingest-markdown.ts:80-140
Retrieval Scoring
CORTEX uses a 7-factor hybrid scoring system to ensure relevant and timely recall. The cortex_search tool implements this logic directly in SQL.
| Factor | Weight | Purpose |
|---|---|---|
| Cosine Similarity | 0.45 | Semantic relevance via vector embeddings |
| Text Match | 0.18 | Exact keyword hits via ILIKE patterns |
| Recency | 0.12 | Exponential decay (30-day half-life) |
| Resonance | 0.10 | Importance based on connectivity and access |
| Priority Boost | 0.05 | Manual importance weighting (P0 to P4) |
| Emotional Boost | 0.10 | Recall boost for high-intensity valence |
Sources: src/mcp/server.ts:74-106, paper/drafts/cortex-v2-4-technical-note.md:65-75
Advanced Cognitive Tools
CORTEX provides tools for self-awareness, skill management, and memory evolution, mapping to Phases 1 through 6 of its cognitive architecture.
Memory Evolution and Reconsolidation
Memories in CORTEX are not static. The cortex_reconsolidate tool allows agents to update existing memories if they were recalled within the last hour (the "labile window").
cortex_labile: Lists memories currently open for modification.cortex_reconsolidate: Updates a memory, preserving the original version as an audit trail.
Sources: src/mcp/server.ts:776-831, paper/drafts/cortex-v2-4-technical-note.md:85-90
Procedural Memory (Skills)
Agents use procedural tools to store and execute repeatable workflows. Proficiency increases as the agent records successful executions.
cortex_skill_store: Teaches the agent a new skill or heuristic.cortex_skill_retrieve: Finds relevant procedures for a current task.cortex_skill_executed: Records success or failure to update proficiency.
Sources: src/mcp/server.ts:834-905
Autonomous Cognition and Dream Cycles
The cortex_dream tool triggers synthetic sleep cycles to maintain the memory network. It executes Slow-Wave Sleep (SWS) for pruning and consolidation, and Rapid Eye Movement (REM) for free association and synthesis of new insights.
cortex_bg_thread: Runs background reasoning threads (Strategic, Operational, or Relational).cortex_synthesize: Generates novel insights from recent synaptic connections.cortex_self_check: Runs diagnostic checks for behavioral drift and operational health.
Sources: src/mcp/server.ts:515-525, src/mcp/server.ts:634-666, src/dream/dream-cycle.ts:38-115
Conclusion
The Model Context Protocol implementation serves as the primary interface for AI agents to leverage the CORTEX cognitive architecture. By exposing high-level cognitive functions as standardized tools, it enables agents to maintain long-term identity, update beliefs through reconsolidation, and improve performance via procedural learning and nightly dream cycles.
Sources: README.md:120-125, src/mcp/server.ts:930-945