---
title: "Cortex"
tagline: "Agent runtime"
language: "Go"
license: "Apache-2.0"
since: "2026"
canonical: "https://xraph.com/work/cortex"
---

# Cortex

An agent framework that describes an agent the way you would describe a colleague: what they can do, how they think, how they talk, what they notice, and what they habitually do when something happens. Runs, steps and tool calls are tracked end to end, checkpoints pause a run for human approval, and memory is scoped per agent per tenant.

## Install

```bash
go get github.com/xraph/cortex
```

## What it is

Cortex is a Go framework for building agents that are described the way you would describe a colleague, rather than as a single long system prompt. An agent is composed from primitives that can be versioned, swapped and evaluated independently.

## The human model

- **Skill**: what it can do. Tool bindings, knowledge references, proficiency levels.
- **Trait**: who it is. Bipolar personality dimensions with influences on behaviour.
- **Behaviour**: what it habitually does. Trigger-action patterns with priorities.
- **Cognitive style**: how it thinks. Phase chains, strategies, transition rules.
- **Communication style**: how it speaks. Tone, formality, verbosity, adaptation.
- **Perception**: what it notices. Attention filters and context windows.
- **Persona**: a composition of the six, reusable across agents.

The reason for the decomposition is maintenance. A 900-line system prompt cannot be tested, nobody can say which paragraph is load-bearing, and fixing one behaviour reliably breaks another. Each primitive here can be evaluated against a Sentinel suite on its own.

## Execution and state

Runs, steps and tool calls are tracked through a state machine with full observability. Memory is split into conversation history, bounded working memory and summaries, scoped per agent per tenant. Checkpoints are human-in-the-loop approval gates that pause a run until someone acts.

Identifiers are TypeIDs: twelve type-prefixed, UUIDv7-based and K-sortable, so an id in a log line tells you what it refers to and roughly when it was created.

## Extending it

Sixteen lifecycle hooks with type-cached dispatch, so an unimplemented hook costs nothing. Two extensions ship in-tree: Prometheus-compatible metrics with eleven counters, and a structured audit trail covering eighteen actions across eight resource types.

Storage is a composite interface of eight sub-interfaces. A production PostgreSQL store using bun with embedded migrations, and an in-memory store for tests, both satisfy it.

## Where it fits

Cortex handles the episode. KGKit handles what survives it. At episode close, conclusions are emitted as typed claims carrying the observations they rest on, and written into the graph as revisable edges. Weave supplies retrieval, Nexus routes the provider traffic, Shield scans input and output, and Sentinel evaluates the result.

---

*Unpublished draft. Not peer reviewed and not submitted to a venue.*


## Anatomy

- **Primitives**: Skills, traits, behaviours, cognitive and communication styles, perception.
- **Personas**: A switchable identity composing the other six.
- **Run state**: Runs, steps and tool calls, each transition recorded.
- **Checkpoints**: Human-in-the-loop gates at declared decision points.

## Constraints and trade-offs

- (decision) Personality is structured parameters, not prose. A paragraph cannot be queried, composed or A/B tested.
- (constraint) Every operation carries tenant and application scope; the store layer enforces it.
- (known gap) Traits and cognitive styles are static. The architecture supports updating them; the feedback loop is not built.