Developer Documentation — Cortex

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

---

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.

---

Recommended guided path

Pick the path that matches what you need:

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

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

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

Architecture

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

Data model

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

Ingestion pipeline

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

Reference

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

Deployment

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

Contributing

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

---

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.