MCP Tools Reference
Relevant source files
The following files were used as context for generating this wiki page:
The CORTEX v2 MCP Server exposes memory operations as native tools for AI agents. It provides a standard interface for tools like cortex_search, cortex_recall, and cortex_ingest via the Model Context Protocol (MCP). This architecture allows agents to interact with a cognitive memory system that supports hippocampal encoding, emotional valence, and autonomous dream cycles.
Sources: src/mcp/server.ts:1-12, README.md:129-132
Architecture Overview
The MCP server runs as a Node.js process using the @modelcontextprotocol/sdk. It utilizes StdioServerTransport to communicate with MCP-compatible clients such as Claude Code or Cursor. Every tool call initiates a database connection through Drizzle ORM and interacts with PostgreSQL and pgvector for storage and retrieval.
Agent Resolution
Before executing most tools, the server resolves an agent by its externalId. If the agent does not exist in the agents table, the system automatically creates a new record.
Sources: src/mcp/server.ts:40-61, package.json:57-58
Interaction Flow
The following diagram illustrates how an MCP client interacts with the CORTEX toolset and underlying memory subsystems.
The diagram shows the request flow from the client through the MCP server to specific CORTEX subsystems and the database.
Sources: src/mcp/server.ts:65-90, README.md:61-75
Core Memory Tools
These tools handle the fundamental operations of session initialization, information storage, and context retrieval.
cortex_init
Initializes a CORTEX session by loading the top 20 most relevant active memories, system statistics (memory count, synapse count, resonance), and active entities. You should call this at the start of every agent session.
Sources: src/mcp/server.ts:211-309
cortex_search
Performs a hybrid search across memory nodes using a 7-factor scoring system. It combines semantic cosine similarity, exact text matches, recency (30-day half-life), resonance scores, priority boosts, and emotional boosts.
Sources: src/mcp/server.ts:65-156, paper/drafts/cortex-v2-4-technical-note.md:88-95
cortex_ingest
Processes new content into memory. This tool triggers the full ingestion pipeline:
- Chunking: Splits text into manageable parts.
- Embedding: Generates vector representations.
- Hippocampal Encoding: Performs Dentate Gyrus pattern separation and CA1 novelty detection.
- Emotional Analysis: Attaches valence and arousal vectors.
- Synapse Formation: Connects the new memory to existing nodes in the graph.
Sources: src/mcp/server.ts:312-383, src/ingestion/ingest-markdown.ts:80-136
Summary Table: Core Tools
| Tool | Primary Function | Key Parameters |
|---|---|---|
cortex_init | Bootstraps agent session context | agent_id |
cortex_search | Hybrid multi-factor retrieval | query, limit, verbose |
cortex_recall | Budget-aware context loading | query, token_budget |
cortex_ingest | Stores new episodic memory | content, priority, source_type |
Sources: src/mcp/server.ts:65-400
Memory Evolution and Reconsolidation
CORTEX supports belief updating rather than simple appending through a "labile window" mechanism.
cortex_labile
Lists memories that were recalled within the last hour. These memories are currently in a "labile" state and can be modified.
Sources: src/mcp/server.ts:616-640, README.md:86-89
cortex_reconsolidate
Updates a recently recalled memory with new information. If the memory is within its one-hour labile window, this tool updates the content and increments the resonance score. The system preserves the original content as an audit trail artifact.
Sources: src/mcp/server.ts:589-613, benchmarks/cogbench/client.ts:245-255
The sequence shows how a search operation opens a window for a subsequent reconsolidation update.
Sources: src/mcp/server.ts:589-613, README.md:162-166
Procedural Memory (Skills)
Procedural tools manage skills, workflows, and heuristics in a separate layer from episodic memories.
- cortex_skill_store: Saves a repeatable process or workflow. It tracks trigger context and specific execution steps.
- cortex_skill_retrieve: Finds relevant skills for a current task context. It returns proficiency levels and success rates.
- cortex_skill_executed: Updates the success rate and proficiency of a skill after application.
- cortex_skill_refine: Updates existing skills with improved steps or context.
Sources: src/mcp/server.ts:643-706
Self-Awareness and Metacognition
These tools (Phases 1-6) provide autonomous cognition and self-monitoring capabilities.
| Tool | Category | Description |
|---|---|---|
cortex_self_check | Proprioception | Runs diagnostics on operational health and drift. |
cortex_dream | Maintenance | Triggers resonance analysis and adaptive pruning. |
cortex_bg_thread | Cognition | Runs strategic, operational, or relational reasoning. |
cortex_reason | Metacognition | Records structured decision traces with pros/cons. |
cortex_audit | Metacognition | Performs weekly checks for bias and consistency. |
cortex_observe | Perception | Analyzes screen state to understand principal context. |
Sources: src/mcp/server.ts:403-820, src/dream/dream-cycle.ts:38-66
cortex_dream Configuration
The cortex_dream tool allows for granular control over the synthetic sleep cycle. Users can specify the cycle_type:
full: Runs all SWS and REM phases.resonance_only: Updates Ebbinghaus decay scores.pruning_only: Removes low-resonance, non-salient memories.consolidation_only: Clusters related high-resonance memories.
Sources: src/mcp/server.ts:425-452, src/dream/dream-cycle.ts:47-50
Conclusion
The MCP Tools Reference defines the primary interaction point between AI agents and the CORTEX cognitive architecture. By providing tools that handle episodic storage, procedural learning, and metacognitive auditing, CORTEX enables agents to maintain long-term identity and operational efficiency across multiple sessions.
Sources: README.md:20-30, src/mcp/server.ts:854-860