Skip to content
Arka Platform

Developer Documentation — Cortex

Audience: software engineer who wants to integrate Cortex, contribute to the codebase, or understand the internal architecture.

What is Cortex

Section titled “What is Cortex”

Cortex is the knowledge-graph engine behind the Arka platform. It stores, versions, and serves atoms — typed, versioned artefacts that describe agent profiles, skills, governance rules, templates, and project memory. Cortex exposes two consumer surfaces: a REST API (Fastify/Express, port 9096) and a Model Context Protocol (MCP) server (port 3001). A React UI provides visual access to the catalogue and workspace.

The engine follows a strict hexagonal architecture. Domain services depend on ports (interfaces); adapters implement those ports. This separation lets the same business logic serve HTTP clients, LLM agents, and batch scripts without coupling.

Section titled “Recommended guided path”

Pick the path that matches what you need:

I want to integrate Cortex into my system

Section titled “I want to integrate Cortex into my system”
  1. Read reference/rest-api for the HTTP surface.
  2. Read reference/mcp-tools if your consumer is an LLM agent.
  3. Read reference/environment-variables to configure your instance.

I want to deploy Cortex

Section titled “I want to deploy Cortex”
  1. Read deploy/docker-compose for the full self-hosted stack.
  2. Read reference/environment-variables for secrets and tuning.

I want to contribute to Cortex

Section titled “I want to contribute to Cortex”
  1. Start with architecture/ to understand hexagonal layering.
  2. Read architecture/data-model to understand the ATOM model.
  3. Read architecture/ingestion-pipeline to understand the write path.
  4. Read contributing for coding standards and PR workflow.

Table of contents

Section titled “Table of contents”

Architecture

Section titled “Architecture”

architecture/ covers the hexagonal layers, inbound and outbound adapters, domain core, event bus, and composition root.

Data model

Section titled “Data model”

architecture/data-model documents the ATOM model (six layers), HYOS profiles, blocs, taxonomy, and graph edges.

Ingestion pipeline

Section titled “Ingestion pipeline”

architecture/ingestion-pipeline traces the write path from Zod validation to SurrealDB persistence and embedding enrichment.

Reference

Section titled “Reference”

reference/ groups the REST API route list, MCP tool catalogue, and environment variables.

Deployment

Section titled “Deployment”

deploy/ covers the Docker Compose stack, reverse proxy, backups, and health monitoring.

Contributing

Section titled “Contributing”

contributing summarises coding standards, hexagonal rules, and the PR workflow.

Documentation status

Section titled “Documentation status”

This documentation is generated from the arka-cortex source code. Route counts, tool counts, and environment variable lists are verified against the codebase at each update. If you find a discrepancy, it is a bug to report.