Introduction

Cortex is a Go library for building AI agents that think and behave like humans. Instead of hand-crafting system prompts, you declare an agent's skills, traits, behaviors, and persona — the same building blocks that make people unique — and Cortex assembles them into a coherent identity at runtime.

Cortex is a library — not a service. You bring your own LLM provider, database, and HTTP server. Cortex provides the agent orchestration plumbing.

The Human Model

Cortex models AI agents the way you would describe a person:

What it does

• Declarative personality — Define agents via composable Skills, Traits, and Behaviors instead of imperative prompt engineering.
• Persona composition — Bundle skills, traits, behaviors, cognitive style, communication style, and perception into a reusable Persona. Assign it to any agent with one field.
• Execution tracking — Every agent run is recorded as a Run with Steps and ToolCalls, providing full observability into reasoning chains.
• Human-in-the-loop — Checkpoints pause a run for human approval before proceeding with sensitive actions.
• Multi-tenant isolation — Every entity is scoped to a tenant and app via context. Cross-tenant access is structurally impossible.
• Plugin system — 16 lifecycle hooks for metrics, audit trails, tracing, and custom processing. Extensions opt in to only the events they care about.
• Memory management — Conversation history, working memory, and summary memory per agent per tenant.
• PostgreSQL store — Production-ready persistence with embedded migrations and JSONB columns for flexible metadata.
• Forge integration — Drop-in forge.Extension with DI-injected Engine and auto-registered HTTP routes.
• REST API — 36 endpoints for managing agents, personas, skills, traits, behaviors, runs, checkpoints, and memory.

Design philosophy

Library, not service. Cortex is a set of Go packages you import. You control main, the database connection, and the process lifecycle.

Declarative over imperative. You don't tell agents what to do — you tell them who they are. Skills define capabilities, Traits shape personality, Behaviors encode habits. Cortex assembles the system prompt and runtime parameters from these declarations.

Interfaces over implementations. Every subsystem defines a Go interface. Swap any storage backend with a single type change.

Tenant-scoped by design. cortex.WithTenant and cortex.WithApp inject context that is enforced at every layer.

TypeID everywhere. All entities use type-prefixed, K-sortable, UUIDv7-based identifiers (agt_, skl_, trt_, bhv_, prs_, arun_, etc.).

Quick look

package main

import (
    "context"
    "log"

    "github.com/xraph/cortex/engine"
    "github.com/xraph/cortex/extension"
    "github.com/xraph/cortex/store/postgres"
)

func main() {
    ctx := context.Background()

    // Create the store.
    db := connectDB() // your *bun.DB
    pgStore := postgres.New(db)

    // Build the Cortex engine.
    eng, err := engine.New(
        engine.WithStore(pgStore),
    )
    if err != nil {
        log.Fatal(err)
    }

    // Or use as a Forge extension:
    ext := extension.New(
        extension.WithStore(pgStore),
    )
    _ = ext // register with your Forge app
    _ = eng
    _ = ctx
}

Where to go next