REST API Reference
Relevant source files
The following files were used as context for generating this wiki page:
The CORTEX REST API provides a programmatic interface for interacting with the synthetic cognition infrastructure. It enables AI agents and external applications to manage episodic and procedural memories, perform hybrid semantic searches, trigger maintenance cycles, and visualize cognitive graphs.
The server operates on port 3100 by default and exposes endpoints under the /api/v1 prefix. It handles memory ingestion through a pipeline that includes chunking, embedding, and hippocampal encoding. Retrieval utilizes a 7-factor hybrid scoring system to ensure contextually relevant memory recall.
Sources: src/index.ts:16-17, README.md:126-127, paper/drafts/cortex-v2-4-technical-note.md:31-35
Core API Endpoints
The API is organized into functional modules including Search, Ingest, Dream, and Graph.
Memory Retrieval and Search
CORTEX uses a hybrid scoring system for search, combining semantic similarity, text matching, recency, resonance, and priority.
| Endpoint | Method | Description |
|---|---|---|
/api/v1/search | POST | Performs a hybrid 7-factor search across all memories. |
/api/v1/recall | POST | Budget-aware context retrieval based on token limits. |
Sources: src/index.ts:25-26, README.md:175-177, src/mcp/server.ts:68-80
Memory Ingestion
The ingestion process transforms raw content into indexed memory nodes.
| Endpoint | Method | Description |
|---|---|---|
/api/v1/ingest | POST | Stores new content. Chunks, embeds, and runs hippocampal encoding. |
The ingestion pipeline ensures that new memories are separated from similar existing patterns using Dentate Gyrus (DG) sparse coding and prioritized based on CA1 novelty detection.
Sources: src/index.ts:27, src/mcp/server.ts:311-344, src/ingestion/ingest-markdown.ts:86-105
Cognitive Maintenance and Evolution
Dream Cycles
The dream endpoint triggers maintenance tasks that simulate Slow-Wave Sleep (SWS) and Rapid Eye Movement (REM).
| Endpoint | Method | Description |
|---|---|---|
/api/v1/dream | POST | Triggers resonance analysis, pruning, and consolidation. |
Sources: src/index.ts:36, src/mcp/server.ts:468-472
Memory Reconsolidation
Reconsolidation allows the system to update existing memories within a "labile window" (typically one hour after recall).
| Endpoint | Method | Description |
|---|---|---|
/api/v1/reconsolidate | POST | Updates a previously recalled memory with new information. |
/api/v1/reconsolidate/labile | GET | Lists memories currently open for modification. |
Sources: src/index.ts:28-29, src/mcp/server.ts:639-652
Visualization and Diagnostics
Graph API
The graph endpoint returns a 3D visualization-ready representation of the memory network, including nodes and synapses.
| Parameter | Type | Description |
|---|---|---|
agentId | string | Required. The external ID of the agent. |
limit | number | Max nodes to return (Default: 15000, Max: 50000). |
Sources: src/api/graph.ts:64-75, src/index.ts:35
The graph response includes a stats object containing driftScore, health, and sourceBreakdown to monitor the agent's cognitive integrity.
Sources: src/api/graph.ts:169-204
Summary of Shared Parameters
Most endpoints require an agentId to ensure multi-agent isolation.
| Key | Default | Description |
|---|---|---|
agentId | "arlo" | Identifier for the specific agent's memory store. |
priority | 2 | Importance level (0=critical, 4=ephemeral). |
sourceType | "api" | Label for the origin of the data (e.g., markdown, telegram). |
Sources: src/mcp/server.ts:315-325, src/api/graph.ts:65
The REST API serves as the primary integration layer for non-MCP clients, providing full access to the CORTEX v2 cognitive architecture. It supports high-scale operations, managing thousands of active memories and millions of synapses per agent.
Sources: README.md:46-52, src/index.ts:40-54