cortex AGENTS.md

CortexPrism — AI Agent Operating System

Project Identity

CortexPrism is a self-hosted, open-source AI agent operating system — an autonomous agent runtime that turns any LLM into a capable digital agent. It provides persistent memory, a rich tool ecosystem, sandboxed code execution, multi-agent orchestration, a full-featured web UI, and enterprise-grade security.

• License: Apache 2.0
• Version: 0.53.0 (see deno.json)
• Repository: CortexPrism/cortex on GitHub
• CI: .github/workflows/ci.yml (runs on push to main)

Tech Stack

Layer	Technology
Runtime	Deno 2.x (TypeScript strict mode)
Database	libSQL (SQLite-compatible) via @libsql/client
Testing	Deno test runner
CLI framework	@cliffy/command
LLM SDKs	Anthropic, OpenAI, Google Generative AI, AWS Bedrock
Frontend	Inline SPA (Tailwind CDN, CodeMirror 6, vanilla JS, 78 modular files)
Package manager	Deno import maps (deno.json)

Build & CI Commands

deno task check      # Type-check all files
deno task lint       # Lint all files
deno task fmt        # Format all files (auto-fix)
deno task test       # Run all tests (sets --allow-all)
deno run --allow-all src/main.ts <command>  # Run CLI

CI runs deno fmt --check, deno lint, deno check src/main.ts, deno test --allow-all on ubuntu, macos, and windows.

Package Structure (v0.48.6+)

The codebase is organized into 6 coarse packages under packages/ and a composition root in src/:

packages/
├── core/           — @cortex/core
│   ├── contracts/  — pure interface definitions (ICortexConfig, IDbClient, etc.)
│   └── src/        — config, db, i18n, utils, plugins
├── gate/           — @cortex/gate
│   ├── contracts/
│   └── src/        — security (policy, vault, supervisor), sandbox, vfs
├── ai/             — @cortex/ai
│   ├── contracts/
│   └── src/        — agent, tools, memory, llm, pipeline, skills
├── server/         — @cortex/server
│   ├── contracts/
│   └── src/        — server, hub, channels, a2a, mcp, voice, workspace, codegraph
├── infra/          — @cortex/infra
│   ├── contracts/
│   └── src/        — processes, services, scheduler, ipc, triggers, workflow, observability
└── cli/            — @cortex/cli
    ├── contracts/
    └── src/        — cli commands, tui

src/
├── agent/          — agent loop orchestrator (81 lines)
│   stages/         — 7 pipeline stages (setup, history, assessment, prompt-builder, model-selector, llm-stream, tool-executor)
│   post/           — post-turn modules (response, background, cleanup)
│   helpers/        — shared helpers (preferences, strip-tool-calls, nanoid)
│   pipeline/       — pipeline context
├── server/
│   server.ts       — HTTP server entry (composition root for server)
│   new-router.ts   — route dispatcher (replaced 6,075-line monolith)
│   routes/         — 69 route modules (one per API area)
│   ui/
│   │   mod.ts      — UI assembler (concatenates JS + HTML)
│   │   js/         — 29 concatenated JS modules
│   │   pages/      — 46 page HTML templates
│   │   shared/     — shared utilities
│   │   css.ts      — embedded CSS
│   │   shell.ts    — sidebar/layout HTML
│   │   providers.ts
├── main.ts         — CLI entry point (composition root)
└── tests/          — 30 test files (flat structure)