# CortexPrism — Complete Documentation This file contains the full text of all CortexPrism documentation for LLM ingestion. --- ## CLI Reference ### Agent # `cortex agent` Manage agent configurations that define how Cortex interacts with LLMs. Each agent has a model, provider, system prompt, tools, temperature, and personality (soul). ## Usage ```bash cortex agent [options] ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `list` | List all agent configurations | | `show` | Show details for an agent | | `create` | Create a new agent | | `update` | Update an existing agent | | `delete` | Delete an agent | | `select` | Select the active agent | | `inspect` | Inspect agent configuration in detail | | `import` | Import an agent configuration | ## Create Options | Option | Description | |--------|-------------| | `--description, -d` | Agent description | | `--provider, -p` | LLM provider to use | | `--model, -m` | Model name | | `--temperature, -t` | Response temperature (0.0–2.0) | | `--soul` | Soul/persona to apply | | `--system-prompt` | Custom system prompt | | `--tools` | Comma-separated tool allow-list | | `--tags` | Comma-separated tags | ## Update Options | Option | Description | |--------|-------------| | `--name, -n` | New name for the agent | | `--description, -d` | Updated description | | `--provider, -p` | Change provider | | `--model, -m` | Change model | | `--temperature, -t` | Adjust temperature | | `--soul` | Change soul/persona | | `--system-prompt` | Update system prompt | | `--tools` | Update tool allow-list | | `--tags` | Update tags | ## Examples ```bash # Create a code reviewer agent cortex agent create code-reviewer -m claude-sonnet-4-5 -d "Reviews pull requests" --tools read,write,shell # Create with specific provider cortex agent create data-analyst -p anthropic -m claude-sonnet-4-5 -t 0.7 # List all agents cortex agent list # Show agent details cortex agent show code-reviewer # Update an agent cortex agent update code-reviewer --tools read,shell,search,web # Select the active agent cortex agent select code-reviewer # Delete an agent cortex agent delete old-agent # Inspect agent cortex agent inspect code-reviewer # Import an agent config cortex agent import ``` URL: https://cortexprism.io/docs/cli/agent --- ### Channels # `cortex channels` Manage communication channels that connect Cortex agents to external messaging platforms. Currently supports Discord as a channel provider. ## Usage ```bash cortex channels [options] ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `start ` | Start a communication channel | | `stop ` | Stop a communication channel | ## Channel Architecture The channel system uses a plugin-based architecture where each messaging platform (Discord, etc.) implements the `ChannelPlugin` interface. Channels are bound to specific agents, routing incoming messages to the agent and sending agent responses back. ### Supported Channel Targets | Target Type | Description | |-------------|-------------| | `dm` | Direct message with a user | | `group` | Group message / multi-user chat | | `channel` | Discord server channel | | `thread` | Thread within a channel | ### Message Features - Rich embeds with fields and footers - File attachment support - Message edits and deletions - Typing indicator support - Reaction handling ## Discord Channel The Discord integration connects via Gateway WebSocket with heartbeat keep-alive. Messages are processed through prefix-based handling. ```bash # Start Discord channel cortex channels start # Stop Discord channel cortex channels stop ``` ## Channel Events Channels emit events that flow through the system: - `message` — New incoming message - `reaction` — Reaction added/removed - `edit` — Message edited - `delete` — Message deleted - `typing` — User started typing ## Examples ```bash # Start the Discord channel integration cortex channels start # Stop all active channels cortex channels stop ``` URL: https://cortexprism.io/docs/cli/channels --- ### Chat # `cortex chat` Start an interactive streaming chat session with any supported LLM provider. This is the primary interface for interacting with the CortexPrism agent. ## Usage ```bash cortex chat [options] cortex chat -m gpt-4o # Override model cortex chat -s sess_abc123 # Resume an existing session cortex chat --resume sess_abc123 # Resume (long flag) cortex chat --no-stream # Disable streaming output cortex chat -p anthropic # Select provider cortex chat -a code-reviewer # Use a specific agent cortex chat --list-agents # List available agents ``` ## Options | Option | Description | |--------|-------------| | `--model, -m` | Override the default model for this session | | `--provider, -p` | Select a specific provider | | `--agent, -a` | Use a specific agent configuration | | `--resume, -s` | Resume an existing session by ID | | `--no-stream` | Disable streaming output (print complete response at once) | | `--list-agents` | List all available agents | | `--help` | Show help for this command | ## Slash Commands Inside the chat session, the following slash commands are available: | Command | Description | |---------|-------------| | `/exit` | Quit the session | | `/quit` | Quit the session | | `/help` | Show available slash commands | | `/soul` | Access soul/persona management | ## Tool Integration When tools are enabled, the agent can: - **Read files** using `file_read` tool - **Execute shell commands** with approval gates - **Search the web** via DuckDuckGo - **Execute code** in sandboxed environments ## Session Persistence Each chat session creates a per-session SQLite database (`sess_*.db`) that stores full message history. Sessions can be resumed later using `--resume` or the interactive session browser via `cortex sessions`. ## Agent Loop Flow ``` User types message → memory retrieval (FTS5 + vector search) → memory injection into system prompt → LLM call (stream or complete) → parse tool calls from response → validate through Parallax security → execute approved tools → re-prompt LLM with results → persist response to session history → write episodic memory summary (async) → per-turn reflection (async, if enabled) ``` ## Examples ```bash # Start a basic chat session with default provider cortex chat # Use a specific model cortex chat -m claude-sonnet-4-5 # Resume a previous session cortex chat -s sess_a1b2c3d4 # Use a specific agent cortex chat -a code-reviewer # Chat without streaming cortex chat --no-stream ``` URL: https://cortexprism.io/docs/cli/chat --- ### Daemon # `cortex daemon` Manage the background daemon supervisor and its child processes. The daemon system provides persistent process management for tool validation, execution, and job scheduling. ## Managed Processes The supervisor manages three daemon processes: | Process | Socket | Description | |---------|--------|-------------| | **Validator** | `/tmp/cortex/validator.sock` | Approves/rejects tool intents via security policy checks | | **Executor** | `/tmp/cortex/executor.sock` | Executes approved tool calls (file ops, shell commands, directory listing) | | **Scheduler** | `/tmp/cortex/scheduler.sock` | Runs cron jobs and periodic memory consolidation | ## Usage ```bash cortex daemon start # Start supervisor + all daemons in background cortex daemon stop # Stop all daemon processes cortex daemon restart # Restart all daemon processes cortex daemon run # Run supervisor in foreground (for systemd/tmux) cortex daemon status # Show running/stopped status for each daemon ``` ## Options | Option | Description | |--------|-------------| | `--help` | Show help for this command | ## Auto-Start Behavior `cortex chat` and `cortex serve` automatically call `ensureDaemons()` which pings the validator socket and starts the supervisor if needed. ## Supervision Loop - Each child is spawned via `Deno.Command` with scoped `--allow-*` permissions - On crash (non-zero exit), supervisor waits `min(2^n × 1s, 30s)` then restarts with exponential backoff - On clean exit (zero exit), process is not restarted - `SIGINT`/`SIGTERM` triggers cascading shutdown of all children ## IPC Protocol All daemons communicate via Unix domain sockets: ``` /tmp/cortex/validator.sock /tmp/cortex/executor.sock /tmp/cortex/scheduler.sock ``` Messages are JSON-line format, connection-per-message. Heartbeat pings check liveness. ## `cortex stop` Also stops daemon processes: ```bash cortex stop # Stop server + daemons cortex stop --server-only # Stop only the HTTP server cortex stop --daemon-only # Stop only the daemon processes ``` ## Examples ```bash # Start all daemon processes cortex daemon start # Check daemon status cortex daemon status # Run supervisor in foreground (for systemd integration) cortex daemon run # Stop all daemons cortex daemon stop # Stop only server, keep daemons running cortex stop --daemon-only ``` URL: https://cortexprism.io/docs/cli/daemon --- ### Desktop # `cortex desktop` Cross-platform desktop automation that provides agent tools for GUI interaction. Supports screenshots, mouse actions, keyboard input, and clipboard management across Linux, macOS, and Windows. ## Usage ```bash cortex desktop [options] ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `dockerfile` | Generate a Dockerfile for containerized desktop automation | | `entrypoint` | Generate an entrypoint script for the desktop container | | `screenshot` | Capture a screenshot (PNG or JPEG) | | `click` | Mouse click at specified coordinates | | `type` | Type text at the current focus | | `clipboard` | Read or write clipboard contents | ## Platform Backends | Platform | Backend | |----------|---------| | **Linux** | `xdotool` (mouse/keyboard), `import` (screenshots), `xclip` (clipboard) | | **macOS** | AppleScript + `screencapture` | | **Windows** | PowerShell + Win32 APIs (`Add-Type` for GDI) | ## Desktop Actions | Action | Description | |--------|-------------| | `screenshot` | Capture screen (PNG/JPEG format) | | `click` | Single mouse click | | `dblclick` | Double mouse click | | `type` | Type text string | | `keypress` | Press a key with optional modifiers | | `drag` | Mouse drag from point to point | | `get_clipboard` | Read clipboard text | | `set_clipboard` | Write text to clipboard | | `wait` | Wait specified milliseconds | | `move` | Move mouse to coordinates | | `scroll` | Scroll mouse wheel | ## Containerized Execution Desktop automation can run in Docker containers using the generated Dockerfile and entrypoint scripts. This provides isolation and reproducibility for GUI automation tasks. ## Examples ```bash # Capture a screenshot cortex desktop screenshot # Generate Dockerfile for containerized desktop automation cortex desktop dockerfile # Generate entrypoint script cortex desktop entrypoint ``` URL: https://cortexprism.io/docs/cli/desktop --- ### Discord # `cortex discord` Run a Discord bot that connects Cortex agents to Discord servers. The bot responds to messages using Cortex agents, providing AI-powered chat directly in Discord channels. ## Usage ```bash cortex discord [options] ``` ## Options | Option | Description | |--------|-------------| | `--token, -t` | Discord bot token | | `--prefix` | Command prefix for bot messages (default: `!cortex`) | | `--model, -m` | Model to use for Discord responses | | `--help` | Show help for this command | ## Setup 1. Create a Discord application at https://discord.com/developers 2. Add a bot to your application 3. Copy the bot token 4. Invite the bot to your server with appropriate permissions ## Configuration The Discord bot token is passed via the `--token` flag or the `DISCORD_BOT_TOKEN` environment variable. It is not stored in the Cortex config file. ## Examples ```bash # Start the Discord bot cortex discord -t # Start with custom prefix cortex discord -t --prefix "!agent" # Start with specific model cortex discord -t -m gpt-4o ``` URL: https://cortexprism.io/docs/cli/discord --- ### Eval # `cortex eval` A comprehensive evaluation framework for benchmarking agent performance. Run suites of tasks across 8 task categories with pattern matching, file verification, and tool sequence validation. Supports regression detection against baseline runs. ## Usage ```bash cortex eval [options] ``` ## Options | Option | Description | |--------|-------------| | `--suite, -s` | Evaluation suite to run | | `--baseline, -b` | Baseline run for regression comparison | | `--model, -m` | Model to use for evaluation | | `--save-baseline` | Save current results as baseline for future comparison | | `--help` | Show help for this command | ## Task Categories | Category | Description | |----------|-------------| | `code_generation` | Generate code from natural language prompts | | `bug_fix` | Fix bugs in provided code | | `refactoring` | Refactor code for improved structure | | `code_review` | Review code and provide feedback | | `shell_command` | Generate and execute correct shell commands | | `file_operation` | Perform file system operations | | `search_retrieval` | Search and retrieve information | | `tool_use_sequence` | Execute multi-step tool sequences | ## Scoring Methods | Method | Description | |--------|-------------| | **Regex patterns** | Match response against expected patterns | | **Contains/not_contains** | Check for presence or absence of strings | | **Fuzzy matching** | Approximate string matching for tolerance | | **File content verification** | Verify file contents after execution | | **Exit code checking** | Validate command exit codes | | **Tool sequence validation** | Verify correct tool call ordering | ## Regression Detection Compare current evaluation runs against previous baselines: - `RegressionCheck.previousScore` — Score from baseline run - `RegressionCheck.degraded` — Flag if performance dropped - Per-category pass/fail and average score breakdowns ## Examples ```bash # Run an evaluation suite cortex eval -s code-generation # Run with a specific model cortex eval -s bug-fix -m claude-sonnet-4-5 # Compare against a baseline cortex eval -s refactoring -b baseline-run-001 # Save current results as new baseline cortex eval -s code-review --save-baseline ``` URL: https://cortexprism.io/docs/cli/eval --- ### Git # `cortex git` Full git porcelain interface executed through the Cortex agent workspace. Ten subcommands provide complete git version control with agent-powered commit messages and branch management. ## Usage ```bash cortex git [options] ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `status` | Show working tree status | | `log` | Show commit history | | `diff` | Show changes between commits or working tree | | `add` | Stage files for commit | | `commit` | Create a new commit | | `push` | Push commits to remote | | `pull` | Pull changes from remote | | `clone` | Clone a repository | | `branch` | List or manage branches | | `remote` | Manage remote repositories | ## Subcommand Details ### `cortex git status` ```bash cortex git status # Show working tree status ``` ### `cortex git log` ```bash cortex git log # Show commit history cortex git log --limit 20 # Limit to 20 entries ``` ### `cortex git diff` ```bash cortex git diff # Show unstaged changes cortex git diff --stat # Show diff statistics cortex git diff --file path/to/file # Diff a specific file ``` ### `cortex git add` ```bash cortex git add path/to/file # Stage a specific file cortex git add --all # Stage all changes ``` ### `cortex git commit` ```bash cortex git commit # Create commit with message cortex git commit --all # Stage all and commit ``` ### `cortex git push` ```bash cortex git push # Push to default remote cortex git push --remote origin # Specify remote cortex git push --branch main # Specify branch ``` ### `cortex git pull` ```bash cortex git pull # Pull from default remote cortex git pull --remote origin # Specify remote cortex git pull --branch main # Specify branch ``` ### `cortex git clone` ```bash cortex git clone # Clone a repository cortex git clone --branch main # Clone a specific branch ``` ### `cortex git branch` ```bash cortex git branch # List all branches cortex git branch --create feature-x # Create a new branch cortex git branch --checkout main # Checkout a branch ``` ### `cortex git remote` ```bash cortex git remote # List remotes cortex git remote --add origin # Add a remote cortex git remote --url # Show remote URLs ``` ## Examples ```bash # Commit with a message cortex git commit "fix: resolve type error in auth module" # Clone and set up a project cortex git clone https://github.com/user/repo.git # Create a feature branch cortex git branch --create feature/new-dashboard # Push to a specific remote branch cortex git push --remote origin --branch feature/new-dashboard ``` URL: https://cortexprism.io/docs/cli/git --- ### Github # `cortex github` Full GitHub integration for managing pull requests, issues, repositories, and branches directly from the CLI. Requires GitHub authentication via personal access token. ## Usage ```bash cortex github [options] cortex github token # Manage GitHub authentication token ``` ## Subcommands ### `cortex github pr` Manage pull requests. ```bash cortex github pr list # List pull requests cortex github pr list --state open # Filter by state (open, closed, all) cortex github pr list --limit 10 # Limit results cortex github pr get # Get pull request details cortex github pr create # Create a new pull request cortex github pr create --draft # Create as draft PR cortex github pr create --body "..." # PR description cortex github pr merge # Merge a pull request cortex github pr merge --method squash # Merge method (merge, squash, rebase) cortex github pr close # Close a pull request ``` ### `cortex github issue` Manage issues. ```bash cortex github issue list # List issues cortex github issue list --state open # Filter by state cortex github issue list --limit 20 # Limit results cortex github issue list --labels bug # Filter by labels cortex github issue create # Create a new issue cortex github issue create --body "..." # Issue description cortex github issue create --labels bug,priority # Add labels cortex github issue create --assignees user1 # Assign users cortex github issue close # Close an issue ``` ### `cortex github repo` Manage repositories. ```bash cortex github repo list # List repositories cortex github repo list --type all # Filter by type (all, owner, public, private, member) cortex github repo list --limit 10 # Limit results cortex github repo get # Get repository details cortex github repo branches # List branches in a repository cortex github repo branches --limit 20 # Limit branch results ``` ### `cortex github token` Manage GitHub authentication. ```bash cortex github token # Set or update GitHub personal access token ``` ## Authentication GitHub integration requires a personal access token. Set it using: ```bash cortex github token ``` The token is stored in the Cortex vault (AES-256-GCM encrypted). Required scopes: - `repo` — Full control of private repositories - `read:org` — Read organization and team membership - `issues:read/write` — Read and write issues ## Examples ```bash # List open pull requests cortex github pr list --state open # Create a draft PR cortex github pr create --draft --body "WIP: Refactor auth middleware" # Merge a PR with squash cortex github pr merge 42 --method squash # List bugs in the current repo cortex github issue list --labels bug # Create a new issue with labels cortex github issue create --labels enhancement --body "Add dark mode toggle" # Browse all repositories cortex github repo list --type all # View branches in a repo cortex github repo branches cortex --limit 20 ``` URL: https://cortexprism.io/docs/cli/github --- ### Hooks # `cortex hooks` Manage git hooks that integrate Cortex agent capabilities into the git workflow. Hooks can be installed into repositories to trigger agent actions on git events. ## Usage ```bash cortex hooks [options] ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `init` | Initialize git hooks in a repository | | `disable` | Disable git hooks in a repository | ## Examples ```bash # Initialize git hooks in the current repository cortex hooks init # Disable git hooks cortex hooks disable ``` URL: https://cortexprism.io/docs/cli/hooks --- ### Import # `cortex import` Import data from external sources into Cortex, including sessions from other AI platforms. ## Usage ```bash cortex import [options] ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `openclaw` | Import sessions from OpenClaw | | `json` | Import data from JSON format | ## Options | Option | Subcommand | Description | |--------|------------|-------------| | `--dry-run` | `openclaw` | Preview import without writing data | ## Examples ```bash # Import from OpenClaw cortex import openclaw # Preview OpenClaw import cortex import openclaw --dry-run # Import from JSON cortex import json ``` URL: https://cortexprism.io/docs/cli/import --- ### CLI Reference Overview # CLI Reference CortexPrism provides a comprehensive command-line interface for interacting with the agentic system. All commands are invoked through the `cortex` binary. ## Usage ```bash cortex [options] ``` ## Global Options | Option | Environment Variable | Description | |--------|---------------------|-------------| | `--config, -c` | `CORTEX_CONFIG` | Path to config file (default: `~/.cortex/config.json`) | | `--data-dir` | `CORTEX_DATA_DIR` | Data directory path (default: `~/.cortex/`) | | `--verbose, -v` | — | Enable verbose logging | | `--help, -h` | — | Show help | | `--version, -V` | — | Show version | ## Available Commands | Command | Description | |---------|-------------| | [`cortex chat`](/docs/cli/chat) | Interactive streaming chat session with LLM providers | | [`cortex setup`](/docs/cli/setup) | First-run setup wizard | | [`cortex migrate`](/docs/cli/migrate) | Initialize or migrate all databases | | [`cortex sessions`](/docs/cli/sessions) | List and manage chat sessions | | [`cortex jobs`](/docs/cli/jobs) | Manage scheduled cron jobs | | [`cortex memory`](/docs/cli/memory) | Search and manage the 5-tier memory system | | [`cortex run`](/docs/cli/run) | Execute code files in sandboxed or direct subprocess mode | | [`cortex serve`](/docs/cli/serve) | Start the HTTP + WebSocket server with web UI | | [`cortex reflect`](/docs/cli/reflect) | Inspect and consolidate reflection patterns | | [`cortex vault`](/docs/cli/vault) | Encrypted credential vault (AES-256-GCM) | | [`cortex policy`](/docs/cli/policy) | Security policy rule management | | [`cortex migrate`](/docs/cli/setup) | Initialize or migrate all databases | | [`cortex daemon`](/docs/cli/daemon) | Manage background daemon processes (validator, executor, scheduler) | | [`cortex soul`](/docs/cli/soul) | Agent soul/persona management | | [`cortex discord`](/docs/cli/discord) | Discord bot integration | | [`cortex log`](/docs/cli/log) | View and manage logging (show, tail, clear, set-level, status) | | [`cortex plugins`](/docs/cli/plugins) | Plugin management (install, enable, disable, remove, update, verify) | | [`cortex marketplace`](/docs/cli/marketplace) | Marketplace interaction (list, categories, stats, install) | | [`cortex import`](/docs/cli/import) | Import data from other sources (openclaw, json) | | [`cortex agent`](/docs/cli/agent) | Agent configuration management (create, update, delete, select, inspect) | | [`cortex service`](/docs/cli/service) | Micro-service mode management (list, create, start, stop) | | [`cortex stop`](/docs/cli/stop) | Stop server, daemons, or both | | [`cortex update`](/docs/cli/update) | Check, apply, or rollback Cortex updates with channel support | | [`cortex git`](/docs/cli/git) | Full git porcelain via agent workspace (status, log, diff, commit, push, clone) | | [`cortex github`](/docs/cli/github) | GitHub integration (PRs, issues, repos, branches) | | [`cortex hooks`](/docs/cli/hooks) | Git hooks management | | [`cortex triggers`](/docs/cli/triggers) | File watchers, webhooks, and git hook event triggers | | [`cortex channels`](/docs/cli/channels) | Communication channels (Discord integration) | | [`cortex mcp`](/docs/cli/mcp) | MCP server management (serve, stdio transport) | | [`cortex remote`](/docs/cli/remote) | Remote agent management (add, connect, remove) | | [`cortex tui`](/docs/cli/tui) | Terminal UI | | [`cortex projects`](/docs/cli/projects) | Project management (create, delete) | | [`cortex workflow`](/docs/cli/workflow) | Workflow engine (run, approve) | | [`cortex desktop`](/docs/cli/desktop) | Desktop app automation (screenshot, click, type, clipboard) | | [`cortex node`](/docs/cli/node) | Hub node management (register, list, connect) | | [`cortex eval`](/docs/cli/eval) | Evaluation framework for benchmarking agent performance | | [`cortex models`](/docs/cli/models) | Model management (list, show, set, available) | | [`cortex qm`](/docs/cli/qm) | Model Quartermaster (patterns, weights, stats, decisions, dashboard) | | [`cortex mqm`](/docs/cli/qm) | Model Quartermaster (model-level: stats, decisions, weights, accuracy) | | [`cortex install`](/docs/cli/install) | Install Cortex as a system service | | [`cortex uninstall`](/docs/cli/uninstall) | Uninstall Cortex system service | | [`cortex start`](/docs/cli/start) | Start Cortex server and daemon | | [`cortex restart`](/docs/cli/restart) | Restart Cortex server and daemon | | [`cortex voice`](/docs/cli/voice) | Voice mode management (enable, disable, set-voice, set-speed) | URL: https://cortexprism.io/docs/cli --- ### Install # `cortex install` Install Cortex as a system service, enabling automatic startup and daemon management. ## Usage ```bash cortex install [options] ``` ## Options | Option | Description | |--------|-------------| | `--port, -p` | Port for the HTTP server (default: 3000) | | `--host, -H` | Host to bind to (default: 127.0.0.1) | | `--daemon-only` | Install only the daemon service | | `--server-only` | Install only the HTTP server service | | `--no-start` | Install without starting the services | | `--help` | Show help for this command | ## Examples ```bash # Install Cortex as a system service cortex install # Install on custom port cortex install -p 8080 # Install without starting cortex install --no-start ``` URL: https://cortexprism.io/docs/cli/install --- ### Jobs # `cortex jobs` Manage scheduled cron jobs that run on the daemon scheduler. Jobs are persisted in SQLite with retry logic and status tracking. ## Usage ```bash cortex jobs [options] ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `list` | List all jobs with their status and next run time | | `add ` | Create a new scheduled job | | `cancel ` | Cancel a pending or failed job | | `run-due` | Execute all currently due jobs immediately | ## `cortex jobs add` Options | Option | Description | |--------|-------------| | `--cron ` | CRON expression (e.g., `0 9 * * 1` for weekly Monday 9AM) | | `--in ` | Run after N minutes from now | | `--max-attempts ` | Max retry attempts on failure (default: 3) | ## Scheduler Behavior - The scheduler daemon polls the database for due jobs - On failure, jobs are retried with configurable backoff - Execution history is logged for audit - Memory consolidation can be scheduled as a recurring job - CRON jobs auto-reschedule after completion ## CRON Format ``` ┌───────── minute (0-59) │ ┌───────── hour (0-23) │ │ ┌───────── day of month (1-31) │ │ │ ┌───────── month (1-12) │ │ │ │ ┌───────── day of week (0-6, 0=Sunday) │ │ │ │ │ * * * * * ``` ## Examples ```bash # Add a weekly report every Monday at 9 AM cortex jobs add weekly-report "generate-weekly-report" --cron "0 9 * * 1" # Add a one-time job to run in 30 minutes cortex jobs add quick-backup "run-backup" --in 30 # List all jobs cortex jobs list # Cancel a pending job cortex jobs cancel job_xyz789 # Run all due jobs immediately cortex jobs run-due ``` URL: https://cortexprism.io/docs/cli/jobs --- ### Log # `cortex log` View and manage Cortex logging output. The logging system writes JSONLines to a rotating log file with configurable log levels. ## Usage ```bash cortex log [options] ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `show` | Display recent log entries (latest 100 by default) | | `tail` | Stream new log entries in real time | | `clear` | Clear/truncate the log file | | `path` | Print the path to the current log file | | `set-level` | Set the log level for the current session | | `status` | Show current logging configuration | ### Options | Option | Subcommand | Description | |--------|------------|-------------| | `--limit, -n` | `show` | Number of log entries to display (default: 100) | | `--level, -l` | `show`, `tail` | Filter by log level (trace, debug, info, warn, error) | ## Log Levels | Level | Description | |-------|-------------| | `trace` | Verbose diagnostic output | | `debug` | Debug-level information | | `info` | General operational messages | | `warn` | Warning conditions | | `error` | Error conditions | | `silent` | Suppress all log output | ## Configuration The logging system is configured in `~/.cortex/config.json`: ```json { "logging": { "filePath": "~/.cortex/cortex.log", "level": "info" } } ``` Environment variable override: `CORTEX_LOG_LEVEL` ## Examples ```bash # View recent logs cortex log show # View last 100 log entries cortex log show -n 100 # Filter by error level cortex log show --level error # Stream logs in real time cortex log tail # Check current configuration cortex log status ``` URL: https://cortexprism.io/docs/cli/log --- ### Marketplace # `cortex marketplace` Browse and install plugins and agent configurations from the CortexPrism marketplace directly from the CLI. ## Usage ```bash cortex marketplace [options] ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `list plugins` | List available plugins with filtering | | `list agents` | List available agent configurations | | `categories` | Browse marketplace categories | | `stats` | Show marketplace statistics | | `install` | Install a plugin or agent | ## Plugin Listing Options | Option | Description | |--------|-------------| | `--search, -s` | Search by keyword | | `--kind, -k` | Filter by plugin kind (`esm`, `mcp`, `wasm`) | | `--category, -c` | Filter by category | | `--limit, -l` | Limit number of results | ## Agent Listing Options | Option | Description | |--------|-------------| | `--search, -s` | Search by keyword | | `--provider, -p` | Filter by provider | | `--category, -c` | Filter by category | | `--limit, -l` | Limit number of results | ## Install Options | Option | Description | |--------|-------------| | `--yes, -y` | Skip confirmation prompt | ## Examples ```bash # List all plugins cortex marketplace list plugins # Search for Python plugins cortex marketplace list plugins -s python # Filter by MCP plugins cortex marketplace list plugins -k mcp # Browse categories cortex marketplace categories # View marketplace stats cortex marketplace stats # Install a plugin cortex marketplace install python-executor -y # List agent configs cortex marketplace list agents -s code-review # Filter agents by provider cortex marketplace list agents -p anthropic ``` URL: https://cortexprism.io/docs/cli/marketplace --- ### Mcp # `cortex mcp` Run Cortex as a Model Context Protocol (MCP) server, enabling AI applications to use Cortex tools and agents through the MCP protocol standard. ## Usage ```bash cortex mcp [options] ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `serve` | Start Cortex as an MCP server over HTTP | | `stdio` | Run MCP server over standard I/O transport | | `connect` | Connect to a remote MCP server | | `disconnect` | Disconnect from an MCP server | | `connections` | List active MCP connections | ## MCP Integration Cortex implements an MCP server that exposes Cortex capabilities (tools, memory, agents, sessions) to any MCP-compatible client. This allows editors, IDEs, and other AI applications to use Cortex as their agentic backend. ### Transport - **stdio**: Standard input/output transport for process-level integration - **HTTP**: Server mode on port 9187 for remote MCP connections - The MCP server handles JSON-RPC 2.0 messages according to the Model Context Protocol specification ## Available Tools via MCP When running as an MCP server, Cortex exposes: - File operations (read, write, list) - Shell command execution (with approval gates) - Memory search and retrieval - Agent conversation management - Session persistence and resume ## Examples ```bash # Start MCP server over stdio cortex mcp stdio # Start MCP server cortex mcp serve ``` URL: https://cortexprism.io/docs/cli/mcp --- ### Memory # `cortex memory` Search and manage the 5-tier memory system. CortexPrism uses a hybrid retrieval approach combining FTS5 keyword search with cosine vector similarity, scored with exponential decay. ## Usage ```bash cortex memory search "" # Search all memory types (hybrid return) cortex memory search "" --type semantic # Semantic-only search cortex memory search "" --type episodic # Episodic-only search cortex memory add "" # Add a semantic fact cortex memory add "" --category project --importance 0.9 # Categorized memory ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `search` | Search memory with hybrid retrieval | | `add` | Add a new semantic memory entry | | `health` | Show memory system health metrics | | `heuristics` | Display memory decay and scoring heuristics | ## Options | Option | Description | |--------|-------------| | `--type` | Filter results by memory type: `episodic`, `semantic`, or `all` (default: `all`) | | `--limit, -n` | Maximum results to return (default: 8) | | `--category` | Category filter for `add` subcommand | | `--importance` | Importance value for `add` subcommand (0.0–1.0, default: 0.5) | | `--help` | Show help for this command | ## Memory Tiers | Tier | Persistence | Content | |------|-------------|---------| | Episodic | Session | Turn summaries of user+agent exchanges with auto-decay | | Semantic | Long-term | Injected facts and knowledge with hybrid FTS5 + vector retrieval | | Reflection | Permanent | LLM-extracted behavior patterns from per-turn meta-cognition | | Graph | Long-term | Knowledge graph of entities and relationships | | Skills | Permanent | Procedural knowledge extracted from multi-step tool usage | ## Retrieval Algorithm ``` Query → FTS5 keyword search (episodic + semantic tables) → cosine vector similarity (via embedding provider) → merge + re-score: score × 2^(-age_days / half_life_days) → sort descending → top-K results ``` ## Embedding Providers | Provider | Model | Requirement | |----------|-------|-------------| | OllamaEmbedder | Configurable via Ollama | Ollama running locally | | OpenAIEmbedder | `text-embedding-3-small` | OpenAI API key required | | StubEmbedder | Deterministic hash | No external service needed (default) | ## Examples ```bash # Hybrid search (all memory types) cortex memory search "project deployment config" # Semantic-only search cortex memory search "deployment config" --type semantic # Episodic-only search cortex memory search "deployment" --type episodic # Add a fact to semantic memory cortex memory add "CortexPrism uses SQLite WAL mode for all databases" # Add a categorized fact with high importance cortex memory add "critical bug" --category bugs --importance 0.9 ``` URL: https://cortexprism.io/docs/cli/memory --- ### Migrate # `cortex migrate` Initialize or migrate all Cortex databases. Runs the full migration chain for all SQLite databases used by the system. ## Usage ```bash cortex migrate ``` ## Description The `migrate` command ensures all databases are at the latest schema version. It runs migrations for: - `cortex.db` — Core system configuration and state - `memory.db` — 5-tier memory system (episodic, semantic, reflection, graph, skills) - `lens.db` — Cortex Lens immutable audit trail - `vault.db` — Encrypted credential vault - `plugins.db` — Plugin registry and state All databases use SQLite with WAL mode enabled for concurrent read access. ## When to Run - First installation (run automatically by `cortex setup`) - After a Cortex version upgrade that includes schema changes - When troubleshooting database-related errors ## Examples ```bash # Initialize all databases to latest schema cortex migrate # The command is idempotent — safe to run multiple times cortex migrate ``` URL: https://cortexprism.io/docs/cli/migrate --- ### Models # `cortex models` Manage LLM models used by Cortex. View available models, inspect model details, set default models, and browse all models supported by configured providers. ## Usage ```bash cortex models [options] ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `list` | List configured models | | `show ` | Show details for a configured provider | | `set ` | Configure a provider setting | | `available` | List all available models across providers | ## Examples ```bash # List configured models cortex models list # Show details for a provider cortex models show anthropic # Configure a provider setting cortex models set anthropic model claude-sonnet-4-5 # Browse all available models cortex models available ``` URL: https://cortexprism.io/docs/cli/models --- ### Node # `cortex node` Manage nodes in the Cortex hub — a distributed agent execution layer where remote nodes connect to a central hub via WebSocket. Nodes register with capability tiers and execute directives from the hub. ## Usage ```bash cortex node [options] ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `register` | Register a new node with the hub | | `list` | List all registered nodes | | `show` | Show details for a specific node | | `deregister` | Remove a node from the hub | | `rekey` | Rotate a node's authentication token | | `connect` | Connect as a node to a hub | ## Node Status | Status | Description | |--------|-------------| | `connecting` | Establishing WebSocket connection | | `connected` | Active with heartbeat | | `disconnected` | Connection lost | | `error` | Connection in error state | | `deregistered` | Node removed from hub | ## Capability Tiers | Tier | Access Level | |------|-------------| | **root** | Full unrestricted — all tools, all paths (`/`), all sudo commands, all domains | | **sudo** | Elevated scoped — excludes `/etc`, `/root`, `/proc`, `/sys`; allows apt/npm/pip | | **unprivileged** | Sandboxed — read-only tools, no shell, restricted to `/tmp/cortex-sandbox` | ## Connect Options | Option | Description | |--------|-------------| | `--id` | Node identifier | | `--token` | Authentication token | | `--endpoint` | Hub WebSocket endpoint URL | | `--tier` | Capability tier (root, sudo, unprivileged) | | `--group` | Node group for routing | | `--name` | Human-readable node name | | `--reconnect-ms` | Reconnect interval in milliseconds | | `--heartbeat-ms` | Heartbeat interval in milliseconds | | `--timeout-ms` | Connection timeout in milliseconds | ## Protocol Nodes communicate with the hub via a message protocol: - **register** — Node announces itself to hub - **heartbeat** — Periodic health check with live metrics - **directive** — Hub sends execution directive - **result** — Node returns execution result - **stream_chunk** — Streaming result chunks - **cancel** — Hub cancels in-flight directive ## Examples ```bash # Register a new node cortex node register # List all nodes cortex node list # Show node details cortex node show node-001 # Connect as a node to a hub cortex node connect --token --endpoint https://hub.example.com --tier sudo # Rotate node token cortex node rekey node-001 # Remove a node cortex node deregister node-001 ``` URL: https://cortexprism.io/docs/cli/node --- ### Plugins # `cortex plugins` Manage the Cortex plugin system. Install, enable, disable, update, verify integrity, and manage permissions for ESM, MCP, and WASM plugins. ## Usage ```bash cortex plugins [options] ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `list` | List installed plugins | | `install` | Install a plugin | | `enable` | Enable a disabled plugin | | `disable` | Disable a plugin without removing | | `remove` | Uninstall a plugin | | `verify` | Verify plugin integrity | | `permissions` | View or set plugin permissions | | `update` | Update plugins to latest version | | `validate` | Validate plugin configuration | ## Plugin Types | Type | Description | |------|-------------| | **ESM** | ECMAScript modules loaded into the Cortex runtime | | **MCP** | Model Context Protocol server plugins | | **WASM** | WebAssembly plugins running in sandboxed environment | ## Install Sources ```bash # Install from marketplace cortex plugins install marketplace:cortexprism.io/plugins/python-executor # Install from GitHub cortex plugins install github:user/repo # Install from local path cortex plugins install ./my-plugin # Install from npm cortex plugins install npm:@scope/plugin-name ``` ## Plugin Permissions Manage what plugins can access: ```bash # View plugin permissions cortex plugins permissions # Set permissions cortex plugins permissions -s read,write,shell ``` ## Update Options | Option | Description | |--------|-------------| | `--all, -a` | Update all installed plugins | | `--check, -c` | Check for updates without applying | ## Example | Option | Command | Description | |--------|---------|-------------| | `--fix` | `validate` | Auto-fix validation issues | ## Examples ```bash # Install from marketplace cortex plugins install marketplace:cortexprism.io/plugins/python-executor # List all installed plugins cortex plugins list # Update all plugins cortex plugins update --all # Check for updates cortex plugins update -c # Disable a plugin cortex plugins disable python-executor # Enable a plugin cortex plugins enable python-executor # Verify plugin integrity cortex plugins verify python-executor # Remove a plugin cortex plugins remove python-executor # Validate plugin config cortex plugins validate python-executor ``` URL: https://cortexprism.io/docs/cli/plugins --- ### Policy # `cortex policy` Manage security policy rules for the Parallax security model. Policy rules control which operations agents are allowed to perform, based on pattern matching with priority-based evaluation. ## Usage ```bash cortex policy list # List all policy rules cortex policy add "" --kind shell --effect deny --reason "reason" cortex policy check shell "rm -rf /etc" # Check if an action would be allowed cortex policy remove # Remove a rule by ID ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `list` | List all policy rules with their patterns, effects, and priorities | | `add` | Add a new policy rule | | `remove` | Remove a policy rule by ID | | `check` | Check whether a specific action would be allowed or denied | ## Options | Option | Description | |--------|-------------| | `--kind` | Rule kind: `tool`, `shell`, `domain` | | `--effect` | `allow` or `deny` | | `--reason` | Human-readable reason for the rule | | `--priority` | Rule priority (lower number = higher precedence, default: 500) | | `--help` | Show help for this command | ## Default Deny Rules On first migration, the following dangerous patterns are seeded: | Rule | Pattern | Blocks | |------|---------|--------| | Recursive root delete | `rm\s+-rf\s+/` | `rm -rf /` and variants | | Fork bombs | `:\(\)\{.*\}` | Shell fork bomb patterns | | Direct disk writes | `dd\s+if=.*of=/dev/` | `dd` to block devices | | World-writable root | `chmod\s+777\s+/` | Making root world-writable | ## Policy Evaluation ``` checkPolicy(kind, value): for rule in rules WHERE kind = ? ORDER BY priority ASC: if regex(rule.pattern).test(value): return { allowed: rule.effect === 'allow', reason: rule.reason } return { allowed: true, reason: 'default allow' } ``` Priority ASC means lower numbers are evaluated first. A `deny` at priority 100 will override an `allow` at priority 500. ## Examples ```bash # List all current rules cortex policy list # Add a deny rule for a dangerous domain pattern cortex policy add "curl.*evil\.com" --kind shell --effect deny --reason "Block known malicious domain" # Check if a command would be allowed cortex policy check shell "curl https://evil.com" # → { allowed: false, reason: "Block known malicious domain" } # Add an allow rule with high priority to override deny cortex policy add "git pull" --kind shell --effect allow --priority 100 --reason "Allow git operations" # Remove a rule cortex policy remove pol_abc123 ``` URL: https://cortexprism.io/docs/cli/policy --- ### Projects # `cortex projects` Manage Cortex projects with persistent configuration. Each project creates a `cortex-project.json` file that stores the project's agent assignment, tools, and metadata. ## Usage ```bash cortex projects [options] ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `create` | Create a new project | | `delete` | Delete a project | ## Project Configuration Each project stores a `cortex-project.json` file with: ```json { "name": "my-project", "path": "/home/user/projects/my-project", "agentId": "agent-001", "memoryDb": "project-memory.db", "tools": ["read", "write", "shell", "search"], "description": "Project description" } ``` ## Active Project Detection Cortex automatically detects the active project based on the current working directory. When a `cortex-project.json` is found in the directory tree, the project's agent and configuration are loaded automatically. ## Examples ```bash # Create a new project cortex projects create # Delete a project cortex projects delete my-project ``` URL: https://cortexprism.io/docs/cli/projects --- ### Qm # `cortex qm` / `cortex mqm` The Model Quartermaster is an adaptive model-selection engine that observes LLM calls across sessions, computes six weighted signal scores, and fuses them to predict the optimal model for each task. `cortex mqm` provides model-level analysis across all sessions; the legacy `cortex qm` tool-prediction variant is also available for tool-level analysis. ## Usage ```bash cortex qm [options] cortex mqm [options] ``` ## Six Prediction Signals (MQM) | Signal | Description | |--------|-------------| | **Trajectory** | Recent model usage patterns and sequences | | **Episodic** | Similar conversation context matching | | **Historical** | Past performance data for task categories | | **Cost** | Cost efficiency optimization across models | | **Quality** | Expected quality based on model capabilities | | **Reflection** | Per-turn reflection feedback integration | ## `cortex qm` Subcommands | Subcommand | Description | |------------|-------------| | `patterns` | List learned patterns | | `weights` | Show current signal weights | | `stats` | Display usage statistics | | `decisions` | Show prediction decisions for a session | | `trace` | Trace the prediction chain for a turn | | `dashboard` | Rich visual dashboard with accuracy bars and top predictions | | `accuracy` | Show prediction accuracy metrics | | `reset` | Reset quartermaster state for a session | | `reset-all` | Reset all quartermaster data | ### Options | Option | Subcommand | Description | |--------|------------|-------------| | `--limit, -n` | `patterns` | Limit number of patterns shown | | `--session, -s` | `decisions`, `dashboard`, `accuracy` | Filter by session ID | | `--limit, -n` | `decisions` | Limit number of decisions shown | ## `cortex mqm` Subcommands | Subcommand | Description | |------------|-------------| | `stats` | Model-level usage statistics | | `decisions` | Model-level prediction decisions | | `weights` | Model-level signal weights | | `accuracy` | Accuracy metrics across all sessions | | `dashboard` | Model-level dashboard | | `reset` | Reset model-level quartermaster | | `reset-all` | Reset all model-level data | ### Options | Option | Subcommand | Description | |--------|------------|-------------| | `--limit, -n` | `decisions` | Limit number of decisions | | `--hours, -h` | `accuracy` | Time window for accuracy calculation | ## Prediction Confidence Levels | Confidence | Action | |------------|--------| | ≥ 90% | **Automate** — Auto-select model (safe operations only) | | 60–89% | **Suggest** — Recommend model to the agent | | < 60% | **Defer** — Let the agent decide | ## Active Mode The Quartermaster requires 50 observations before entering active prediction mode. Before this threshold, it operates in learning-only mode, collecting data without making predictions. ## Reinforcement Learning After each prediction, the Quartermaster evaluates correctness: - **Reward (EMA α = 0.15)**: Increase signal weights for correct predictions - **Punishment (EMA α = 0.25)**: Decrease weights for incorrect predictions - **Convergence**: Weights stabilize after ~200–500 observations ## Dashboard Output The `dashboard` subcommand provides the richest output: - Accuracy bars per signal - Current signal weights visualization - Top models by prediction accuracy - Session and model-level trends - Confidence distribution histograms ## Examples ```bash # View prediction dashboard for a session cortex qm dashboard -s sess_abc123 # Show learned patterns cortex qm patterns --limit 20 # Display signal weights cortex qm weights # Trace prediction for a specific turn cortex qm trace 42 # Show accuracy metrics cortex qm accuracy -s sess_abc123 # Model-level accuracy over last 24 hours cortex mqm accuracy -h 24 # Reset all quartermaster data cortex mqm reset-all ``` URL: https://cortexprism.io/docs/cli/qm --- ### Reflect # `cortex reflect` Inspect and consolidate LLM self-assessment reflection patterns. After each turn, CortexPrism performs a meta-cognitive self-evaluation to assess response quality and extract reusable patterns. ## Usage ```bash cortex reflect list # Show stored reflection patterns cortex reflect consolidate # Run LLM meta-pattern extraction ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `list` | Display all stored reflection patterns from past sessions | | `consolidate` | Run LLM-driven meta-pattern extraction across stored reflections | ## Reflection System After each agent turn, the system performs: 1. **Confidence assessment** — LLM self-evaluates response quality 2. **Pattern extraction** — Identifies recurring themes and behaviors 3. **Pattern storage** — Saved to `reflection_memory` table (T5 tier) 4. **Consolidation** — Batch meta-pattern extraction across stored reflections Reflection is fire-and-forget — the agent loop does not wait for reflection to complete before returning the response to the user. ## Configuration Reflection runs automatically after each agent turn. Use `cortex reflect` to review and manage reflection patterns: ```bash # Inspect recent reflections cortex reflect list -s sess_abc123 # Show consolidated patterns cortex reflect patterns # Run manual consolidation cortex reflect consolidate ``` ## Examples ```bash # View all stored reflection patterns cortex reflect list # Run meta-pattern consolidation cortex reflect consolidate ``` URL: https://cortexprism.io/docs/cli/reflect --- ### Remote # `cortex remote` Manage remote agent nodes that connect to the Cortex hub for distributed agent execution. Remote agents register with the hub and execute directives through the global tool registry. ## Usage ```bash cortex remote [options] ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `add` | Register a new remote agent | | `connect` | Connect a remote agent to the hub | | `remove` | Deregister a remote agent | ## Remote Agent Status | Status | Description | |--------|-------------| | `connecting` | Establishing WebSocket connection to hub | | `connected` | Active connection with heartbeat | | `disconnected` | Connection lost, attempting reconnect | | `error` | Connection in error state | ## Capability Tiers Remote agents operate at one of three capability tiers: | Tier | Access Level | |------|-------------| | **root** | Full unrestricted access — all tools, all paths, all sudo commands | | **sudo** | Elevated but scoped — excludes system paths, allows package management | | **unprivileged** | Sandboxed — read-only tools, no shell, restricted to `/tmp/cortex-sandbox` | ## Connection Protocol Remote agents connect to the hub via WebSocket with: - **Heartbeat**: Every 30 seconds with live `/proc` metrics (CPU, memory, disk) - **Auto-reconnect**: Exponential backoff on connection loss - **Token authentication**: Secure token-based registration - **Streaming results**: Tool execution results streamed back in chunks ## Node Metrics Connected agents report live system metrics: - `cpuPercent` — Current CPU utilization - `memoryMb` — Memory usage in MB - `diskFreeMb` — Available disk space - `uptimeSeconds` — Agent uptime ## Examples ```bash # Register a new remote agent cortex remote add # Connect a remote agent to the hub cortex remote connect --id agent-001 --token --endpoint https://hub.example.com # Remove a remote agent cortex remote remove ``` URL: https://cortexprism.io/docs/cli/remote --- ### Restart # `cortex restart` Restart the Cortex HTTP server and background daemon processes. ## Usage ```bash cortex restart [options] ``` ## Options | Option | Description | |--------|-------------| | `--port, -p` | Port of the server to restart (default: 3000) | | `--host, -H` | Host to bind to (default: 127.0.0.1) | | `--daemon-only` | Restart only the daemon processes | | `--server-only` | Restart only the HTTP server | | `--help` | Show help for this command | ## Examples ```bash # Restart everything cortex restart # Restart on custom port cortex restart -p 8080 # Restart only the server cortex restart --server-only ``` URL: https://cortexprism.io/docs/cli/restart --- ### Run # `cortex run` Execute code files in sandboxed environments with resource limits, or as direct subprocesses. Supports auto-fix loop for failed executions. ## Usage ```bash cortex run # Run in sandbox (auto-detect language) cortex run script.py --no-sandbox # Run as direct subprocess cortex run script.py --fix # Enable LLM auto-fix loop on failure cortex run script.py --fix --max-fix 6 # Up to 6 fix attempts ``` ## Options | Option | Description | |--------|-------------| | `--lang, -l` | Force language interpreter (e.g., `python`, `javascript`, `bash`) | | `--no-sandbox` | Run as direct subprocess instead of Docker sandbox | | `--fix` | Enable LLM auto-fix loop when code fails | | `--max-fix` | Maximum number of fix attempts (default: 4) | | `--help` | Show help for this command | ## Supported Languages | Language | Extension | Sandbox Image | |----------|-----------|---------------| | Python | `.py` | `python:3.12-alpine` | | JavaScript | `.js` | `node:22-alpine` | | TypeScript | `.ts` | `denoland/deno:alpine` | | Bash | `.sh` | `alpine:3.20` | | Ruby | `.rb` | `ruby:3.3-alpine` | | Go | `.go` | `golang:1.22-alpine` | | Rust | `.rs` | `rust:1.78-alpine` | ## Docker Sandbox When running in sandbox mode, Docker containers are created with: | Constraint | Value | |------------|-------| | Network | `--network=none` (no network access) | | Memory | 256MB limit | | CPU | 0.5 cores | | Process limit | 64 PIDs | | Security | `no-new-privileges` | | Timeout | 30 seconds | | Max output | 64KB | Subprocess fallback is used when `docker info` fails. ## Auto-Fix Loop When `--fix` is enabled: ``` runInSandbox(code) → exit != 0? → LLM: "Fix this error: \n\nCode:\n" → extract fixed code from LLM response → runInSandbox(fixedCode) → repeat up to maxRounds ``` ## Examples ```bash # Run a Python script in Docker sandbox cortex run analyze.py # Run a shell script as direct subprocess cortex run deploy.sh --no-sandbox # Run with auto-fix enabled cortex run buggy-code.py --fix # Run with aggressive auto-fix cortex run complex.js --fix --max-fix 8 ``` URL: https://cortexprism.io/docs/cli/run --- ### Serve # `cortex serve` Start the built-in HTTP server with REST API endpoints and WebSocket support for real-time streaming chat. Also serves the CortexPrism web UI dashboard. ## Usage ```bash cortex serve # http://127.0.0.1:3000 (foreground) cortex serve --port 8080 --host 0.0.0.0 cortex serve -d # Run in the background (daemon mode) cortex serve -d -r # Restart background server on the same port cortex serve -s # Stop background server ``` ## Options | Option | Description | |--------|-------------| | `--port, -p` | HTTP server port (default: 3000) | | `--host, -H` | Bind address (default: 127.0.0.1) | | `-d` | Run server in background (daemon mode) | | `-r` | Restart an existing background server (use with `-d`) | | `-s` | Stop a running background server | | `--help` | Show help for this command | ## Service Management ```bash cortex serve install # Install as a system service cortex serve uninstall # Uninstall the system service ``` ## REST API Endpoints The server exposes 85+ REST API endpoints across 20+ resource groups. Key endpoints include: | Method | Path | Description | |--------|------|-------------| | GET | `/api/health` | Health check | | GET | `/api/sessions` | List recent sessions | | GET | `/api/sessions/tree` | Session hierarchy tree | | GET | `/api/sessions/:id` | Get session details | | GET | `/api/sessions/:id/events` | Get session events | | GET | `/api/sessions/:id/messages` | Get session messages | | POST | `/api/sessions/:id/resume` | Resume a session | | DELETE | `/api/sessions/:id` | Delete a session | | GET | `/api/memory/search?q=` | Search memory | | POST | `/api/memory/add` | Add memory entry | | GET | `/api/jobs` | List jobs by status | | GET | `/api/config` | Get system configuration | | GET | `/api/providers/configured` | List configured providers | | GET | `/api/lens/recent` | Recent audit events | | GET | `/api/skills` | List skill modules | | GET | `/api/plugins` | List installed plugins | | GET | `/api/agents` | List agent configurations | | GET | `/api/metrics` | Prometheus metrics ## WebSocket Protocol Connect to `ws://:/ws` for real-time streaming chat. **Client → Server messages:** ```json { "type": "chat", "message": "...", "sessionId": "sess_..." } { "type": "ping" } { "type": "new_session" } { "type": "select_agent", "agentId": "..." } ``` **Server → Client messages:** ```json { "type": "connected" } { "type": "session", "sessionId": "sess_..." } { "type": "start" } { "type": "chunk", "delta": "..." } { "type": "done", "tokensIn": 100, "tokensOut": 50, "costUsd": 0.001, "durationMs": 800 } { "type": "error", "error": "..." } { "type": "pong" } ``` ## Web UI Dashboard The built-in web UI provides a full-featured dashboard with these tabs: - **Dashboard** — KPI cards, server info, system resources, daemon status - **Chat** — WebSocket-powered streaming chat interface - **Sessions** — Browse and manage all chat sessions - **Memory** — Search and browse memory entries across all tiers - **Skills** — Manage and browse skill modules - **Soul** — Agent personality management - **Activity** — Cortex Lens audit timeline of all tool calls and policy decisions - **Editor** — Code editor with syntax highlighting - **Code Runner** — Sandboxed code execution interface - **Version Control** — Git workspace management (status, log, diff, commit, push) - **Projects** — Project management - **Agents** — Configure and manage agent profiles - **Services** — Manage micro-service instances - **Nodes** — Distributed node management and metrics - **Jobs** — View scheduled job status and history - **Automation** — Trigger and hook configuration - **Channels** — Communication channel management - **Settings** — System configuration - **Policies** — Security policy rule management - **Extensions** — Plugin installation and management (with marketplace sub-tab) - **Analytics** — Usage and performance analytics - **Quartermaster** — Model Quartermaster stats and dashboard Session resume is supported: including an existing `sessionId` in a `chat` message reopens the per-session database and loads previous history. ## Examples ```bash # Start server on default port in foreground cortex serve # Start on a custom port in background cortex serve --port 8080 --host 0.0.0.0 -d # Restart a background server cortex serve -d -r # Stop the background server cortex serve -s ``` URL: https://cortexprism.io/docs/cli/serve --- ### Service # `cortex service` Manage Cortex micro-services — persistent agent-powered services that run on specific ports with health checks and automatic restart capabilities. ## Usage ```bash cortex service [options] ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `list` | List all services | | `show` | Show service details and runtime status | | `create` | Create a new micro-service | | `update` | Update an existing service | | `delete` | Delete a service | | `start` | Start a service | | `stop` | Stop a running service | ## Create Options | Option | Description | |--------|-------------| | `--description, -d` | Service description | | `--agent, -a` | Agent to use for this service | | `--port, -p` | Port to listen on | | `--model, -m` | LLM model | | `--provider` | LLM provider | | `--tools` | Comma-separated tool list | | `--auto-start` | Auto-start service on Cortex startup | | `--max-restarts` | Maximum restart attempts before giving up | | `--health-interval` | Health check interval in seconds | | `--system-prompt` | Custom system prompt | ## Update Options | Option | Description | |--------|-------------| | `--name, -n` | New service name | | `--description, -d` | Updated description | | `--agent, -a` | Change agent | | `--port, -p` | Change port | | `--model, -m` | Change model | | `--provider` | Change provider | | `--tools` | Update tool list | | `--auto-start` | Toggle auto-start | | `--max-restarts` | Update max restarts | | `--health-interval` | Update health check interval | | `--system-prompt` | Update system prompt | ## Examples ```bash # Create a REST API service cortex service create api-server -a code-reviewer -p 3001 --auto-start # Create with custom model cortex service create docs-bot -a writer --model gpt-4o -p 3002 # List all services cortex service list # Show service details cortex service show api-server # Start a service cortex service start api-server # Stop a service cortex service stop api-server # Update a service cortex service update api-server --port 8080 --auto-start # Delete a service cortex service delete old-service ``` URL: https://cortexprism.io/docs/cli/service --- ### Sessions # `cortex sessions` List and manage past chat sessions. Each session maintains its own message history in a dedicated per-session SQLite database. ## Usage ```bash cortex sessions # List recent sessions cortex sessions --limit 50 # Show more sessions ``` ## Options | Option | Description | |--------|-------------| | `--limit` | Maximum sessions to show (default: 20) | | `--help` | Show help for this command | ## Session Lifecycle 1. **Create** — A new session is created when you start `cortex chat` without `--resume` 2. **Active** — Session is in active use, receiving messages 3. **Closed** — Session is ended (exit chat) and marked with a `closed_at` timestamp 4. **Resumed** — A closed session can be reopened with `cortex chat --resume ` ## Per-Session Database Each session gets a dedicated SQLite database (`sess_.db`) stored in the data directory. This keeps session data isolated and allows efficient loading of history when resuming. ## Examples ```bash # List recent sessions cortex sessions # Show more sessions cortex sessions --limit 50 # Resume a session (via chat command) cortex chat --resume sess_a1b2c3d4 ``` URL: https://cortexprism.io/docs/cli/sessions --- ### Setup # `cortex setup` / `cortex migrate` Initialize the CortexPrism environment, configure LLM providers, and set up databases. ## `cortex setup` Run the interactive setup wizard to configure CortexPrism for first use: ```bash cortex setup ``` The setup wizard guides you through: 1. **Mode selection** — Choose CLI or Web interface 2. **Provider configuration** — Add API keys for up to 24 LLM providers (or skip) 3. **AI personalization** — Optional context about how you use AI 4. **Personality template** — Choose from 8 soul templates 5. **Channel setup** — CLI, CLI+Web, CLI+Discord, or all channels 6. **Telemetry preference** — Opt in or out of anonymous usage data ## `cortex migrate` Initialize or migrate all databases to the latest schema: ```bash cortex migrate ``` Migrates all databases: | Database | File | Migrations | |----------|------|------------| | Core | `cortex.db` | sessions, turns, jobs, policy rules, agents, services, hubs, nodes | | Memory | `memory.db` | 5-tier memory, FTS5, embeddings, reflections, graph, skills | | Lens | `lens.db` | Immutable audit events (50+ event types) | | Vault | `vault.db` | Encrypted credential entries (AES-256-GCM) | | Plugins | `plugins.db` | Plugin registry and state | Migrations are idempotent with checksum guards — safe to run multiple times. ## Configuration File After setup, configuration is stored at `~/.cortex/config.json`: ```json { "version": 1, "defaultProvider": "anthropic", "providers": { "anthropic": { "kind": "anthropic", "model": "claude-sonnet-4-20250514", "apiKey": "sk-..." }, "openai": { "kind": "openai", "model": "gpt-4o", "apiKey": "sk-..." } }, "agent": { "name": "Cortex", "maxTurns": 50, "streamOutput": true }, "router": { "enabled": false, "confidenceThreshold": 0.7, "cascade": [] } } ``` URL: https://cortexprism.io/docs/cli/setup --- ### Soul # `cortex soul` Manage agent souls (personas) that define the personality, tone, and behavior of Cortex agents. Souls provide consistent character traits, communication styles, and behavioral patterns. ## Usage ```bash cortex soul [options] ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `init` | Initialize a new soul configuration | | `show` | Display current soul configuration | | `edit` | Edit a soul configuration | | `note` | Add a personality note to a soul | | `templates` | List available soul templates | | `apply-template` | Apply a predefined soul template | | `validate` | Validate a soul configuration | ## Options | Option | Subcommand | Description | |--------|------------|-------------| | `--force` | `init` | Overwrite existing soul configuration | ## Soul Templates Prebuilt soul templates provide starting points for agent personalities: - `professional` — Professional assistant - `friendly` — Friendly companion - `developer` — Code reviewer / developer - `creative` — Creative writer - `analyst` — Data analyst - `teacher` — Technical teacher / support - `minimalist` — Minimalist / concise - `custom` — Build your own ## Examples ```bash # Initialize a new soul cortex soul init # View current soul cortex soul show # List available templates cortex soul templates # Apply a template cortex soul apply-template "code-reviewer" # Add a personality note cortex soul note # Validate soul configuration cortex soul validate ``` URL: https://cortexprism.io/docs/cli/soul --- ### Start # `cortex start` Start the Cortex HTTP server and background daemon processes. ## Usage ```bash cortex start [options] ``` ## Options | Option | Description | |--------|-------------| | `--port, -p` | Port for the HTTP server (default: 3000) | | `--host, -H` | Host to bind to (default: 127.0.0.1) | | `--daemon-only` | Start only the daemon processes | | `--server-only` | Start only the HTTP server | | `--help` | Show help for this command | ## Examples ```bash # Start Cortex cortex start # Start on custom port cortex start -p 8080 -H 0.0.0.0 # Start only the server cortex start --server-only ``` URL: https://cortexprism.io/docs/cli/start --- ### Stop # `cortex stop` Stop the Cortex HTTP server, background daemon processes, or both. ## Usage ```bash cortex stop # Stop server + daemons cortex stop --server-only # Stop only the HTTP server cortex stop --daemon-only # Stop only the daemon processes cortex stop -p 3000 # Stop server on a specific port ``` ## Options | Option | Description | |--------|-------------| | `--port, -p` | Port of the server to stop (default: 3000) | | `--server-only` | Stop only the HTTP server, keep daemons running | | `--daemon-only` | Stop only daemon processes, keep server running | | `--help` | Show help for this command | ## Process Shutdown On stop, Cortex performs a graceful shutdown: 1. `SIGTERM` sent to the target process 2. 5-second grace period for clean shutdown 3. `SIGKILL` if process hasn't exited ## Examples ```bash # Stop everything cortex stop # Stop only the server cortex stop --server-only # Stop only daemons cortex stop --daemon-only # Stop server on custom port cortex stop -p 8080 ``` URL: https://cortexprism.io/docs/cli/stop --- ### Triggers # `cortex triggers` An event-driven trigger system that responds to external events by launching agent tasks. Supports three trigger sources: file system watchers, HTTP webhooks, and git hooks. ## Usage ```bash cortex triggers [options] ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `add` | Add a new trigger configuration | | `remove` | Remove a trigger configuration | | `install-hooks` | Install git hooks into a repository | | `uninstall-hooks` | Remove git hooks from a repository | ## Trigger Sources ### File Watcher Watch filesystem paths for changes and trigger agent tasks. ```yaml source: watcher paths: - "src/**/*.ts" - "config/*.yaml" patterns: - "*.ts" - "*.json" events: - create - modify - delete debounceMs: 500 ``` ### Webhooks Receive HTTP POST requests from external services with HMAC signature verification. ```yaml source: webhook path: "/hooks/github" secretEnv: "GITHUB_WEBHOOK_SECRET" providers: - github - gitlab - generic events: - push - pull_request - issues ``` ### Git Hooks Install shell scripts into `.git/hooks/` that POST to the webhook endpoint. ```yaml source: git_hook repoPath: "/home/user/project" hooks: - pre-commit - post-commit - pre-push branches: - main - develop ``` ## Trigger Actions Each trigger can be configured with an action: ```yaml action: type: agent_turn agent: code-reviewer promptTemplate: "Review the changes in {{ changed_files }}" timeoutSeconds: 300 ``` Template variables available in prompts: - `{{ event_type }}` — The event that fired - `{{ changed_files }}` — List of changed files - `{{ provider }}` — Webhook provider name - `{{ branch }}` — Git branch name ## Rate Limiting Triggers support configurable rate limiting: ```yaml rateLimit: count: 10 perSeconds: 60 cooldownSeconds: 30 ``` ## Webhook Security Webhooks support HMAC-SHA256 signature verification for GitHub, GitLab, and generic providers. IP allowlisting can be configured for additional security. ## Examples ```bash # Add a file watcher trigger cortex triggers add # Add a webhook trigger cortex triggers add # Install git hooks in a repository cortex triggers install-hooks /path/to/repo # Remove git hooks cortex triggers uninstall-hooks /path/to/repo # Remove a trigger cortex triggers remove ``` URL: https://cortexprism.io/docs/cli/triggers --- ### Tui # `cortex tui` Launch the Terminal User Interface (TUI) for Cortex, providing an interactive streaming chat experience in the terminal. ## Usage ```bash cortex tui ``` ## Overview The TUI provides a split-pane terminal interface for interacting with Cortex: - **Left pane**: Streaming chat with the agent - **Right pane**: Tool calls and command history - Keyboard-driven navigation and command input ## Examples ```bash # Launch the terminal UI cortex tui ``` URL: https://cortexprism.io/docs/cli/tui --- ### Uninstall # `cortex uninstall` Remove Cortex system service and daemon configurations. ## Usage ```bash cortex uninstall [options] ``` ## Options | Option | Description | |--------|-------------| | `--daemon-only` | Uninstall only the daemon service | | `--server-only` | Uninstall only the HTTP server service | | `--help` | Show help for this command | ## Examples ```bash # Uninstall Cortex cortex uninstall # Uninstall only daemon cortex uninstall --daemon-only ``` URL: https://cortexprism.io/docs/cli/uninstall --- ### Update # `cortex update` Manage Cortex updates including checking for new versions, applying updates, rolling back, and configuring update channels. Supports both binary and source update modes. ## Usage ```bash cortex update --check # Check for available updates cortex update --force # Apply latest update cortex update --channel stable # Switch to stable channel cortex update --rollback # Rollback to previous version cortex update --status # Show current version and channel info ``` ## Options | Option | Description | |--------|-------------| | `--check` | Check for available updates without applying | | `--channel` | Set update channel (`stable`, `pre-release`) | | `--rollback` | Rollback to the previous installed version | | `--status` | Display current version, channel, and update state | | `--force` | Force apply update even if already on latest | | `--help` | Show help for this command | ## Update Channels | Channel | Description | |---------|-------------| | `stable` | Production-ready releases with full testing | | `pre` | Pre-release builds with latest features | ## Update Modes ### Binary Mode Downloads pre-built binaries with SHA-256 verification and optional GPG signature validation. The binary is downloaded to `~/.cortex/updates/` and atomically replaced. ### Source Mode Pulls the latest source from the Cortex repository and rebuilds. Used when running from source or when binary mode is unavailable for the platform. ## Configuration The update system can be configured in the `~/.cortex/config.json` file: ```json { "update": { "channel": "stable", "checkOnStartup": true, "autoUpdate": false, "checkIntervalHours": 24, "githubToken": "ghp_...", "gpgKeyPath": "/path/to/gpg/key" } } ``` ## Verification All updates are verified using: - **SHA-256**: Binary hash comparison against the release manifest - **GPG Signatures**: Optional GPG signature verification when `gpgKeyPath` is configured - **Atomic Replacement**: Updates are applied atomically to prevent corruption ## Examples ```bash # Check if an update is available cortex update --check # Apply the latest stable update cortex update --force # Switch to pre-release channel cortex update --channel pre-release # Rollback to previous version cortex update --rollback # View current version and channel cortex update --status ``` URL: https://cortexprism.io/docs/cli/update --- ### Vault # `cortex vault` Manage encrypted credentials using AES-256-GCM encryption with PBKDF2 key derivation. The vault stores sensitive credentials like API keys and secrets securely on disk. ## Usage ```bash export CORTEX_VAULT_KEY="your-passphrase" cortex vault store "" --service # Prompts for value cortex vault get "" # Retrieve and decrypt value cortex vault list # List all stored entries cortex vault delete "" # Delete an entry ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `store` | Store a new encrypted credential (prompts for value) | | `get` | Retrieve and decrypt a credential | | `list` | List all stored credential names | | `delete` | Delete a stored credential | ## Options | Option | Description | |--------|-------------| | `--service` | Service name to associate with the credential (for `store`) | | `--type, -t` | Credential type: `api_key`, `token`, or `password` (default: `api_key`) | | `--help` | Show help for this command | ## Encryption Details ``` vaultStore(name, value): passphrase = Deno.env.get('CORTEX_VAULT_KEY') key = PBKDF2(passphrase, salt='cortex-vault-salt-v1', 100000 iterations, SHA-256) → AES-256 key iv = crypto.getRandomValues(12 bytes) ciphertext = AES-GCM-256.encrypt(iv, key, value) store(iv || ciphertext) in vault_entries vaultGet(name): buf = vault_entries[name].encrypted_data iv = buf[0:12] cipher = buf[12:] plaintext = AES-GCM-256.decrypt(iv, key, cipher) vault_access_log.insert(...) return plaintext ``` ## Security Notes - The passphrase is never stored — only held in the environment variable at runtime - All access is logged to `vault_access_log` for audit - Default deny rules protect against common dangerous patterns ## Examples ```bash # Set the vault passphrase export CORTEX_VAULT_KEY="my-strong-passphrase" # Store an API key cortex vault store "openai-key" --service openai # Retrieve an API key (outputs to stdout) cortex vault get "openai-key" # List all stored credentials cortex vault list # Delete a credential cortex vault delete "openai-key" ``` URL: https://cortexprism.io/docs/cli/vault --- ### Voice # `cortex voice` Manage voice mode for Cortex, enabling voice-based interaction with agents. Supports speech-to-text (OpenAI Whisper) and text-to-speech (OpenAI TTS or ElevenLabs). ## Usage ```bash cortex voice [options] ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `enable` | Enable voice mode | | `disable` | Disable voice mode | | `status` | Show voice mode status | | `set-voice` | Select a voice profile | | `set-speed` | Adjust speech speed | ## Examples ```bash # Enable voice mode cortex voice enable # Check voice status cortex voice status # Select a voice cortex voice set-voice # Adjust speech speed cortex voice set-speed # Disable voice mode cortex voice disable ``` URL: https://cortexprism.io/docs/cli/voice --- ### Workflow # `cortex workflow` A DSL-based workflow engine for defining and executing multi-step agent tasks. Supports sequential steps, conditional branching, parallel execution, goto jumps, and human-in-the-loop approval waits. ## Usage ```bash cortex workflow [options] ``` ## Subcommands | Subcommand | Description | |------------|-------------| | `run` | Execute a workflow | | `approve` | Approve a paused workflow step | ## Workflow Nodes | Node Type | Description | |-----------|-------------| | `step` | Sequential execution step | | `branch` | Conditional branching (if/then/else) | | `parallel` | Parallel execution of multiple steps | | `goto` | Jump to a specific step (loops) | | `wait` | Pause execution awaiting human approval | ## Fluent API Workflows are built using a fluent builder pattern: ```typescript Workflow.create("deploy") .step("build", async (ctx) => { ... }) .step("test", async (ctx) => { ... }) .branch("check", (ctx) => ctx.testsPassed) .then("deploy", async (ctx) => { ... }) .else("rollback", async (ctx) => { ... }) .waitForApproval("confirm", "Deploy to production?") .execute(context) ``` ## Lifecycle Callbacks Each step supports lifecycle hooks: - `onStepStart` — Called before step execution - `onStepEnd` — Called after step execution completes ## Built-in Workflows Cortex ships with a `health-check` workflow that runs system diagnostics: - Disk space check (`df`) - Memory check (`free`) - Returns system health report ## Examples ```bash # Run a workflow cortex workflow run # Approve a waiting workflow step cortex workflow approve ``` URL: https://cortexprism.io/docs/cli/workflow --- ## Architecture ### Agent Loop # Agent Loop The agent loop is the core execution engine of CortexPrism. `agentTurn()` handles one complete user→agent exchange. ## Execution Flow ``` agentTurn(opts) 1. injectMemory(systemPrompt, hits) ← prepend relevant memory 2. persistMessage(userMessage) 3. [TOOL LOOP — up to MAX_TOOL_ROUNDS=8] a. LLM call (stream or complete) b. parseToolCalls(response) ← extract {...} c. for each call: - validateToolCall() ← Parallax policy check - tool.execute() - logEvent(tool_call) d. formatToolResults() → re-prompt 4. persistMessage(agentResponse) 5. incrementTurn(sessionId) 6. writeEpisodic(summary) ← fire-and-forget 7. reflectOnTurn() [if enabled] ← fire-and-forget 8. logEvent(llm_call) return AgentTurnResult ``` ## Agent Options | Option | Type | Purpose | |--------|------|---------| | `userMessage` | string | User input | | `provider` | LLMProvider | Active LLM provider | | `model` | string | Model name | | `sessionDb` | Db | Per-session SQLite instance | | `sessionId` | string | Session identifier | | `systemPrompt` | string | System prompt (may have memory injected) | | `stream` | boolean | Stream output chunks | | `onChunk` | function | Chunk callback for streaming | | `registry` | ToolRegistry | Registered tools | | `toolContext` | ToolContext | Working dir, approval gate | | `embedder` | EmbeddingProvider | For memory retrieval | | `enableReflection` | boolean | Post-turn reflection | ## Tool Loop Detail The tool loop runs up to 8 rounds per user turn. Each round: 1. LLM generates a response (may contain tool calls) 2. Tool calls are parsed from `{"tool":"x","args":{...}}` format 3. Each tool call is validated through the Parallax security gate 4. Valid tool calls are executed; results are formatted and sent back to the LLM 5. The LLM can then respond or make additional tool calls This enables complex multi-step reasoning chains without returning control to the user. ## Configuration Configured via the agent section of `~/.cortex/config.json`: ```json { "agent": { "name": "Cortex", "maxTurns": 50, "streamOutput": true } } ``` - `maxTurns`: Maximum conversation turns before session auto-closes - `streamOutput`: Enable streaming token-by-token output - `name`: Agent name used in system prompts URL: https://cortexprism.io/docs/architecture/agent-loop --- ### Channels # Communication Channels The channels system provides a plugin-based architecture for connecting Cortex agents to external messaging platforms. Each channel binds an agent to a specific platform, routing messages bidirectionally. ## Architecture ``` ┌──────────────────────────────────────────────────────────┐ │ Channel System │ │ │ │ Channel Manager ──► Plugin Registry │ │ │ │ │ │ ▼ ▼ │ │ Discord Adapter [Future: Slack, Teams, Telegram] │ │ │ │ │ ▼ │ │ Gateway WebSocket ←→ Discord API │ │ │ │ │ ▼ │ │ Agent (bound per channel) │ └──────────────────────────────────────────────────────────┘ ``` ## Channel Plugin Interface Each platform implements the `ChannelPlugin` interface: ```typescript interface ChannelPlugin { connect(config: ChannelConfig): Promise; disconnect(): Promise; onEvent(handler: (event: ChannelEvent) => void): void; send(message: OutboundMessage): Promise; edit(messageId: string, content: string): Promise; react(messageId: string, emoji: string): Promise; delete(messageId: string): Promise; typing(channelId: string): Promise; upload(channelId: string, file: Attachment): Promise; } ``` ## Message Types | Target | Description | |--------|-------------| | `dm` | Direct message with a user | | `group` | Group/multi-user chat | | `channel` | Server channel | | `thread` | Thread within a channel | ## Discord Implementation The Discord adapter (`channels/discord.ts`) connects via Gateway WebSocket: 1. **Authentication**: Bot token-based connection 2. **Heartbeat**: Keep-alive pings at Discord's required interval 3. **Message Handling**: Prefix-based command parsing (`!cortex`) 4. **Rich Embeds**: Support for embedded messages with fields, footers, and colors 5. **Reaction Handling**: Respond to emoji reactions on messages ## Event Flow ``` User sends message in Discord → Gateway WebSocket receives MESSAGE_CREATE → ChannelPlugin.onEvent fires → Channel manager routes to bound agent → Agent processes message (LLM + tools pipeline) → Agent response sent back via ChannelPlugin.send → Message appears in Discord channel ``` ## Configuration ```json { "channels": { "discord": { "token": "", "prefix": "!cortex", "agent": "default-agent" } } } ``` See also: [Discord Bot](/docs/cli/discord), [Triggers System](/docs/architecture/triggers) URL: https://cortexprism.io/docs/architecture/channels --- ### Daemon Supervisor # Daemon Supervisor The daemon supervisor manages three background processes required for tool security and job scheduling. It provides automatic crash recovery with exponential backoff. ## Architecture ``` cortex daemon start / chat / serve auto-start │ ▼ supervisor-process.ts │ ├── validator-process.ts ← IPC socket: approves/rejects tool intents │ policy check → allow/deny → logged to Lens │ ├── executor-process.ts ← IPC socket: executes approved tool calls │ file read/write, shell commands, directory listing │ └── scheduler-process.ts ← DB polling: runs cron jobs every 30s memory consolidation, scheduled commands ``` ## Managed Processes | Process | Socket | Permissions | Description | |---------|--------|-------------|-------------| | **Validator** | `/tmp/cortex/validator.sock` | Read/write/net/env/sys | Policy checks for tool intents | | **Executor** | `/tmp/cortex/executor.sock` | Read/write/run/net/env/sys | Executes approved tool calls | | **Scheduler** | `/tmp/cortex/scheduler.sock` | Read/write/run/net/env/sys | Polls DB for due jobs every 30s | ## Supervision Loop - Each child is spawned via `Deno.Command` with scoped `--allow-*` permissions (principle of least privilege) - On crash (non-zero exit), supervisor waits `min(2^n × 1s, 30s)` then restarts - On clean exit (zero exit), process is not restarted (intentional shutdown) - `SIGINT` / `SIGTERM` triggers cascading shutdown of all children ## IPC Protocol All daemons communicate via Unix domain sockets: ``` /tmp/cortex/validator.sock /tmp/cortex/executor.sock /tmp/cortex/scheduler.sock ``` - Messages are JSON-line format - Connection-per-message model - Heartbeat pings check liveness ## Auto-Start `cortex chat` and `cortex serve` call `ensureDaemons()` which pings the validator socket and starts the supervisor if needed. The web server can also run in background via `cortex serve -d`. ## Usage ```bash cortex daemon start # Start supervisor + all daemons in background cortex daemon stop # Stop all daemon processes cortex daemon restart # Stop, wait 1s, then start cortex daemon run # Run supervisor in foreground (for systemd/tmux) cortex daemon status # Show running/stopped status ``` URL: https://cortexprism.io/docs/architecture/daemon-supervisor --- ### Databases # Databases CortexPrism uses multiple SQLite databases, each serving a specific purpose. All databases use WAL mode via `@libsql/client` for concurrent read/write performance. ## Database Overview | Database | File | Contents | Migrations | |----------|------|----------|------------| | Core | `cortex.db` | Sessions, turns, jobs, policy rules | 001, 007, 009 | | Memory | `memory.db` | 5-tier memory, FTS5, embeddings | 002, 008 | | Lens | `lens.db` | Audit events (all system activity) | 003 | | Vault | `vault.db` | Encrypted credentials + access log | 004 | | Plugins | `plugins.db` | Plugin registry | 005 | | Session | `sess_*.db` | Per-session message history | 006 | ## Migration History Core migrations (23+ total across all databases): | Migration | Database | Description | |-----------|----------|-------------| | 001_core.sql | cortex.db | Core schema: sessions, turns, jobs | | 002_memory.sql | memory.db | 5-tier memory tables + FTS5 virtual tables | | 003_lens.sql | lens.db | Lens audit events table | | 004_vault.sql | vault.db | Vault entries + access log | | 005_plugins.sql | plugins.db | Plugin registry | | 006_session.sql | sess_*.db | Per-session message store | | 007_jobs_v2.sql | cortex.db | Job scheduler columns | | 008_memory_embeddings.sql | memory.db | Embedding + decay columns | | 009_policy.sql | cortex.db | Policy rules + default deny seeds | | 010-023 | Various | Hub nodes, agents, services, skills, channels, workflows, onboarding, evaluations, triggers, MQM, voice, computer use | ## Data Directory Structure ``` ~/.cortex/ ├── config.json ├── data/ │ ├── cortex.db │ ├── memory.db │ ├── lens.db │ ├── vault.db │ ├── plugins.db │ └── sess_*.db (one per chat session) ``` ## Key Schemas ### Memory (memory.db) | Table | Purpose | |-------|---------| | `episodic_memory` | Turn summaries of user+agent exchanges | | `semantic_memory` | Injected facts and knowledge | | `reflection_memory` | LLM-extracted behavior patterns | | `episodic_memory_fts` | FTS5 virtual table for keyword search | | `semantic_memory_fts` | FTS5 virtual table for keyword search | ### Lens (lens.db) | Table | Purpose | |-------|---------| | `lens_events` | All system events: LLM calls, tool calls, policy checks, session actions | ### Vault (vault.db) | Table | Purpose | |-------|---------| | `vault_entries` | Encrypted credential storage (name, encrypted_data, service) | | `vault_access_log` | Audit trail of all credential access | ## Configuration Database locations are configured via the data directory (default: `~/.cortex/`): ```bash # Override data directory CORTEX_DATA_DIR=/data/cortex cortex chat ``` URL: https://cortexprism.io/docs/architecture/databases --- ### Git Workspace # Git Workspace Cortex provides a full git porcelain interface executed through the agent workspace. Ten subcommands provide complete git version control with agent-powered features like auto-generated commit messages and diff analysis. ## Architecture ``` ┌──────────────────────────────────────────────────────────┐ │ Git Workspace │ │ │ │ CLI (cortex git) ──► git-cmd.ts ──► Git Operations │ │ │ │ │ ▼ │ │ Agent Integration │ │ (commit messages, diff analysis, │ │ branch suggestions, PR descriptions) │ └──────────────────────────────────────────────────────────┘ ``` ## Subcommands | Command | Description | Agent Integration | |---------|-------------|-------------------| | `status` | Working tree status | Suggestions for next actions | | `log` | Commit history | Analysis of commit patterns | | `diff` | Changes between commits | Summarized diff explanations | | `add` | Stage files | Intelligent staging suggestions | | `commit` | Create commit | Auto-generated commit messages | | `push` | Push to remote | PR-ready push workflows | | `pull` | Pull from remote | Conflict resolution assistance | | `clone` | Clone repository | Automatic setup | | `branch` | Branch management | Naming convention enforcement | | `remote` | Remote management | Remote URL validation | ## Agent-Powered Features Git commands provide full porcelain functionality: 1. **Commit Messages**: Analyze diffs and generate conventional commit messages (`feat:`, `fix:`, `refactor:`, etc.) 2. **Diff Analysis**: Summarize changes in natural language for code review 3. **Branch Naming**: Suggest consistent branch names based on convention 4. **Conflict Detection**: Identify potential merge conflicts before they occur 5. **PR Descriptions**: Generate comprehensive pull request descriptions from commit history ## Pipeline Integration Git operations flow through the Cortex pipeline system, enabling hooks at each stage: - Pre-commit: Content safety checks, secret detection - Post-commit: Memory consolidation of changes - Pre-push: Validation of commit quality - Post-clone: Automatic project setup See also: [GitHub Integration](/docs/architecture/github-integration), [Pipeline System](/docs/architecture/pipeline) URL: https://cortexprism.io/docs/architecture/git-workspace --- ### Github Integration # GitHub Integration Cortex provides deep GitHub integration for managing pull requests, issues, and repositories directly from the CLI, with agent-powered automation for code review and project management. ## Architecture ``` ┌──────────────────────────────────────────────────────────┐ │ GitHub Integration │ │ │ │ CLI (cortex github) ──► github-cmd.ts ──► GitHub API │ │ │ │ │ ▼ │ │ Subsystem Integration │ │ (Vault for tokens, Agent for reviews, │ │ Git workspace for branch/repo context) │ └──────────────────────────────────────────────────────────┘ ``` ## Subcommand Tree ### Pull Requests | Command | Description | |---------|-------------| | `pr list` | List pull requests (filterable by state, limit) | | `pr get` | Get pull request details | | `pr create` | Create a pull request (with draft and body options) | | `pr merge` | Merge a pull request (merge, squash, rebase) | | `pr close` | Close a pull request | ### Issues | Command | Description | |---------|-------------| | `issue list` | List issues (filterable by state, labels, limit) | | `issue create` | Create an issue (with body, labels, assignees) | | `issue close` | Close an issue | ### Repositories | Command | Description | |---------|-------------| | `repo list` | List repositories (filterable by type, limit) | | `repo get` | Get repository details | | `repo branches` | List branches in a repository | ## Authentication GitHub tokens are stored encrypted in the Cortex vault (AES-256-GCM). Required scopes: - `repo` — Repository access - `read:org` — Organization membership - `issues:read/write` — Issue management ## Agent Integration GitHub commands can trigger agent workflows: - **PR Creation**: Agent generates PR title and description from branch diff - **Code Review**: Agent reviews PRs and submits inline comments - **Issue Triage**: Agent categorizes and labels incoming issues - **Release Notes**: Agent generates release notes from merged PRs See also: [Git Workspace](/docs/architecture/git-workspace), [Workflow Engine](/docs/architecture/workflow) URL: https://cortexprism.io/docs/architecture/github-integration --- ### Architecture Overview # Architecture Overview CortexPrism is a single-process agentic harness written in TypeScript/Deno. It exposes a CLI, a REST API + WebSocket server, and a web UI. All state is persisted in SQLite databases using WAL mode via `@libsql/client`. ## High-Level Architecture ``` ┌─────────────────────────────────────────────────────────────────┐ │ CortexPrism │ │ │ │ CLI (cortex chat / run / serve / ...) │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────┐ │ │ │ agent/loop.ts │ │ │ │ userMessage → [memory inject] → LLM call │ │ │ │ → [tool parse] → [validator] → [execute] │ │ │ │ → [re-prompt loop] → response │ │ │ │ → [episodic write] → [reflection] │ │ │ └─────────────────────────────────────────────┘ │ │ │ │ │ ┌──────┼──────────────────────────────────────┐ │ │ │ │ Subsystems │ │ │ │ memory/ tools/ sandbox/ security/ │ │ │ │ llm/ server/ scheduler/ │ │ │ └──────────────────────────────────────────────┘ │ │ │ │ SQLite databases (WAL mode) │ │ cortex.db · memory.db · lens.db · vault.db · sess_*.db │ └─────────────────────────────────────────────────────────────────┘ ``` ## Core Components | Component | Description | |-----------|-------------| | **Agent Loop** | Core reasoning + tool loop that orchestrates LLM calls, tool execution, memory operations, and reflection | | **Memory System** | 5-tier memory with hybrid FTS5 keyword + vector embedding retrieval and exponential decay scoring | | **LLM Layer** | 24 provider implementations with unified `LLMProvider` interface and CascadeRouter | | **Tool System** | Extensible tool registry with built-in tools for file I/O, shell, web search, and code execution | | **Security (Parallax)** | 3-stage policy validation gate with encrypted vault, regex deny rules, and full audit logging | | **Sandbox** | Docker container sandbox (subprocess fallback) with resource limits and auto-fix loop | | **Daemon Supervisor** | Background process manager for validator, executor, and scheduler daemons with auto-restart | | **HTTP Server** | Built-in web server with REST API, WebSocket streaming, and web UI dashboard | | **Scheduler** | SQLite-persisted cron job scheduler with retry | | **Model Quartermaster** | Adaptive 6-signal model selection engine with reinforcement learning and context fingerprinting | | **Git Workspace** | Agent-powered git porcelain with auto-commit messages, diff analysis, and branch management | | **GitHub Integration** | PR, issue, and repository management with agent-powered code review and triage | | **Pipeline System** | 12-stage hook-based processing pipeline for the agent turn lifecycle (pre/post-assess, pre/post-reason, pre/post-tool, pre/post-llm, pre/post-reflect, pre/post-output) | | **Trigger System** | File watchers, webhooks, and git hooks that launch agent tasks on external events | | **Workflow Engine** | DSL-based workflow execution with steps, branches, parallel execution, and approval gates | | **Communication Channels** | Plugin-based messaging platform integration (Discord, extensible) | | **Remote Agents** | Distributed node execution via WebSocket hub with capability-based security tiers | | **MCP Server** | Model Context Protocol server exposing Cortex tools and agents to MCP clients | | **Update System** | Dual-mode updates (binary/source) with SHA-256 verification and rollback | | **Observability** | Prometheus-compatible metrics registry and distributed tracing with OTLP export | | **Desktop Automation** | Cross-platform GUI automation (screenshots, clicks, typing, clipboard) for Linux, macOS, Windows | | **Evaluation Framework** | Agent benchmarking with 8 task categories, pattern scoring, and regression detection | | **Hub Node System** | Distributed hub with WebSocket-based node registry, capability tiers, and session routing | | **Lens Audit Log** | Immutable event log for all system actions — LLM calls, tool execution, policy decisions | ## Data Flow 1. User input enters through CLI, Web UI, or API 2. Agent loop processes input with context from memory 3. LLM provider generates response via the model router 4. Tool calls are executed through the Parallax security gate 5. Results are stored in memory and returned to the user ## Core subsystems - [Agent Loop](/docs/architecture/agent-loop) — Core execution engine - [Memory System](/docs/architecture/memory-system) — 5-tier memory architecture - [Security Parallax](/docs/architecture/security-parallax) — Defense-in-depth security model - [Model Router](/docs/architecture/model-router) — Intelligent LLM provider routing - [Daemon Supervisor](/docs/architecture/daemon-supervisor) — Background process management - [Plugin System](/docs/architecture/plugin-system) — Plugin architecture - [Databases](/docs/architecture/databases) — SQLite database schemas - [Quartermaster](/docs/architecture/quartermaster) — Model Quartermaster prediction engine - [Git Workspace](/docs/architecture/git-workspace) — Agent-powered git porcelain - [GitHub Integration](/docs/architecture/github-integration) — PR/issue/repo management - [Pipeline System](/docs/architecture/pipeline) — 12-stage hook-based pipeline - [Channels](/docs/architecture/channels) — Communication channel plugins - [Triggers](/docs/architecture/triggers) — Event-driven trigger system - [Workflow Engine](/docs/architecture/workflow) — DSL-based workflow execution - [Remote Agents](/docs/architecture/remote-agents) — Distributed agent nodes - [MCP Server](/docs/architecture/mcp-server) — Model Context Protocol server - [Update System](/docs/architecture/update-system) — Binary/source updates and rollback - [Observability](/docs/architecture/observability) — Metrics and tracing URL: https://cortexprism.io/docs/architecture --- ### Mcp Server # MCP Server Cortex implements a Model Context Protocol (MCP) server, enabling any MCP-compatible client (editors, IDEs, other AI applications) to use Cortex as their agentic backend. ## Architecture ``` ┌──────────────────────────────────────────────────────────┐ │ MCP Server │ │ │ │ MCP Client (IDE/Editor) │ │ │ │ │ ▼ stdio (JSON-RPC) │ │ ┌──────────────────────────────────────────────┐ │ │ │ MCP Server (mcp/server.ts) │ │ │ │ │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ │ Tools │ │ Memory │ │ Sessions│ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ │ │ │ └──────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────┘ ``` ## Transport The MCP server uses **stdio transport** — standard input/output for process-level integration. This is the most common MCP transport pattern and enables direct embedding in editors and IDEs that support MCP. ## Exposed Capabilities Via MCP, clients can access: | Capability | MCP Mapping | |------------|-------------| | **Tools** | MCP tools — file I/O, shell execution, web search, code execution | | **Memory** | MCP resources — search, retrieve, and inject memory entries | | **Agents** | MCP prompts — agent-specific system prompts and templates | | **Sessions** | MCP sampling — create and resume chat sessions | ## Protocol The MCP server implements the standard Model Context Protocol with: - **JSON-RPC 2.0** message format - **Initialize/Capability negotiation** - **Tool listing and execution** - **Resource listing and reading** - **Prompt listing and retrieval** ## Integration Examples ### VS Code / Cursor Configure your MCP settings to launch Cortex: ```json { "mcpServers": { "cortex": { "command": "cortex", "args": ["mcp", "stdio"] } } } ``` ### Claude Desktop Add Cortex as an MCP server in Claude Desktop settings to use Cortex tools directly from Claude conversations. See also: [MCP CLI](/docs/cli/mcp), [Plugin System](/docs/architecture/plugin-system) URL: https://cortexprism.io/docs/architecture/mcp-server --- ### Memory System # Memory System CortexPrism features a sophisticated 5-tier memory architecture with hybrid retrieval combining FTS5 keyword search and cosine vector similarity, scored with exponential time decay. ## Memory Architecture ``` retrieve(query, embedder) │ ├── keywordSearch(query) → FTS5 BM25 over episodic_memory + semantic_memory │ ├── vectorSearch(embed) → cosine similarity over stored embeddings │ embedding = embedder.embed(query) if embedder available │ └── merge + decay-score score = raw_score × 2^(-age_days / half_life_days) sorted descending → top-K ``` ## Memory Tiers | Tier | Database Table | Retention | Content | |------|---------------|-----------|---------| | **Episodic** | `episodic_memory` | Auto-decay based on half-life | Turn summaries — user+agent exchanges | | **Semantic** | `semantic_memory` | Indefinite unless pruned | Injected facts / knowledge / entities | | **Reflection** | `reflection_memory` | Consolidated weekly | LLM-extracted behavior patterns | | **Graph** | `entity_graph` | Built from semantic extraction | Knowledge graph nodes and edges | | **Skills** | `skills` table | Persisted indefinitely | Procedural knowledge from sessions | ## Storage | Table | Type | Contents | |-------|------|----------| | `episodic_memory` | Row | Turn summaries — user+agent exchanges | | `semantic_memory` | Row | Injected facts / knowledge | | `reflection_memory` | Row | LLM-extracted behaviour patterns | | `entity_graph` | Row | Knowledge graph nodes and edges | | `skills` | Row | Procedural knowledge from sessions | | `episodic_memory_fts` | FTS5 | Virtual table for keyword search on episodic | | `semantic_memory_fts` | FTS5 | Virtual table for keyword search on semantic | ## Retrieval Algorithm ``` 1. FTS5 keyword search across episodic_memory and semantic_memory → BM25 ranking scores 2. Cosine vector similarity (if embedder available) → embedding = embedder.embed(query) → cosine similarity against stored embeddings 3. Merge + decay scoring → score = raw_score × 2^(-age_days / half_life_days) → half_life_days: configurable per tier (default: 7 days) 4. Sort descending → return top-K results ``` ## Embedding Providers | Provider | Backend | Model | Use Case | |----------|---------|-------|----------| | `OllamaEmbedder` | Ollama `/api/embeddings` | Configurable | Local embedding generation | | `OpenAIEmbedder` | OpenAI API | `text-embedding-3-small` | Cloud embedding generation | | `StubEmbedder` | Deterministic hash | — | No external service needed (default) | ## Memory Injection `injectMemory(systemPrompt, hits)` prepends retrieved content to the system prompt: ``` --- Relevant Memory --- [episodic] 2026-06-14: User: ... Assistant: ... [semantic] CortexPrism uses SQLite WAL mode --- ``` This ensures the agent has relevant context from past interactions without exceeding token limits. ## Operations - `store`: Save information to a memory tier (episodic or semantic) - `search`: Query memories across tiers with hybrid retrieval - `retrieve`: Get specific memories by ID - `forget`: Remove memories - `compress`: Summarize and archive older memories URL: https://cortexprism.io/docs/architecture/memory-system --- ### Model Router # Model Router (RouteLLM) The model router provides intelligent LLM provider selection through a cascading confidence-based routing system. It automatically escalates to more capable models when the current model's confidence is low. ## CascadeRouter `CascadeRouter` wraps multiple providers in a cascade chain. On each call: ``` 1. Tries first provider in cascade (cheapest) 2. Calls estimateConfidence(text) — heuristic based on hedging language 3. If confidence < threshold → tries next provider in cascade 4. Returns last result if all providers exhausted ``` This cost-optimized approach ensures simple queries use cheaper models while complex reasoning escalates to more capable ones. ## Configuration ```json { "router": { "enabled": true, "confidenceThreshold": 0.7, "cascade": [ { "provider": "ollama", "model": "llama3.2:3b" }, { "provider": "ollama", "model": "llama3.1:8b" }, { "provider": "anthropic", "model": "claude-sonnet-4-20250514" } ] } } ``` | Option | Default | Description | |--------|---------|-------------| | `enabled` | false | Enable or disable the router | | `confidenceThreshold` | 0.7 | Minimum confidence score to accept a response (0.0–1.0) | | `cascade` | [] | Ordered list of provider+model pairs to try | ## Supported Providers | Provider | Kind | Default Model | |----------|------|---------------| | Anthropic | `anthropic` | `claude-sonnet-4-20250514` | | OpenAI | `openai` | `gpt-4o` | | Google Gemini | `google` | `gemini-2.0-flash` | | Mistral | `mistral` | `mistral-large-latest` | | Groq | `groq` | `llama-3.3-70b-versatile` | | DeepSeek | `deepseek` | `deepseek-chat` | | OpenRouter | `openrouter` | routes to 200+ models | | xAI (Grok) | `xai` | `grok-2-latest` | | Together AI | `together` | `Llama-3.3-70B-Instruct-Turbo` | | AWS Bedrock | `bedrock` | Claude/Llama/Titan | | Cohere | `cohere` | `command-r-plus` | | Ollama | `ollama` | `llama3.2` (local) | ## Provider Interface All providers implement the `LLMProvider` interface: ```typescript interface LLMProvider { readonly name: string; readonly defaultModel: string; complete(options: CompletionOptions): Promise; stream(options: CompletionOptions): AsyncIterable; } ``` ## Features - **Multi-Provider**: 24 LLM providers through a unified interface - **Cascading Router**: Cheapest model first, escalate on low confidence - **Failover**: Automatic fallback to next provider on errors - **Cost Optimization**: Route simple queries to cheaper/ local models - **Streaming**: All providers support streaming responses URL: https://cortexprism.io/docs/architecture/model-router --- ### Observability # Observability Cortex includes an in-process observability layer with a Prometheus-compatible metrics registry and a distributed tracing system supporting multiple backends and OTLP export. ## Architecture ``` ┌──────────────────────────────────────────────────────────┐ │ Observability │ │ │ │ Metrics Registry Tracing System │ │ ┌────────────────────┐ ┌──────────────┐ │ │ │ Counters │ │ Span Creation │ │ │ │ Gauges │ │ Attributes │ │ │ │ Histograms │ │ Status Codes │ │ │ └────────┬───────────┘ └──────┬───────┘ │ │ │ │ │ │ ▼ ▼ │ │ ┌────────────────────┐ ┌──────────────┐ │ │ │ /metrics endpoint │ │ Backends: │ │ │ │ (Prometheus text) │ │ - lens │ │ │ └────────────────────┘ │ - stdout │ │ │ │ - otlp │ │ │ │ - none │ │ │ └──────────────┘ │ └──────────────────────────────────────────────────────────┘ ``` ## Metrics Registry In-process Prometheus-compatible registry with three metric types: | Type | Purpose | Example | |------|---------|---------| | **Counter** | Monotonically increasing count | Agent turns, tool calls, errors | | **Gauge** | Point-in-time value | CPU %, memory MB, uptime seconds | | **Histogram** | Distribution of values | Turn duration, token I/O, cost per turn | ### Pre-Registered Metrics | Metric | Type | Labels | |--------|------|--------| | `agent_turns_total` | Counter | provider, model | | `agent_turn_duration_seconds` | Histogram | provider, model | | `token_input_total` | Counter | provider, model | | `token_output_total` | Counter | provider, model | | `cost_usd_total` | Counter | provider, model | | `tool_calls_total` | Counter | tool, status | | `errors_total` | Counter | type | | `validator_intents_total` | Counter | status (approved/rejected) | | `scheduler_jobs_total` | Counter | status | | `memory_consolidations_total` | Counter | tier | | `cpu_percent` | Gauge | — | | `memory_mb` | Gauge | — | | `uptime_seconds` | Gauge | — | | `qm_predictions_total` | Counter | confidence_level | | `qm_accuracy` | Gauge | signal | | `mqm_weights` | Gauge | signal | ## Distributed Tracing The tracing system creates spans throughout the agent lifecycle: | Span Name | Parent | Attributes | |-----------|--------|------------| | `agent_turn` | root | session_id, turn_id, model | | `memory_retrieval` | agent_turn | tier, result_count, duration_ms | | `llm_call` | agent_turn | provider, model, tokens_in, tokens_out | | `tool_execution` | agent_turn | tool_name, approved, duration_ms | | `reflection` | agent_turn | patterns_found | | `quartermaster_predict` | agent_turn | confidence, signal_scores | ### Backend Configuration ```json { "tracing": { "backend": "otlp", "otlpEndpoint": "https://collector.example.com:4318/v1/traces" } } ``` Supported backends: - **lens**: Store traces in lens.db audit log (default) - **stdout**: Print spans to stdout for debugging - **otlp**: Export to OpenTelemetry collector - **none**: Disable tracing entirely See also: [Databases](/docs/architecture/databases), [Quartermaster](/docs/architecture/quartermaster) URL: https://cortexprism.io/docs/architecture/observability --- ### Pipeline # Pipeline System The pipeline system provides a hook-based processing framework that wraps every stage of the agent turn lifecycle. Core and plugin hooks execute at 12 distinct pipeline stages with configurable priority, timeout protection, and rich modification capabilities. ## Architecture ``` ┌──────────────────────────────────────────────────────────┐ │ Pipeline System │ │ │ │ 12 Pipeline Stages (in order): │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │pre-assess│→│post-assess│→│pre-reason │→ ... │ │ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌────────────────────────────────────────────┐ │ │ │ Registered Hooks (prioritized) │ │ │ │ Core Hooks + Plugin Hooks │ │ │ └────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────┘ ``` ## 12 Pipeline Stages | Stage | When | Purpose | |-------|------|---------| | `pre-assess` | Before assessment | Pre-filter, context preparation | | `post-assess` | After assessment | Validate assessment output | | `pre-reason` | Before reasoning | Modify reasoning context | | `post-reason` | After reasoning | Validate reasoning output | | `pre-tool` | Before tool execution | Tool call filtering | | `post-tool` | After tool execution | Tool result processing | | `pre-llm` | Before LLM call | Modify LLM request | | `post-llm` | After LLM call | Process LLM response | | `pre-reflect` | Before reflection | Modify reflection context | | `post-reflect` | After reflection | Process reflection output | | `pre-output` | Before final output | Modify user-facing response | | `post-output` | After final output | Post-response side effects | ## Hook Interface ```typescript interface PipelineHook { name: string; stages: PipelineStage[]; priority: number; async: boolean; disableable: boolean; run(ctx: PipelineContext): Promise; } interface HookResult { abort?: boolean; modifyInput?: string; modifyLLMResponse?: string; modifyOutput?: string; injectMessages?: Message[]; sideEffects?: SideEffect[]; } ``` ## Built-in Core Hooks | Hook | Stage | Description | |------|-------|-------------| | **Injection Guard** | pre-reason, pre-tool | Prompt injection and content safety detection | | **MQM Routing** | pre-llm, post-llm | Route model selection via Quartermaster | | **Summarization** | pre-reason | Auto-compact context when approaching token limits | | **Output Truncation** | post-tool, post-output | Truncate tool results and responses | | **Loop Detection** | pre-tool | Detect repetitive tool calls and intervene | | **Tool Output Sandbox** | post-tool | Validate and sanitize tool outputs | | **Audit Log** | post-reason | Log LLM calls and decisions to Lens | | **Cost Tracker** | pre-tool, post-tool | Track per-tool and per-turn cost metrics | ## Hook Registration Hooks can be registered by: - Core system on startup - Plugins via the plugin manager - Custom scripts via the hooks API Each hook has a priority (0–100) determining execution order within a stage. Hooks have timeout protection (5s sync, 15s async) to prevent pipeline stalls. ## Pipeline Context Hooks receive a read-only `PipelineContext` with: - `sessionId`, `turnId` — Current session/turn identifiers - `tokensUsed`, `costUsd` — Current consumption metrics - `toolCallsMade` — Count of tool calls this turn - `setState(key, value)` — Mutate pipeline state See also: [Agent Loop](/docs/architecture/agent-loop), [Plugin System](/docs/architecture/plugin-system) URL: https://cortexprism.io/docs/architecture/pipeline --- ### Plugin System # Plugin System CortexPrism supports three types of plugins: ESM modules, MCP (Model Context Protocol) servers, and WebAssembly modules. The plugin system is designed for extensibility and isolation. ## Plugin Types | Type | Technology | Use Case | |------|-----------|----------| | **ESM** | JavaScript/TypeScript modules | General-purpose plugins, extending agent capabilities | | **MCP** | Model Context Protocol servers | Tool providers following the MCP standard | | **WASM** | WebAssembly modules | Performance-critical tasks, cross-language support | ## Plugin Lifecycle ``` 1. Install → Download and register the plugin in plugins.db 2. Enable → Activate the plugin for use in sessions 3. Use → Call plugin capabilities through the tool system 4. Disable → Deactivate without uninstalling 5. Uninstall → Remove the plugin entirely from registry ``` ## Plugin Registry Plugins are registered in `plugins.db` (SQLite) with: - Name and version - Plugin type (ESM/MCP/WASM) - Author and description - Permissions required - Dependencies - Download count (for marketplace tracking) ## Isolation - Plugins run in isolated sandboxes with restricted permissions - Resource limits are enforced per plugin - The policy engine controls what each plugin can access ## Marketplace Plugins can be published to and discovered through the [CortexPrism Marketplace](/marketplace). The marketplace provides: - Plugin discovery and search - Version management - Dependency resolution - Download tracking - User ratings and reviews ## CLI Management ```bash # Install a plugin from the marketplace cortex plugins install marketplace:cortexprism.io/plugins/python-executor # List installed plugins cortex plugins list # Enable/disable a plugin cortex plugins enable cortex plugins disable # Remove a plugin cortex plugins uninstall ``` URL: https://cortexprism.io/docs/architecture/plugin-system --- ### Quartermaster # Model Quartermaster The Model Quartermaster (MQM) is an adaptive model-selection engine that observes LLM call patterns across sessions, computes weighted signal scores, and predicts the optimal model to use. A legacy Quartermaster (QM) variant also provides 5-signal tool prediction. ## Architecture ``` ┌──────────────────────────────────────────────────────────┐ │ Quartermaster System │ │ │ │ Model Calls ──► 6 Signal Computers ──► Fusion │ │ (trajectory, episodic, cost, quality, historical, │ │ reflection) │ │ │ │ │ ▼ │ │ Weighted Prediction │ │ (automate | suggest | defer) │ │ │ │ │ ▼ │ │ Correct? ──► Reinforcement Learning (EMA weight update) │ └──────────────────────────────────────────────────────────┘ ``` ## Six Prediction Signals | Signal | Source | Weight | |--------|--------|--------| | **Trajectory** | Recent model usage patterns and sequences | Dynamic (EMA) | | **Episodic** | Similar conversation context cosine matching | Dynamic (EMA) | | **Historical** | Past performance data for task categories | Dynamic (EMA) | | **Cost** | Cost efficiency optimization across models | Dynamic (EMA) | | **Quality** | Expected quality based on model capabilities | Dynamic (EMA) | | **Reflection** | Per-turn reflection feedback integration | Dynamic (EMA) | ## Prediction Confidence Levels | Confidence | Action | Safe Tools | Unsafe Tools | |------------|--------|------------|--------------| | ≥ 90% | **Automate** | Auto-execute | Suggest | | 60–89% | **Suggest** | Suggest | Suggest | | < 60% | **Defer** | Defer | Defer | Safe tools are read-only, non-destructive operations. Unsafe tools (shell exec, file write, network) are never auto-executed. ## Active Mode Threshold The Quartermaster requires **50 observations** before entering active prediction mode. Before this threshold, it operates in learning-only mode — collecting data, computing signal baselines, but not making predictions. ## Reinforcement Learning After each prediction, correctness is evaluated: - **Reward (EMA α = 0.15)**: Correct signal weights increase - **Punishment (EMA α = 0.25)**: Incorrect weights decrease faster - **Convergence**: Weights stabilize after ~200–500 observations ## Context Fingerprinting The `contexts.ts` module generates 12-feature fingerprints from conversation context for cosine similarity matching of similar situations. Features include model distribution, message length, token composition, and task category indicators. ## Database Schema The Quartermaster persists state in SQLite tables: - `qm_patterns` — Learned prediction patterns - `qm_decisions` — Historical predictions and outcomes - `qm_session_state` — Per-session quartermaster state - `qm_model_stats` — Aggregated model statistics - `qm_weights` — Current signal weight values ## Observability The Quartermaster emits: - **Lens events**: Every prediction, decision evaluation, weight update, and pattern learned - **Prometheus metrics**: Prediction accuracy, confidence distribution, signal weights, mode changes ## CLI Interface See [`cortex qm`](/docs/cli/qm) and [`cortex mqm`](/docs/cli/qm) for the command-line interface. See also: [Model Router](/docs/architecture/model-router) URL: https://cortexprism.io/docs/architecture/quartermaster --- ### Remote Agents # Remote Agents The remote agent system provides a distributed execution layer where agent nodes connect to a central hub via WebSocket. Nodes register with capability tiers, receive directives, and stream results back. ## Architecture ``` ┌──────────────────────────────────────────────────────────┐ │ Hub (Central) │ │ ┌──────────────────────────────────────────────────┐ │ │ │ WebSocket Server (ws-node.ts) │ │ │ │ - Node authentication (token) │ │ │ │ - Heartbeat monitoring (30s interval) │ │ │ │ - Directive dispatch │ │ │ │ - Result routing to sessions │ │ │ └──────────────────────────────────────────────────┘ │ │ ┌──────────────────────────────────────────────────┐ │ │ │ Node Registry (node-registry.ts) │ │ │ │ - Token management │ │ │ │ - Node lifecycle tracking │ │ │ │ - Persistence (SQLite) │ │ │ └──────────────────────────────────────────────────┘ │ │ ┌──────────────────────────────────────────────────┐ │ │ │ Capability Tiers (capability-tiers.ts) │ │ │ │ root | sudo | unprivileged │ │ │ └──────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────┘ │ WebSocket (WSS)│ ┌──────────────┼──────────────┐ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ Node A │ │ Node B │ │ Node C │ │ (root) │ │ (sudo) │ │ (unpriv)│ └─────────┘ └─────────┘ └─────────┘ ``` ## Capability Tiers ### Root (unrestricted) - All tools available - All filesystem paths (`/`) - All sudo commands - All network domains - Maximum privilege ### Sudo (elevated, scoped) - Excludes system paths: `/etc`, `/root`, `/proc`, `/sys`, `/boot`, `/dev` - Allowed package managers: `apt`, `npm`, `pip`, `systemctl`, `docker` - Blocked destructive: `rm -rf /`, `dd`, `mkfs`, `chmod 777` - Scoped tool access ### Unprivileged (sandboxed) - Read-only tools only (read, list, info) - No shell access - Restricted to `/tmp/cortex-sandbox` - No sudo commands - Minimal attack surface ## Message Protocol ``` Node → Hub: Hub → Node: ┌─────────────┐ ┌──────────────┐ │ register │ │ registered │ │ heartbeat │ │ heartbeat_ack│ │ result │ │ directive │ │ stream_chunk│ │ cancel │ │ disconnect │ │ config_update│ └─────────────┘ │ rekey │ │ error │ └──────────────┘ ``` ## Node Metrics Each heartbeat carries live system metrics from `/proc`: ```typescript interface NodeMetrics { cpuPercent: number; memoryMb: number; diskFreeMb: number; uptimeSeconds: number; } ``` ## Session Routing When a session on the hub dispatches a tool call, the session-router: 1. Evaluates directive against node capability tiers 2. Selects eligible nodes 3. Routes directive to the most appropriate node 4. Streams results back to the originating session ## Connection Management - **Heartbeat**: Every 30 seconds - **Timeout**: 90 seconds without heartbeat → disconnect - **Reconnect**: Exponential backoff (1s, 2s, 4s, 8s, 16s, max 60s) - **Token Rotation**: Nodes support `rekey` for credential rotation See also: [Node CLI](/docs/cli/node), [Security Parallax](/docs/architecture/security-parallax) URL: https://cortexprism.io/docs/architecture/remote-agents --- ### Security Parallax # Parallax Security Model The Parallax security model provides defense in depth through three-stage policy validation, encrypted credential storage, and comprehensive audit logging. ## Three-Stage Validation Gate Every tool call passes through a 3-stage validator before execution: ``` Agent emits → 1. checkPolicy('tool', toolName) — is this tool allowed? → 2. checkPolicy('shell', command) — is the shell command safe? → 3. checkPolicy('domain', hostname) — is the domain allowed? → DENY → error returned to agent (no execution) → ALLOW → tool.execute() runs → Lens: policy_check + tool_call events logged ``` Stage 2 only applies to `shell` and `code_exec` tools. Stage 3 only applies to `web_search` with extracted URLs. ## Policy Engine ``` checkPolicy(kind, value): for rule in rules WHERE kind = ? ORDER BY priority ASC: if regex(rule.pattern).test(value): return { allowed: rule.effect === 'allow', reason: rule.reason } return { allowed: true, reason: 'default allow' } ``` Rules are evaluated by priority (ASC — lower number = higher precedence). If no rule matches, the default is **allow**. ### Default Deny Rules Seeded on first database migration: | Pattern | Blocks | |---------|--------| | `rm\s+-rf\s+/` | Recursive root delete | | `:\(\)\{.*\}` | Fork bomb patterns | | `dd\s+if=.*of=/dev/` | Direct disk writes | | `chmod\s+777\s+/` | World-writable root | ## Credential Vault AES-256-GCM encrypted storage for sensitive credentials: ``` vaultStore(name, value): passphrase = Deno.env.get('CORTEX_VAULT_KEY') key = PBKDF2(passphrase, salt='cortex-vault-salt-v1', 100000, SHA-256) → AES-256 key iv = crypto.getRandomValues(12 bytes) ciphertext = AES-GCM-256.encrypt(iv, key, value) store(iv || ciphertext) in vault_entries vaultGet(name): buf = vault_entries[name].encrypted_data iv = buf[0:12]; cipher = buf[12:] plaintext = AES-GCM-256.decrypt(iv, key, cipher) vault_access_log.insert(...) — Full audit trail return plaintext ``` - Passphrase is **never** stored — only held in environment variable `CORTEX_VAULT_KEY` at runtime - All access is logged to `vault_access_log` with timestamps - PBKDF2 with 100,000 iterations of SHA-256 for key derivation ## Security Layers Summary | Layer | Description | |-------|-------------| | Vault | Encrypted storage for secrets and credentials (AES-256-GCM) | | Policy Engine | Granular allow/deny regex rules with priority ordering | | Approval Gates | Configurable approval workflows for sensitive operations | | Sandboxing | Isolated Docker containers for code execution with resource limits | | Audit Logging | Comprehensive logging of all security-relevant events in Lens | | Default Deny | Pre-seeded rules blocking known dangerous patterns | ## Audit Trail (Cortex Lens) All security decisions are logged: - Every policy check (allowed/denied with reason) - Every tool call (tool name, arguments, timestamp) - Every vault access (credential name, access time) - Session events (create, resume, close) - LLM calls (provider, model, token usage, cost) URL: https://cortexprism.io/docs/architecture/security-parallax --- ### Triggers # Trigger System The trigger system provides an event-driven architecture that responds to external events by launching agent tasks. Three trigger sources support file system changes, HTTP webhooks, and git hook events. ## Architecture ``` ┌──────────────────────────────────────────────────────────┐ │ Trigger System │ │ │ │ Sources: │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Webhook │ │ Watcher │ │ Git Hook │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌────────────────────────────────────────┐ │ │ │ Trigger Manager │ │ │ │ (rate limiting, templates, routing) │ │ │ └─────────────────┬──────────────────────┘ │ │ │ │ │ ▼ │ │ ┌────────────────────────────────────────┐ │ │ │ Agent Job Creation │ │ │ │ (prompt template → agent turn/job) │ │ │ └────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────┘ ``` ## Trigger Sources ### Webhooks - HTTP POST endpoints with configurable paths - HMAC-SHA256 signature verification - Provider support: GitHub, GitLab, generic - IP allowlisting for additional security - Event filtering by webhook event type ### File Watchers - Filesystem monitoring via `Deno.FsWatcher` - Configurable paths and glob patterns - Events: `create`, `modify`, `delete` - Debounce to prevent duplicate triggers (configurable ms) ### Git Hooks - Auto-installs shell scripts into `.git/hooks/` - Supported hooks: `pre-commit`, `post-commit`, `pre-push`, `post-merge` - Branch filtering for targeted triggers - POSTs to local webhook endpoint ## Prompt Templates Triggers use template variables for dynamic prompts: ```yaml promptTemplate: | {{ event_type }} on {{ branch }} Changed files: {{ changed_files }} Review the changes and suggest improvements. ``` Available variables: - `{{ event_type }}` — The triggering event - `{{ changed_files }}` — Modified file paths - `{{ provider }}` — Webhook provider (github/gitlab/generic) - `{{ branch }}` — Git branch name - `{{ repo }}` — Repository name ## Rate Limiting Prevents trigger storms with configurable limits: ```yaml rateLimit: count: 10 # Max triggers perSeconds: 60 # Per time window cooldownSeconds: 30 # Cooldown after limit hit ``` ## Security - **HMAC-SHA256**: Webhook payloads verified against secret - **IP Allowlisting**: Restrict webhook sources by IP/CIDR - **Template Sanitization**: All template variables are escaped - **Timeout**: Agent jobs are capped at configurable timeout (default: 300s) See also: [Hooks CLI](/docs/cli/hooks), [Workflow Engine](/docs/architecture/workflow) URL: https://cortexprism.io/docs/architecture/triggers --- ### Update System # Update System The Cortex update system provides dual-mode updates (binary and source), SHA-256 verification, optional GPG signature validation, channel management, and atomic rollback support. ## Architecture ``` ┌──────────────────────────────────────────────────────────┐ │ Update System │ │ │ │ ┌──────────────────────────────────────────────────┐ │ │ │ Channels │ │ │ │ stable ←→ pre-release │ │ │ └──────────────────────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────┼──────────────────────────┐ │ │ │ Update Modes │ │ │ │ │ │ │ │ Binary Mode Source Mode │ │ │ │ ┌──────────┐ ┌──────────────┐ │ │ │ │ │ Download │ │ Git pull │ │ │ │ │ │ SHA-256 │ │ deno compile │ │ │ │ │ │ GPG sig │ │ Install bin │ │ │ │ │ │ Replace │ └──────────────┘ │ │ │ │ └──────────┘ │ │ │ └──────────────────────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────┼──────────────────────────┐ │ │ │ Rollback │ │ │ │ Previous binary → restore │ │ │ └──────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────┘ ``` ## Update Modes ### Binary Mode 1. Check GitHub releases for latest version 2. Download binary for platform and architecture 3. Verify SHA-256 checksum against release manifest 4. Optionally verify GPG signature (if `gpgKeyPath` configured) 5. Atomically replace current binary with new version 6. Archive previous binary for rollback ### Source Mode 1. Pull latest source from git repository 2. Run `deno compile` to build new binary 3. Install binary to system path 4. No signature verification (source is self-built) ## Channels | Channel | Description | Update Frequency | |---------|-------------|-----------------| | `stable` | Production-ready releases | Weekly/monthly | | `pre-release` | Pre-release builds | Daily/as-needed | ## Configuration ```json { "update": { "channel": "stable", "checkOnStartup": true, "autoUpdate": false, "checkIntervalHours": 24, "githubToken": "ghp_...", "gpgKeyPath": "/path/to/gpg/key" } } ``` ### Configuration Options | Option | Description | Default | |--------|-------------|---------| | `channel` | Update channel (`stable` or `pre-release`) | `stable` | | `checkOnStartup` | Check for updates on cortex start | `true` | | `autoUpdate` | Automatically apply updates | `false` | | `checkIntervalHours` | Periodic check interval | `24` | | `githubToken` | GitHub token for API rate limits | `""` | | `gpgKeyPath` | Path to GPG key for signature verification | `""` | ## Verification All updates include: - **SHA-256**: Checksum comparison against release manifest - **GPG Signatures**: Optional detached signature verification - **Atomic Replacement**: `rename()` ensures no partial updates - **Rollback Safety**: Previous binary preserved for `--rollback` See also: [Update CLI](/docs/cli/update), [Configuration](/docs/getting-started/configuration) URL: https://cortexprism.io/docs/architecture/update-system --- ### Workflow # Workflow Engine A domain-specific language (DSL) based workflow engine for defining and executing multi-step agent tasks. Supports sequential execution, conditional branching, parallel processing, loop constructs, and human approval gates. ## Architecture ``` ┌──────────────────────────────────────────────────────────┐ │ Workflow Engine │ │ │ │ Workflow DSL ──► Engine ──► Execute │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────────┐ │ │ │ Workflow Nodes │ │ │ │ step │ branch │ parallel │ goto │ wait│ │ │ └──────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────────┐ │ │ │ Lifecycle Hooks │ │ │ │ onStepStart → execute → onStepEnd │ │ │ └──────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────┘ ``` ## Node Types | Node | Behavior | |------|----------| | **step** | Sequential execution of a single task | | **branch** | Conditional if/then/else routing | | **parallel** | Concurrent execution via `Promise.allSettled` | | **goto** | Jump to a labeled step (loops, retries) | | **wait** | Pause execution, await human `approve()` call | ## Fluent Builder API Workflows are defined using a fluent builder pattern: ```typescript const workflow = new Workflow("deploy-and-verify") .step("build", async (ctx) => { ctx.set("built", true); }) .step("test", async (ctx) => { ctx.set("testsPassed", true); }) .branch("quality-gate", (ctx) => ctx.testsPassed) .then("deploy-staging", async (ctx) => { /* ... */ }) .else("notify-failure", async (ctx) => { /* ... */ }) .waitForApproval("production-approval", "Deploy to production?") .step("deploy-prod", async (ctx) => { /* ... */ }) .step("verify-prod", async (ctx) => { /* ... */ }); const result = await workflow.execute(initialContext); ``` ## Context System Each workflow carries a `WorkflowContext` — a key-value data store that flows through all steps, enabling state sharing between nodes. ## Result Structure ```typescript interface WorkflowResult { success: boolean; error?: string; durationMs: number; stepsCompleted: number; stepsTotal: number; } ``` ## Built-in Workflows Cortex ships with a `health-check` workflow: - Step 1: Check disk space (`df`) - Step 2: Check memory (`free`) - Step 3: Aggregate and report ## Approval Gates Human-in-the-loop approval pauses workflow execution. Approvals are resumable: - CLI: `cortex workflow approve ` - API: Programmatic approval via the REST endpoint See also: [Trigger System](/docs/architecture/triggers), [Agent Loop](/docs/architecture/agent-loop) URL: https://cortexprism.io/docs/architecture/workflow --- ## Design Docs ### Design Docs Overview # Design Docs This page indexes the design specification documents for the CortexPrism project. Full specifications are maintained in the [GitHub repository](https://github.com/CortexPrism/cortex/tree/main/docs/design). ## Specification Index | Document | Description | |----------|-------------| | [DESIGN.md](https://github.com/CortexPrism/cortex/blob/main/docs/design/DESIGN.md) | Overall design vision, principles, and competitive analysis | | [ARCHITECTURE.md](https://github.com/CortexPrism/cortex/blob/main/docs/ARCHITECTURE.md) | Comprehensive architecture documentation | | [Security Model](/docs/architecture/security-parallax) | Security architecture, threat model, and mitigation strategies | | [Memory System](/docs/architecture/memory-system) | Memory tier specifications and implementation details | | [Plugin System](/docs/architecture/plugin-system) | Plugin architecture, lifecycle, and API specifications | | [Model Router](/docs/architecture/model-router) | Model router and request routing specifications | | [Daemon Supervisor](/docs/architecture/daemon-supervisor) | Background process management design | | [Agent Loop](/docs/architecture/agent-loop) | Core reasoning and tool execution loop | | [Databases](/docs/architecture/databases) | SQLite database schemas and migration strategy | ## Related Resources - [Architecture Overview](/docs/architecture) — High-level system architecture - [Developer Guide](/docs/developer-guide) — Plugin and agent development framework - [Knowledge Base](/docs/knowledge-base) — FAQ, troubleshooting, and best practices - [CLI Reference](/docs/cli) — Complete command-line reference For the complete set of 40+ detailed design specifications, see the [GitHub repository](https://github.com/CortexPrism/cortex/tree/main/docs/design). URL: https://cortexprism.io/docs/design-docs --- ## Developer Guide ### Agent Development # Agent Development This guide covers creating custom agent configurations, defining agent personas (souls), and building specialized agents for specific use cases. ## Agent Configuration Agents are defined using JSON configuration files that specify the model, behavior, tools, and personality. ### Basic Agent Config ```json { "name": "code-reviewer", "version": "1.0.0", "provider": "anthropic", "model": "claude-sonnet-4-20250514", "temperature": 0.3, "systemPrompt": "You are a senior code reviewer. Analyze code for bugs, security issues, and style violations. Suggest improvements.", "tools": ["read_file", "search_code", "git_diff"], "maxTurns": 50, "streamOutput": true } ``` ### Using soul (Persona) Configuration The `soul` field defines the agent's personality, behavior patterns, and constraints: ```json { "name": "research-assistant", "version": "1.0.0", "provider": "openai", "model": "gpt-4o", "temperature": 0.7, "soul": { "persona": "A thoughtful research assistant with expertise in academic literature review. You cite sources carefully and acknowledge uncertainty.", "constraints": [ "Always cite sources when making factual claims", "Distinguish between established facts and speculation", "Suggest further reading when appropriate" ], "voice": "professional", "memory": { "tiers": ["episodic", "semantic"], "retrieval": { "limit": 10, "minScore": 0.5 } } }, "tools": ["web_search", "read_file", "memory_search"] } ``` ## Using Agents Locally ```bash # Import from marketplace cortex agent import marketplace:research-assistant # Use in chat cortex chat --agent research-assistant # Or specify inline cortex chat --provider openai --model gpt-4o --system-prompt "You are a helpful coding assistant" ``` ## Publishing Agents Agents can be published to the marketplace for others to use: 1. Create your agent configuration 2. Test it locally: `cortex chat --agent my-agent` 3. Publish via the [Publish Agent](/marketplace/publish/agent) page ## Agent Tools Agents can use built-in tools and plugin-provided tools: ### Built-in Tools | Tool | Description | |------|-------------| | `file_read` | Read files from the filesystem (with enhanced multi-modal support) | | `file_write` | Write files to the filesystem | | `file_edit` | Apply precise string replacements in files | | `file_delete` | Delete files | | `file_rename` | Rename or move files | | `file_copy` | Copy files | | `file_glob` | Find files by glob patterns | | `file_search` | Search file contents with regex | | `file_tree` | Display directory tree | | `file_diff` | Compute file diffs | | `file_undo` | Undo file changes | | `shell` | Execute shell commands | | `code_exec` | Run code in sandboxed environments (Docker/gVisor) | | `web_search` | Search the web (DuckDuckGo, Brave, Tavily, SerpAPI) | | `web_fetch` | Fetch and parse content from URLs | | `memory_search` | Search the memory system | | `memory_store` | Store information in memory | | `sub_agent` | Spawn sub-agent processes for independent tasks | | `load_skill` | Load skill modules into agent context | | `skill_read` | Read bundled skill definitions | | `git` | Full git porcelain (status, log, diff, commit, push, clone, etc.) | | `github` | GitHub integration (PRs, issues, repositories) | | `listen` | Voice input via microphone | | `speak` | Text-to-speech output | ### Plugin Tools Any plugin capability is automatically available as a tool to agents. Install a plugin and reference its capabilities: ```json { "name": "data-analyst", "version": "1.0.0", "tools": ["code_exec", "plugin:csv-analyzer/analyze", "plugin:chart-generator/generate"] } ``` ## Agent Best Practices ### System Prompt Design ```markdown You are a [role] with expertise in [domain]. ## Behavioral Guidelines - [Guideline 1] - [Guideline 2] ## Constraints - [Constraint 1] - [Constraint 2] ## Output Format - [Format preferences] ## Tools Available - [Tool 1]: [Brief description] - [Tool 2]: [Brief description] ``` ### Temperature Settings | Use Case | Temperature | |----------|-------------| | Code generation | 0.2 - 0.4 | | Analysis/review | 0.3 - 0.5 | | Creative writing | 0.7 - 0.9 | | Research | 0.5 - 0.7 | | Data extraction | 0.1 - 0.3 | ### Memory Configuration ```json { "soul": { "memory": { "tiers": ["episodic", "semantic"], "retrieval": { "limit": 5, "minScore": 0.3, "recencyWeight": 0.4, "relevanceWeight": 0.6 } } } } ``` ## Example: Security Auditor Agent ```json { "name": "security-auditor", "version": "1.0.0", "provider": "anthropic", "model": "claude-sonnet-4-20250514", "temperature": 0.2, "soul": { "persona": "Expert security auditor with OWASP, CWE, and NIST knowledge. Methodical and thorough.", "constraints": [ "Always prioritize critical vulnerabilities", "Provide remediation steps for each finding", "Distinguish between theoretical and practical risks", "Never execute potentially destructive commands" ] }, "tools": ["read_file", "shell", "web_search", "plugin:dependency-scanner/scan"], "systemPrompt": "You perform security audits on codebases. For each finding, provide: severity, description, affected lines, and remediation." } ``` ## Example: Personal Assistant Agent ```json { "name": "personal-assistant", "version": "1.0.0", "provider": "openai", "model": "gpt-4o", "temperature": 0.7, "soul": { "persona": "Helpful, efficient personal assistant. Proactive and organized.", "voice": "friendly", "memory": { "tiers": ["episodic", "semantic", "reflection"], "retrieval": { "limit": 15 } } }, "tools": ["web_search", "memory_search", "memory_store", "code_exec", "read_file", "write_file"] } ``` ## Managing Agents via CLI ```bash cortex agent list # List configured agents cortex agent import # Import an agent from marketplace or file cortex agent export # Export agent to JSON cortex agent remove # Remove an agent cortex chat --agent # Chat with a specific agent cortex chat --list-agents # List available agents ``` URL: https://cortexprism.io/docs/developer-guide/agent-development --- ### Best Practices # Plugin Development Best Practices Guidelines and recommendations for building high-quality CortexPrism plugins. ## General Principles ### 1. Single Responsibility Each plugin should do one thing well. If you find yourself adding unrelated capabilities, split them into separate plugins. ```typescript // Good: focused plugin export default definePlugin({ name: "csv-parser", capabilities: { parseCSV, validateCSV, transformCSV }, }); // Bad: mixed concerns export default definePlugin({ name: "data-utils", capabilities: { parseCSV, sendEmail, resizeImage, queryDatabase }, }); ``` ### 2. Fail Gracefully Always handle errors and provide meaningful messages: ```typescript // Good async function fetchData(url: string, ctx: CapabilityContext) { if (!url.startsWith("https://")) { throw new PluginError("Only HTTPS URLs are supported"); } try { return await ctx.sandbox.fetch(url); } catch (err) { throw new PluginError(`Failed to fetch ${url}: ${err.message}`); } } ``` ### 3. Validate Inputs Use Zod schemas or explicit validation for all capability inputs: ```typescript const Input = z.object({ email: z.string().email(), template: z.string().min(1).max(10000), variables: z.record(z.string()).optional(), }); ``` ### 4. Respect Timeouts Capabilities have a default timeout of 30 seconds. Support cancellation: ```typescript async function processLargeFile(path: string, ctx: CapabilityContext) { const stream = await ctx.sandbox.readFileStream(path); for await (const chunk of stream) { if (ctx.abortSignal.aborted) { throw new TimeoutError("Processing cancelled"); } // process chunk } } ``` ### 5. Declare Minimal Permissions Only request the permissions you actually use: ```json { "permissions": { "network": ["fetch:https://api.example.com"], "filesystem": ["read:/tmp/data"] } } ``` ## ESM-Specific ### Use TypeScript TypeScript provides better IDE support and catches errors at build time: ```typescript interface SearchResult { title: string; url: string; snippet: string; } export default definePlugin({ name: "web-search", capabilities: { async search(query: string): Promise { // Type-safe implementation }, }, }); ``` ### Bundle for Distribution Bundle your plugin into a single file for reliable distribution: ```bash deno bundle mod.ts dist/plugin.js ``` Or for npm-published plugins: ```bash npx tsc && npx esbuild dist/index.js --bundle --format=esm --outfile=dist/bundle.js ``` ### Avoid Global State Each capability call may run in a fresh context. Use factory functions for stateful plugins: ```typescript export default async function createPlugin() { const connection = await createConnectionPool(); return { name: "db-connector", capabilities: { async query(sql: string) { return connection.execute(sql); }, }, }; } ``` ## MCP-Specific ### Handle Process Lifecycle MCP servers should handle graceful shutdown: ```typescript process.on("SIGTERM", async () => { await cleanup(); process.exit(0); }); process.on("SIGINT", async () => { await cleanup(); process.exit(0); }); ``` ### Minimize Startup Time Keep MCP server initialization fast. Defer expensive setup to the first tool call: ```typescript let client: DatabaseClient | null = null; server.setRequestHandler(CallToolRequestSchema, async (request) => { if (!client) { client = await createClient(); // Deferred initialization } // handle tool call }); ``` ### Stream Large Results For large outputs, use streaming responses: ```typescript server.setRequestHandler(CallToolRequestSchema, async (request) => { const stream = await getLargeResultStream(); return { content: [{ type: "text", text: stream.readAll() }], }; }); ``` ## WASM-Specific ### Optimize for Size ```toml [profile.release] opt-level = "s" # Optimize for size lto = true # Link-time optimization codegen-units = 1 # Better optimization strip = true # Remove debug symbols ``` ### Use Simple Types WASM ABI works best with primitive types. Use JSON for complex data: ```rust // Good: use JSON for structured data #[derive(Deserialize)] struct Input { values: Vec, threshold: f64, } // Avoid: complex ABI types fn process(values: *const f64, count: u32, threshold: f64) -> u32 { } ``` ### Test with wasmtime Always test your WASM plugin outside of CortexPrism first: ```bash wasmtime run --dir=. plugin.wasm ``` ## Testing Guidelines ### Unit Tests ```typescript import { testPlugin } from "@cortexprism/plugin-sdk/testing"; const harness = await testPlugin(myPlugin); Deno.test("my capability works", async () => { const result = await harness.call("myCap", { input: "test" }); assertEquals(result, { expected: "output" }); }); Deno.test("my capability rejects invalid input", async () => { await assertRejects( () => harness.call("myCap", { input: "" }), PluginError, ); }); ``` ### Integration Tests Test your plugin in a real CortexPrism session: ```bash cortex plugins install ./my-plugin cortex chat --agent my-agent <<< "Use my-plugin to do something" ``` ## Documentation Every plugin should include: 1. **README.md**: Usage instructions, examples, configuration options 2. **manifest.json**: Complete metadata for marketplace display 3. **Inline comments**: For complex logic in capability implementations 4. **Example inputs**: In capability descriptions for LLM context ## What to Avoid - **Hardcoded secrets**: Use the vault or environment variables - **Synchronous blocking**: All capabilities must be async - **Side effects without cleanup**: Always clean up in `onDeactivate` - **Dependency on specific LLM providers**: Keep capabilities provider-agnostic - **Overly broad permissions**: Request minimum required access URL: https://cortexprism.io/docs/developer-guide/best-practices --- ### Esm Plugin # ESM Plugin Development ESM (ECMAScript Module) plugins are JavaScript/TypeScript modules that export capabilities as async functions. They are the easiest plugin type to develop and the most common in the CortexPrism ecosystem. ## Project Structure ``` my-plugin/ ├── mod.ts # Plugin entry point (default export) ├── capabilities/ # Optional: split capabilities into modules │ ├── search.ts │ └── format.ts ├── test/ # Tests ├── README.md └── manifest.json # Plugin manifest (auto-generated or manual) ``` ## Entry Point Conventions The plugin **must** have a default export that is either: 1. A **plugin definition object** (recommended): ```typescript export default { name: "my-plugin", version: "1.0.0", capabilities: { /* ... */ }, }; ``` 2. A **factory function** (for async initialization): ```typescript export default async function createPlugin() { const client = await connectToService(); return { name: "service-connector", version: "1.0.0", capabilities: { async query(input: string) { return client.query(input); }, }, }; } ``` ## Defining Capabilities Capabilities are async functions that the agent tool system can invoke. Each capability receives a context object with permissions and utilities. ```typescript import { definePlugin, type CapabilityContext } from "@cortexprism/plugin-sdk"; export default definePlugin({ name: "code-analyzer", version: "1.1.0", description: "Analyze source code for metrics and issues", capabilities: { async countLines( filePath: string, ctx: CapabilityContext ): Promise<{ total: number; code: number; comments: number }> { // ctx.sandbox.readFile is gated by the Parallax policy const content = await ctx.sandbox.readFile(filePath); const lines = content.split("\n"); return { total: lines.length, code: lines.filter((l) => l.trim() && !l.trim().startsWith("//")).length, comments: lines.filter((l) => l.trim().startsWith("//")).length, }; }, async detectLanguage(code: string): Promise { // Pure computation, no sandbox access needed if (code.includes("fn ") || code.includes("let mut")) return "rust"; if (code.includes("def ") || code.includes("import ")) return "python"; if (code.includes("function ") || code.includes("=>")) return "javascript"; return "unknown"; }, }, }); ``` ## CapabilityContext Each capability receives a context object that provides: | Property | Description | |----------|-------------| | `ctx.sandbox` | Sandboxed file system and network access | | `ctx.log` | Structured logger scoped to the plugin | | `ctx.memory` | Read access to the agent's episodic/semantic memory | | `ctx.config` | Plugin-specific configuration from the agent config | | `ctx.abortSignal` | Signal for timeout/cancellation | ## SDK Usage The `@cortexprism/plugin-sdk` package provides: ```typescript import { definePlugin, // Type-safe plugin definition helper CapabilityContext, // Type for the context argument z, // Zod validation (capability input schemas) HttpError, // Error class for HTTP-like errors PermissionError, // Error for policy denial } from "@cortexprism/plugin-sdk"; ``` Install with: ```bash npm install @cortexprism/plugin-sdk # or via JSR deno add @cortexprism/plugin-sdk ``` ## Input Validation Use Zod schemas for capability input validation: ```typescript import { definePlugin, z } from "@cortexprism/plugin-sdk"; const SearchInput = z.object({ query: z.string().min(1).max(500), limit: z.number().int().min(1).max(100).default(10), source: z.enum(["web", "news", "academic"]).default("web"), }); export default definePlugin({ name: "advanced-search", version: "1.0.0", capabilities: { async search(raw: unknown) { const input = SearchInput.parse(raw); const results = await searchEngine(input.query, input.source, input.limit); return results; }, }, }); ``` ## Error Handling Always throw typed errors so the agent can handle them gracefully: ```typescript import { PluginError, PermissionError } from "@cortexprism/plugin-sdk"; export default definePlugin({ name: "file-ops", version: "1.0.0", capabilities: { async readFile(path: string, ctx: CapabilityContext) { if (!path.startsWith("/allowed/path/")) { throw new PermissionError(`Access denied: ${path}`); } try { return await ctx.sandbox.readFile(path); } catch (err) { throw new PluginError(`Failed to read file: ${err.message}`, err); } }, }, }); ``` ## Extension Points Beyond capabilities, ESM plugins can extend CortexPrism through several extension points. Export named exports from your entry point module. ### Tools Export a `tools` array to register tool definitions with the agent loop: ```typescript import type { Tool, PluginContext } from "cortex/plugins"; const weatherTool: Tool = { definition: { name: "get_weather", description: "Get current weather for a city", params: [ { name: "city", type: "string", description: "City name", required: true }, ], capabilities: ["network:fetch"], }, execute: async (args, ctx) => { const res = await fetch(`https://api.weather.example/${args.city}`); const data = await res.text(); return { toolName: "get_weather", success: true, output: data, durationMs: 0 }; }, }; export const tools = [weatherTool]; ``` ### CLI Commands Declare commands in the manifest and export a handler: ```json { "cliCommands": [ { "name": "my-command", "description": "My custom CLI command", "options": [ { "name": "verbose", "type": "boolean", "description": "Verbose output", "flag": "-v" } ] } ] } ``` ```typescript export async function myCommand(args: Record) { console.log(`Running with args:`, args); } ``` ### LLM Providers Export a `providers` map to add new AI provider integrations: ```typescript export const providers = { "my-provider": (config: Record) => ({ name: "my-provider", defaultModel: "my-model", async complete(opts) { /* ... */ }, async *stream(opts) { /* ... */ }, }), }; ``` ### UI Panels Define panels in the manifest. Each panel has an HTML file served by the CortexPrism Web UI: ```json { "ui": { "panels": [ { "id": "weather", "title": "Weather", "icon": "cloud", "htmlPath": "./ui/panel.html" } ], "settings": [ { "section": "API", "fields": [ { "key": "apiKey", "label": "Weather API Key", "type": "secret", "defaultValue": "" } ] } ] } } ``` ### Lifecycle Hooks Your entry point module can export lifecycle hooks that the plugin manager calls automatically: ```typescript import type { PluginContext } from "cortex/plugins"; export const onLoad = async (ctx: PluginContext) => { // Called when the plugin transitions from INSTALLED to ACTIVE // Use for initialization: connect to services, allocate resources ctx.logger.info("Plugin loaded"); await ctx.state.set("startedAt", new Date().toISOString()); }; export const onUnload = async (ctx: PluginContext) => { // Called when the plugin transitions from ACTIVE to UNLOADING // Use for cleanup: close connections, release resources ctx.logger.info("Plugin unloaded"); }; ``` ### PluginContext Lifecycle hooks receive a `PluginContext` with these properties: | Property | Type | Description | |----------|------|-------------| | `ctx.logger` | `Logger` | Structured logger prefixed with plugin name | | `ctx.config` | `ConfigStore` | Plugin configuration from `~/.cortex/config.json` | | `ctx.state` | `StateStore` | In-memory key-value store persisted to `state.json` | | `ctx.pluginDir` | `string` | Plugin installation directory | | `ctx.dataDir` | `string` | Plugin-private data directory (`~/.cortex/data/plugins//data/`) | Use `ctx.config` and `ctx.state` instead of direct file access for portability. ### Plugin Store Layout When installed, plugin data is stored under `~/.cortex/data/plugins/`: ``` ~/.cortex/data/plugins/ ├── / │ ├── esm/ # downloaded ESM source │ ├── wasm/ # downloaded WASM binaries │ ├── data/ # plugin-private data │ └── state.json # persisted plugin state (ctx.state) ``` ## Testing Test plugins with the CortexPrism test harness: ```typescript import { testPlugin } from "@cortexprism/plugin-sdk/testing"; import myPlugin from "./mod.ts"; const harness = await testPlugin(myPlugin); // Test a capability const result = await harness.call("countLines", "test/fixture.ts"); console.assert(result.total > 0); // Test with custom context const withConfig = await testPlugin(myPlugin, { config: { maxLines: 100 }, }); ``` ## Bundling for Distribution The plugin manager can load plugins from: 1. **Local directory**: `cortex plugins install ./path/to/plugin` 2. **Marketplace**: `cortex plugins install marketplace:cortexprism.io/plugins/my-plugin` 3. **URL**: `cortex plugins install https://example.com/plugin.js` For distribution, bundle to a single ESM file: ```bash deno bundle mod.ts dist/plugin.js ``` ## Permissions Declaration Declare the permissions your plugin needs in the manifest: ```json { "name": "network-scanner", "version": "1.0.0", "permissions": { "network": ["fetch:https://api.example.com"], "filesystem": ["read:/tmp"], "env": ["MY_API_KEY"] } } ``` The Parallax policy engine enforces these permissions at runtime. URL: https://cortexprism.io/docs/developer-guide/esm-plugin --- ### Getting Started # Getting Started with Plugins ## CLI Commands ### Install a Plugin ```bash cortex plugins install ``` Sources: - `marketplace:/plugins/` — install from the marketplace - `https://...` — install from a URL pointing to a manifest.json - `./path/to/manifest.json` — install from a local file ### List Plugins ```bash cortex plugins list ``` Shows all installed plugins with their name, version, type, status, and description. ### Manage Plugins ```bash cortex plugins enable cortex plugins disable cortex plugins remove ``` - **enable** — loads the plugin module, registers its tools/hooks/providers, and sets status to `active` - **disable** — calls unload hooks, deregisters tools, sets status to `unloaded` - **remove** — calls uninstall hooks, removes database entries and plugin data ### Update Plugins ```bash cortex plugins update cortex plugins update --all ``` ### Verify Integrity ```bash cortex plugins verify ``` Checks the SHA-256 hash of the plugin entry point against the manifest. ### Inspect Permissions ```bash cortex plugins permissions ``` Shows declared, effective, and overridden permissions for a plugin. ## Web UI Navigate to the **Plugins** tab in the Web UI (started via `cortex serve`) to see installed plugins, their status, and available configuration options. Use the **Marketplace** tab to browse and install new plugins. Plugin-provided panels appear as additional tabs in the Web UI. ## Configuration Plugin settings are stored in `~/.cortex/config.json` under the `plugins` key: ```json { "plugins": { "my-plugin": { "apiEndpoint": "https://api.example.com", "maxRetries": 3 } } } ``` Configure via: 1. **Web UI** — Settings tab shows all plugin settings with form fields defined in the manifest 2. **CLI** — edit `~/.cortex/config.json` directly 3. **API** — `GET/PUT /api/plugins//config` ## Settings Schema Each plugin declares its settings in the manifest under `ui.settings`. CortexPrism renders these as form fields in the Web UI. ```json { "ui": { "settings": [ { "section": "API", "fields": [ { "key": "apiKey", "label": "API Key", "type": "secret", "defaultValue": "" }, { "key": "endpoint", "label": "Endpoint URL", "type": "text", "defaultValue": "https://api.example.com" } ] } ] } } ``` ## Plugin Store When installed, plugins and their data are stored under `~/.cortex/data/plugins/`: ``` ~/.cortex/data/plugins/ ├── / │ ├── esm/ # downloaded ESM source │ ├── wasm/ # downloaded WASM binaries │ ├── data/ # plugin-private data │ └── state.json # persisted plugin state ``` ## Lifecycle States Each plugin moves through these states: ``` DISCOVERED → INSTALLED → LOADING → ACTIVE ↓ UNLOADING → REMOVED ``` - **INSTALLED** — manifest stored in database, files staged on disk - **ACTIVE** — module loaded, tools registered, UI panels rendered in Web UI - **REMOVED** — database row deleted, files cleaned from disk URL: https://cortexprism.io/docs/developer-guide/getting-started --- ### Developer Guide Overview # Developer Guide This guide covers everything you need to build, publish, and maintain plugins and agents for the CortexPrism ecosystem. Whether you are extending the system with custom capabilities or building agents for specific use cases, you are in the right place. ## Sections | Guide | Description | |-------|-------------| | [Getting Started](/docs/developer-guide/getting-started) | Plugin CLI commands, Web UI, and configuration | | [Plugin Types](/docs/developer-guide/plugin-types) | Overview of ESM, MCP, and WASM plugin architectures | | [ESM Plugins](/docs/developer-guide/esm-plugin) | Building JavaScript/TypeScript ESM plugins | | [MCP Plugins](/docs/developer-guide/mcp-plugin) | Building Model Context Protocol server plugins | | [WASM Plugins](/docs/developer-guide/wasm-plugin) | Building WebAssembly plugins | | [Plugin API Reference](/docs/developer-guide/plugin-api) | Complete plugin capability and lifecycle API | | [Agent Development](/docs/developer-guide/agent-development) | Creating and customizing agent configurations | | [Publishing](/docs/developer-guide/publishing) | Publishing plugins and agents to the marketplace | | [Submission Standards](/docs/developer-guide/submission-standards) | Repository structure, versioning, AI disclosure, and submission procedure | | [Best Practices](/docs/developer-guide/best-practices) | Guidelines and recommendations for plugin development | ## Quick Start The fastest way to start developing a plugin: ```bash # Create a new ESM plugin mkdir my-plugin cd my-plugin npm init -y npm install @cortexprism/plugin-sdk ``` ```typescript import { definePlugin } from "@cortexprism/plugin-sdk"; export default definePlugin({ name: "my-plugin", version: "1.0.0", capabilities: { async greet(name: string): Promise { return `Hello, ${name}!`; }, }, }); ``` Install your plugin locally to test: ```bash cortex plugins install ./my-plugin ``` ## System Requirements - **Runtime**: Deno v2.0+ or Node.js v20+ (for ESM plugins) - **CortexPrism**: v0.35.3+ - **Rust toolchain** (only for WASM plugins) - **Docker** (optional, for MCP plugin testing) ## Key Concepts - **Plugin**: A self-contained module that adds capabilities to the agent tool system - **Capability**: A single function exposed by a plugin that the agent can invoke - **Manifest**: Metadata describing the plugin (name, version, capabilities, permissions) - **Sandbox**: Isolated execution environment for plugins with resource limits - **Marketplace**: Central registry for discovering and distributing plugins ## Architecture Overview ``` Agent Loop → Tool Registry → Plugin Manager → Plugin Sandbox (isolated) → ESM Runtime / MCP Process / WASM Runtime ``` Each plugin type runs in its own sandboxed environment with resource limits enforced by the Parallax security layer. URL: https://cortexprism.io/docs/developer-guide --- ### Mcp Plugin # MCP Plugin Development MCP (Model Context Protocol) plugins wrap tools conforming to the [Model Context Protocol](https://modelcontextprotocol.io) standard. They run as separate processes and communicate via JSON-RPC, making them suitable for wrapping existing services or implementing language-agnostic tools. ## Overview An MCP plugin is a plugin entry in the CortexPrism registry whose type is `mcp` and whose entry point launches an MCP-compatible server process. The CortexPrism plugin manager manages the child process lifecycle and translates capability calls into MCP `tools/call` requests. ## How It Works ``` Agent → Plugin Manager → MCP Client (JSON-RPC over stdio/HTTP) ↓ MCP Server Process ↓ Tool Implementation ``` The MCP server advertises available tools via `tools/list` and handles invocations via `tools/call`. The CortexPrism MCP client is built on the [official MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk). ## Plugin Manifest ```json { "name": "git-server", "version": "1.0.0", "type": "mcp", "entryPoint": "node dist/server.js", "description": "Git repository management tools", "mcp": { "transport": "stdio", "args": ["--repo-dir", "/workspace"], "env": { "GIT_ALLOWED_COMMANDS": "status,log,diff" }, "timeout": 30000 } } ``` ## Creating an MCP Server You can create an MCP server in any language. Here is a TypeScript example: ```typescript import { Server } from "@modelcontextprotocol/sdk/server/index.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js"; const server = new Server( { name: "git-server", version: "1.0.0" }, { capabilities: { tools: {} } } ); server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [ { name: "git_status", description: "Show working tree status", inputSchema: { type: "object", properties: { path: { type: "string", description: "Repository path" }, }, }, }, { name: "git_log", description: "Show commit log", inputSchema: { type: "object", properties: { path: { type: "string" }, maxCount: { type: "number", default: 10 }, }, }, }, ], })); server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: args } = request.params; switch (name) { case "git_status": { const output = await execGit(["status"], args.path); return { content: [{ type: "text", text: output }] }; } case "git_log": { const output = await execGit(["log", `--max-count=${args.maxCount || 10}`], args.path); return { content: [{ type: "text", text: output }] }; } default: throw new Error(`Unknown tool: ${name}`); } }); const transport = new StdioServerTransport(); await server.connect(transport); ``` ## Python MCP Server Example ```python from mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import TextContent, Tool app = Server("weather-server") @app.list_tools() async def list_tools() -> list[Tool]: return [ Tool( name="get_weather", description="Get current weather for a city", inputSchema={ "type": "object", "properties": { "city": {"type": "string", "description": "City name"} }, "required": ["city"], }, ) ] @app.call_tool() async def call_tool(name: str, arguments: dict) -> list[TextContent]: if name == "get_weather": city = arguments["city"] result = await fetch_weather(city) return [TextContent(type="text", text=str(result))] raise ValueError(f"Unknown tool: {name}") if __name__ == "__main__": import anyio anyio.run(stdio_server, app) ``` ## Transports MCP supports two transport mechanisms: ### stdio (Default) The plugin manager spawns the MCP server as a subprocess and communicates via stdin/stdout. ```json { "mcp": { "transport": "stdio" } } ``` ### HTTP/SSE The MCP server runs as an HTTP server with Server-Sent Events. ```json { "mcp": { "transport": "http", "url": "http://localhost:8080/mcp" } } ``` ## Lifecycle Management | Event | Action | |-------|--------| | Plugin install | Entry point registered but not started | | First capability call | MCP server process spawned | | Subsequent calls | Messages sent to the running process | | Plugin disable | Process sent SIGTERM (graceful shutdown) | | Plugin uninstall | Process killed, resources cleaned up | | Plugin idle timeout | Process terminated after inactivity period | ## Error Handling MCP tools should return structured error responses: ```json { "isError": true, "content": [ { "type": "text", "text": "Repository not found at path: /invalid/path" } ] } ``` ## Security Considerations - MCP processes run with the permissions declared in the manifest - Network access is controlled by the Parallax policy engine - Long-running processes are monitored for resource usage - Output is capped to prevent flooding (default: 64KB) - Timeout is enforced per tool call (default: 30s) ## Debugging Enable verbose logging to inspect MCP communication: ```bash cortex --verbose plugin list ``` The raw JSON-RPC messages are logged to the Cortex Lens audit trail. URL: https://cortexprism.io/docs/developer-guide/mcp-plugin --- ### Plugin Api # Plugin API Reference Complete reference for the CortexPrism plugin system APIs, covering the lifecycle hooks, capability interface, permission model, and runtime APIs. ## Plugin Lifecycle Hooks Plugins can hook into lifecycle events to perform initialization and cleanup: ```typescript export default definePlugin({ name: "lifecycle-demo", version: "1.0.0", onInstall(ctx: LifecycleContext): void | Promise { // Called when the plugin is first installed // Use for one-time setup: create directories, initialize state }, onActivate(ctx: LifecycleContext): void | Promise { // Called when the plugin is activated (enabled) // Use for per-session setup: connect to services, allocate resources }, onDeactivate(ctx: LifecycleContext): void | Promise { // Called when the plugin is deactivated (disabled) // Use for cleanup: close connections, release resources }, onUninstall(ctx: LifecycleContext): void | Promise { // Called right before the plugin is removed // Use for final cleanup: remove data, revoke permissions }, onConfigChange(ctx: LifecycleContext, prev: Record): void | Promise { // Called when plugin configuration changes at runtime // Use to hot-reload settings without restart }, }); ``` ### LifecycleContext | Property | Type | Description | |----------|------|-------------| | `pluginDir` | `string` | Plugin installation directory path | | `dataDir` | `string` | Plugin-scoped data directory for persistent storage | | `config` | `Record` | Current plugin configuration | | `log` | `Logger` | Structured logger | | `db` | `KVStore` | Simple key-value store backed by plugins.db | ## Capability Definition ### ESM Capabilities ```typescript type CapabilityFunction = ( input: TInput, context: CapabilityContext ) => TOutput | Promise; ``` ### CapabilityContext | Property | Type | Description | |----------|------|-------------| | `sandbox` | `SandboxAPI` | Restricted file/network access | | `log` | `Logger` | Structured logger | | `memory` | `MemoryAPI` | Read-only memory access | | `config` | `Record` | Plugin config scoped to this call | | `abortSignal` | `AbortSignal` | Signals timeout/cancellation | | `requestId` | `string` | Unique ID for this capability invocation | ### SandboxAPI ```typescript interface SandboxAPI { readFile(path: string): Promise; writeFile(path: string, content: string): Promise; readDir(path: string): Promise; fetch(url: string, options?: RequestInit): Promise; exec(command: string, args?: string[]): Promise; tempDir(): Promise; } ``` Each `SandboxAPI` method is gated by the Parallax policy engine. Access is denied unless the plugin manifest declares the required permission. ### MemoryAPI ```typescript interface MemoryAPI { search(query: string, options?: { limit?: number; tier?: MemoryTier }): Promise; get(id: string): Promise; } type MemoryTier = "ephemeral" | "working" | "episodic" | "semantic" | "reflection"; interface MemoryEntry { id: string; content: string; score: number; tier: MemoryTier; timestamp: number; } ``` ## Plugin Manifest Schema Full schema for `manifest.json`: ### Required Fields | Field | Type | Description | |-------|------|-------------| | `name` | `string` | Unique plugin identifier (kebab-case). Primary key in the plugin database. | | `version` | `string` | Semantic version (e.g. `1.0.0`). | | `description` | `string` | Short description shown in marketplace and plugin list. | | `kind` | `"esm" | "mcp" | "wasm"` | Plugin runtime kind. | | `entryPoint` | `string` | Path to module, URL, or WASM binary (relative to manifest). | | `runtime` | `"deno" | "wasm"` | Execution target. `deno` for ESM/MCP, `wasm` for WASM. | | `capabilities` | `string[]` | Declared extension points and permissions. | ### Optional Fields | Field | Type | Description | |-------|------|-------------| | `author` | `string` | Author name or organization. | | `homepage` | `string` (url) | Plugin homepage URL. | | `license` | `string` | SPDX license identifier (e.g. `MIT`). | | `repository` | `string` (url) | Source repository URL. | | `hash` | `string` | SHA-256 hash of entry point for integrity verification. | | `signature` | `string` | Optional GPG/JWT signature for trust verification. | | `icon` | `string` | Path to icon file. | | `dependencies` | `Record` | Other plugins required, keyed by name with semver constraints. | | `peerDependencies` | `Record` | Host CortexPrism version constraint. | | `tools` | `ToolDeclaration[]` | Tool definitions (names, params). ESM plugins provide the implementation. | | `cliCommands` | `CliCommandDeclaration[]` | CLI subcommand specifications. | | `ui` | `UiContribution` | UI panels, widgets, and settings forms. | | `config` | `ConfigContribution` | Config schema extensions and defaults. | | `events` | `string[]` | Event types the plugin subscribes to. | | `permissions` | `object` | Granular sandbox permissions. | | `mcp` | `object` | MCP-specific transport and timeout settings. | | `wasm` | `object` | WASM-specific memory and allocator settings. | ### Capabilities Capabilities serve dual purpose: they declare what extension points the plugin uses AND what permissions it needs. **Extension Point Capabilities:** | Value | Description | |-------|-------------| | `tools` | Plugin provides `Tool[]` | | `cli:commands` | Plugin provides CLI subcommands | | `ui:panel` | Plugin provides a Web UI panel/tab | | `ui:widget` | Plugin provides a dashboard widget | | `config:schema` | Plugin extends config schema | | `config:provider` | Plugin provides an LLM provider | | `memory:store` | Plugin provides a custom memory backend | | `memory:embedder` | Plugin provides an embedding provider | | `events:listener` | Plugin subscribes to event bus | | `middleware:pre` | Plugin provides pre-execution middleware | | `middleware:post` | Plugin provides post-execution middleware | **Permission Capabilities:** | Value | Description | |-------|-------------| | `fs:read` | Read filesystem access | | `fs:write` | Write filesystem access | | `fs:list` | Directory listing | | `fs:edit` | File editing | | `fs:delete` | File deletion | | `fs:search` | File searching | | `shell:run` | Shell command execution | | `network:fetch` | Outbound HTTP requests | | `net:outbound` | General outbound network access | | `net:inbound` | Inbound network (listening) | | `db:read` | Database read access | | `db:write` | Database write access | ### ToolDeclaration ```json { "tools": [ { "name": "my_tool", "description": "What this tool does", "params": [ { "name": "input", "type": "string", "description": "Input value", "required": true } ] } ] } ``` ### CliCommandDeclaration ```json { "cliCommands": [ { "name": "my-cmd", "description": "My custom command", "args": [ { "name": "target", "type": "string", "description": "Target to operate on", "required": true } ], "options": [ { "name": "verbose", "type": "boolean", "description": "Verbose output", "flag": "-v" } ] } ] } ``` ### UiContribution ```json { "ui": { "panels": [ { "id": "my-panel", "title": "My Panel", "icon": "star", "htmlPath": "./ui/panel.html" } ], "widgets": [ { "id": "my-widget", "title": "My Widget", "type": "html", "config": {} } ], "settings": [ { "section": "General", "fields": [ { "key": "apiKey", "label": "API Key", "type": "secret", "defaultValue": "" }, { "key": "maxRetries", "label": "Max Retries", "type": "number", "defaultValue": 3 }, { "key": "enabled", "label": "Enabled", "type": "boolean", "defaultValue": true }, { "key": "mode", "label": "Mode", "type": "select", "defaultValue": "auto", "options": [ { "label": "Automatic", "value": "auto" }, { "label": "Manual", "value": "manual" } ] } ] } ] } } ``` **UiSettingField Types:** | Type | Description | |------|-------------| | `text` | Single-line text input | | `number` | Numeric input | | `boolean` | Checkbox toggle | | `select` | Dropdown with `options` array | | `secret` | Password field (masked input) | ### ConfigContribution ```json { "config": { "providers": [ { "kind": "my-provider", "label": "My Provider", "defaultModel": "my-model-v1" } ], "settings": { "defaultEndpoint": "https://api.example.com" } } } ``` ### Trust Levels | Level | Sandbox | Permissions | |-------|---------|-------------| | `untrusted` | Worker sandbox | Limited to declared permissions | | `signed` | Worker sandbox | Broader permissions based on signature | | `trusted` | In-process | Full declared permissions | Trust level is set at install time and can be changed via `cortex plugins permissions `. ### Full Manifest Example ```json { "name": "my-plugin", "version": "1.0.0", "description": "An example plugin with tools, UI panel, and settings", "kind": "esm", "entryPoint": "./mod.ts", "runtime": "deno", "capabilities": ["tools", "ui:panel", "network:fetch"], "author": "Your Name", "license": "MIT", "repository": "https://github.com/you/my-plugin", "tools": [ { "name": "get_weather", "description": "Get current weather for a city", "params": [ { "name": "city", "type": "string", "description": "City name", "required": true } ] } ], "cliCommands": [ { "name": "my-command", "description": "My custom CLI command", "options": [ { "name": "verbose", "type": "boolean", "flag": "-v" } ] } ], "ui": { "panels": [ { "id": "weather", "title": "Weather", "icon": "cloud", "htmlPath": "./ui/panel.html" } ], "settings": [ { "section": "API", "fields": [ { "key": "apiKey", "label": "API Key", "type": "secret", "defaultValue": "" } ] } ] } } ``` ## Runtime API (Available to ESM Plugins) ### Global Objects | Object | Description | |--------|-------------| | `CortexPrism` | Version info and build metadata | | `fetch` | Global fetch (limited by policy) | | `console` | Scoped console (prefixed with plugin name) | ### Importable SDK ```typescript import { definePlugin, // Type-safe plugin definition z, // Zod validation HttpError, // 400-level errors PermissionError, // Policy denial errors PluginError, // Generic plugin errors TimeoutError, // Capability timeout errors } from "@cortexprism/plugin-sdk"; ``` ## Error Types | Error Class | HTTP Status | When to Use | |-------------|-------------|-------------| | `PluginError` | 500 | Unexpected internal errors | | `HttpError` | 400-599 | Client errors, service unavailable | | `PermissionError` | 403 | Policy denial | | `TimeoutError` | 408 | Operation exceeded time limit | ## Registry DB Schema (plugins.db) The plugin registry is stored in `plugins.db` with this schema: ```sql CREATE TABLE plugins ( id TEXT PRIMARY KEY, name TEXT NOT NULL UNIQUE, version TEXT NOT NULL, type TEXT NOT NULL CHECK(type IN ('esm','mcp','wasm')), entry_point TEXT NOT NULL, manifest TEXT NOT NULL, -- Full manifest as JSON enabled INTEGER DEFAULT 1, installed_at TEXT NOT NULL, updated_at TEXT NOT NULL, download_count INTEGER DEFAULT 0 ); CREATE TABLE plugin_permissions ( id TEXT PRIMARY KEY, plugin_id TEXT NOT NULL REFERENCES plugins(id), permission TEXT NOT NULL, granted INTEGER DEFAULT 0 ); CREATE TABLE plugin_config ( plugin_id TEXT PRIMARY KEY REFERENCES plugins(id), config TEXT NOT NULL DEFAULT '{}' ); ``` ## CLI Commands ```bash cortex plugins install # Install from marketplace, URL, or local path cortex plugins list # List installed plugins with status cortex plugins enable # Activate a plugin cortex plugins disable # Deactivate without removing ``` URL: https://cortexprism.io/docs/developer-guide/plugin-api --- ### Plugin Types # Plugin Types CortexPrism supports three distinct plugin architectures, each suited for different use cases. All three follow the same lifecycle and security model but differ in runtime, isolation, and capability exposure. ## Comparison | Aspect | ESM | MCP | WASM | |--------|-----|-----|------| | **Runtime** | Deno/Node.js sandbox | Separate process (stdio/HTTP) | WebAssembly runtime | | **Language** | TypeScript, JavaScript | Any language (stdin/stdout JSON) | Rust, C, C++, Go, AssemblyScript | | **Performance** | Medium | Low (IPC overhead) | High | | **Isolation** | Process-level sandbox | Process-level | Sandboxed runtime | | **State** | In-memory, per-session | Persistent process | Stateless | | **Network** | Restricted by policy | Configurable | None by default | | **Best for** | General-purpose tools | Complex services, external APIs | CPU-intensive, cross-language | ## ESM Plugins ESM (ECMAScript Module) plugins are the most common and flexible type. They are written in TypeScript or JavaScript and run in a sandboxed Deno/Node.js subprocess with restricted permissions. **Use when:** - You want the fastest development cycle - Your plugin performs data processing, file operations, or API calls - You need to share code easily via npm/JSR **Example capability:** ```typescript export default definePlugin({ name: "data-processor", version: "1.0.0", capabilities: { async analyzeCSV(path: string): Promise { const content = await Deno.readTextFile(path); // process CSV data return { rows: content.split("\n").length, columns: inferColumns(content) }; }, }, }); ``` ## MCP Plugins MCP (Model Context Protocol) plugins implement the [Model Context Protocol](https://modelcontextprotocol.io) standard. They run as separate processes communicating via JSON-RPC over stdin/stdout or HTTP. **Use when:** - Your plugin wraps an existing MCP server - You need long-running stateful services - Your plugin requires specific runtime dependencies - You want language-agnostic implementation (Python, Go, Rust, etc.) **Example MCP tool definition:** ```json { "name": "git-mcp-server", "version": "1.0.0", "type": "mcp", "entryPoint": "npx @modelcontextprotocol/server-git", "capabilities": { "tools": ["git_status", "git_log", "git_diff", "git_commit"] } } ``` ## WASM Plugins WASM (WebAssembly) plugins compile to `.wasm` bytecode and run in a sandboxed WebAssembly runtime. They offer the highest performance and strongest security guarantees. **Use when:** - Performance is critical (data transformation, encoding, parsing) - You want to write in Rust, Go, C, or C++ - Your plugin handles sensitive data (stronger sandboxing) - The plugin is stateless and deterministic **Example Rust plugin:** ```rust #[no_mangle] pub extern "C" fn process_data(input_ptr: *const u8, input_len: usize) -> i32 { let input = unsafe { std::slice::from_raw_parts(input_ptr, input_len) }; let result = transform(input); // Write result to shared memory, return pointer result as i32 } ``` ## Choosing the Right Type | Scenario | Recommended Type | |----------|-----------------| | Quick Prototyping | ESM | | Data Processing | ESM or WASM | | External API Integration | MCP | | CPU-intensive Computation | WASM | | Existing CLI Tool Wrapper | MCP | | Language-agnostic Service | MCP | | Security-sensitive Crypto | WASM | | File System Operations | ESM | ## Type Mixing A single plugin entry in the registry can declare multiple capability entry points of different types. The plugin manager dispatches each capability to the appropriate runtime. ```json { "name": "hybrid-plugin", "capabilities": { "fastTransform": { "type": "wasm", "entry": "transform.wasm" }, "webSearch": { "type": "esm", "entry": "web-search.js" }, "gitOps": { "type": "mcp", "entry": "npx @mcp/git" } } } ``` URL: https://cortexprism.io/docs/developer-guide/plugin-types --- ### Publishing # Publishing to the Marketplace This guide covers how to publish your plugins and agents to the CortexPrism Marketplace for distribution to all users. ## Account Setup Before publishing, you need a marketplace account: 1. Navigate to the [Register](/register) page 2. Create an account with your email and username 3. Verify your email address ## Publishing a Plugin ### Step 1: Prepare Your Plugin Ensure your plugin has a complete manifest and is tested: ```bash # Test locally cortex plugins install ./my-plugin # Ensure tool capabilities work in a chat session cortex chat --agent my-agent ``` ### Step 2: Submit via Web UI 1. Go to the [Publish Plugin](/marketplace/publish/plugin) page 2. Fill in the required fields: - **Basic Info**: Name, version, description - **Plugin Details**: Type (ESM/MCP/WASM), entry point, capabilities - **Author & Links**: Author name, website, repository, license - **Media**: Icon, screenshots - **Tags**: Add relevant tags for discoverability 3. Submit for review ### Step 3: Submit via API (Automated) For CI/CD pipelines, use the API directly: ```bash # Authenticate TOKEN=$(curl -s -X POST https://cortexprism.io/api/auth/login \ -H 'Content-Type: application/json' \ -d '{"email":"user@example.com","password":"your-password"}' \ | jq -r '.token') # Submit plugin curl -X POST https://cortexprism.io/api/marketplace/plugins \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "name": "my-plugin", "version": "1.0.0", "description": "Does awesome things", "kind": "esm", "entryPoint": "mod.ts", "capabilities": "{\"transform\":{\"input\":\"any\",\"output\":\"any\"}}", "tags": ["text", "processing"], "repository": "https://github.com/user/my-plugin", "license": "MIT" }' ``` ### Step 4: Review Process After submission: 1. Status is set to **pending** 2. An admin reviews your submission 3. You receive notification of approval or rejection 4. If approved, your plugin is live on the marketplace Check submission status on your [Dashboard](/dashboard). ## Publishing an Agent Similar to plugins, but with agent-specific fields: 1. Go to the [Publish Agent](/marketplace/publish/agent) page 2. Provide: - **Basic Info**: Name, version, description - **Agent Config**: Provider, model, temperature, system prompt - **Tools**: List of tool capabilities the agent uses - **Soul**: Optional personality/soul configuration - **Tags**: For discoverability 3. Submit for review ## Plugin Requirements | Requirement | Details | |-------------|---------| | **Naming** | kebab-case, unique across marketplace | | **Version** | Valid semver (e.g., `1.0.0`, `2.3.1`) | | **Entry point** | Must be accessible and valid | | **Capabilities** | At least one capability defined | | **License** | SPDX identifier required (MIT, Apache-2.0, etc.) | | **README** | Recommended: usage instructions | | **Icon** | Recommended: 256x256 PNG or SVG | ## Version Management Update your plugin by submitting a new version: ```bash curl -X PUT https://cortexprism.io/api/marketplace/plugins/my-plugin \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "version": "1.1.0", "description": "Added new capabilities", "entryPoint": "mod.ts", "capabilities": "..." }' ``` Each published version is stored in the version history. Users can see the changelog and update their local installations. ## Marketplace API The marketplace exposes a full REST API for programmatic access: | Endpoint | Method | Description | |----------|--------|-------------| | `/api/marketplace/plugins` | GET | List plugins with search/filter/pagination | | `/api/marketplace/plugins` | POST | Submit a new plugin | | `/api/marketplace/plugins/:id` | GET | Get plugin details | | `/api/marketplace/plugins/:id` | PUT | Update plugin | | `/api/marketplace/plugins/:id/download` | GET | Download plugin manifest | | `/api/marketplace/plugins/:id/reviews` | GET | List reviews | | `/api/marketplace/plugins/:id/reviews` | POST | Submit a review | See the [OpenAPI docs](/openapi) for the complete specification. ## Best Practices for Publishing 1. **Write a clear description**: Explain what your plugin does and how to use it 2. **Add tags**: Use relevant tags for search discoverability 3. **Include a README**: Provide detailed usage instructions within the plugin 4. **Use screenshots**: Show the plugin in action 5. **Version carefully**: Follow semantic versioning 6. **Respond to reviews**: Engage with user feedback 7. **Keep dependencies minimal**: Faster install, fewer conflicts 8. **Test on multiple platforms**: Linux, macOS, Windows (WSL2) 9. **Add a license**: Clearly state usage terms 10. **Link to source**: If open source, link the repository ## CLI Publishing (Future) Plugin developers will also be able to publish directly from the CLI: ```bash cortex marketplace publish ./my-plugin ``` This command is in development and will be available in a future release. URL: https://cortexprism.io/docs/developer-guide/publishing --- ### Submission Standards # Submission Standards This guide covers the complete set of standards and requirements for publishing plugins on the CortexPrism Marketplace: repository structure, versioning, AI disclosure, and the official submission procedure. ## Repository Structure A well-structured repository makes your plugin easier to maintain, review, and adopt. Follow these conventions to pass review quickly and give users a consistent experience. ### Required Layout ``` my-plugin/ ├── manifest.json # Plugin manifest (required) ├── mod.ts # Entry point (ESM) or equivalent ├── README.md # Documentation (required for marketplace) ├── LICENSE # License file (required) ├── CHANGELOG.md # Version history (recommended) ├── test/ # Tests (recommended) │ ├── unit/ │ └── integration/ ├── screenshots/ # Marketplace screenshots (recommended) │ ├── screenshot-1.png │ └── screenshot-2.png ├── .github/ # GitHub-specific files │ ├── workflows/ │ │ └── publish.yml # CI/CD for automated publishing │ └── ISSUE_TEMPLATE/ # Issue templates (recommended) └── examples/ # Usage examples (recommended) └── basic-usage.md ``` ### Root Files | File | Required | Purpose | |------|----------|---------| | `manifest.json` | Yes | Plugin identity, capabilities, entry point | | `README.md` | Yes | User-facing documentation | | `LICENSE` | Yes | SPDX-identified license file | | `CHANGELOG.md` | Recommended | Version history for users | | `.gitignore` | Recommended | Exclude build artifacts, secrets | ### README Template ```markdown # Plugin Name Brief one-line description. ## Installation \`\`\`bash cortex plugins install marketplace:my-plugin \`\`\` ## Configuration Describe any required configuration in `~/.cortex/config.json`. ## Capabilities - **capability-name**: What it does, expected input, output format - **capability-name**: What it does, expected input, output format ## Examples Show typical usage examples the agent would invoke. ## Permissions List the capabilities/permissions the plugin declares and why. ## Development Setup instructions for contributing. ## License MIT ``` ### CHANGELOG Template ```markdown # Changelog ## [1.1.0] — 2026-06-15 ### Added - New capability: batch processing ### Fixed - Timeout handling for large inputs ## [1.0.0] — 2026-06-01 ### Added - Initial release ``` ### Repository Metadata Configure these GitHub repository settings for best marketplace integration: - **Description**: Brief one-line description of your plugin (shown in marketplace cards) - **Website**: Link to your plugin's homepage or documentation - **Topics**: Add relevant tags (e.g., `cortex-plugin`, `esm`, `code-execution`, `developer-tools`) - Always include `cortex-plugin` as a topic - Include the plugin type: `esm`, `mcp`, or `wasm` - Include category keywords: `development`, `data-processing`, `security`, `productivity`, `analytics`, `communication`, `research` - **License**: Must match the SPDX identifier in your manifest GitHub topics are automatically fetched and displayed on your plugin's marketplace detail page. ## Versioning ### Semantic Versioning All plugins MUST follow [Semantic Versioning 2.0.0](https://semver.org): ``` MAJOR.MINOR.PATCH ``` | Bump | When | Example | |------|------|---------| | **MAJOR** | Breaking changes to capability signatures, removed capabilities, changed behavior | `1.0.0` → `2.0.0` | | **MINOR** | New capabilities, new parameters (backward compatible) | `1.0.0` → `1.1.0` | | **PATCH** | Bug fixes, performance improvements, documentation updates | `1.0.0` → `1.0.1` | ### Pre-release Versions Use pre-release suffixes for development builds: ```json { "version": "2.0.0-alpha.1" } { "version": "2.0.0-beta.2" } { "version": "2.0.0-rc.1" } ``` Pre-release versions are lower precedence than the release version and are not shown in default marketplace listings. ### Version Rules 1. **Once published, a version is immutable**. If you need to fix a released version, publish a new PATCH version. 2. **The manifest `version` field must match the git tag**. Tag releases with `v{version}` (e.g., `v1.0.0`). 3. **Minimum version is `1.0.0`** for the first stable release. Use `0.x.0` for initial development. 4. **Increment correctly**: assess whether your changes are MAJOR, MINOR, or PATCH before each release. 5. **Document breaking changes** in the CHANGELOG with migration instructions. ### Breaking Change Checklist When preparing a MAJOR version bump, ensure: - All capability signature changes are documented - Migration path is provided for users of the previous version - CHANGELOG includes a "Migration from vX" section - Old capabilities are deprecated for at least one MINOR release before removal - Deprecation notice is logged at runtime when old capabilities are called ### Dependency Versioning If your plugin depends on other plugins, specify semver ranges: ```json { "dependencies": { "base-plugin": "^1.0.0" } } ``` - `^1.0.0` — Compatible with 1.x.x - `~1.0.0` — Compatible with 1.0.x - `1.0.0` — Exact version only ## AI Disclosure CortexPrism requires transparency about the use of AI-assisted development tools in plugin submissions. This builds trust with users and helps reviewers understand the code origin. ### When to Disclose You must disclose AI assistance if any part of your plugin submission was: - **Generated** by an AI coding tool (GitHub Copilot, Claude, ChatGPT, etc.) - **Translated** from another language using AI - **Refactored** or **optimized** by AI tools - **Reviewed** by AI for security or correctness - **Documented** using AI-generated text (README, comments) You do NOT need to disclose: - Standard IDE autocomplete (intelligent code completion without generating blocks) - Linting and formatting tools - Spell-checking and grammar tools - Dependency resolution ### Disclosure Format Include an `AI.md` file (or section in README) at the root of your plugin repository: ```markdown # AI Disclosure ## Tools Used - GitHub Copilot (code generation) - Claude (code review) - ChatGPT (documentation) ## Scope - `mod.ts`: Core logic was drafted by Copilot, manually reviewed and modified - `README.md`: Initial draft by ChatGPT, edited for accuracy - `test/unit/*.ts`: Test cases generated by Copilot ## Review All AI-generated code was reviewed, tested, and verified by a human developer before submission. ## Certification I certify that I understand the code being submitted and take full responsibility for its behavior and security. ``` ### Manifest Declaration Add an `aiDisclosure` field to your manifest: ```json { "name": "my-plugin", "version": "1.0.0", "aiDisclosure": { "tools": ["copilot", "claude"], "generatedFiles": ["mod.ts", "README.md"], "humanReviewed": true, "statement": "All AI-generated code was reviewed, tested, and verified." } } ``` ### Why Disclosure Matters 1. **Trust**: Users know what to expect from the code they're installing 2. **Review**: Reviewers can focus on human-written vs. AI-generated sections 3. **Security**: AI-generated code may contain subtle vulnerabilities that need extra scrutiny 4. **Attribution**: Proper credit for the development process 5. **License compliance**: Some AI tools have specific attribution requirements ### Review Expectations for AI-Assisted Submissions Submissions that declare AI assistance receive the same review process as unassisted submissions, but reviewers will: - Pay extra attention to security boundaries (input validation, permission checks) - Verify that error handling is complete and not hallucinated - Check for nonsensical or dead code paths - Confirm that API usage matches documented behavior - Flag any code that appears to have been submitted without human review ## Submission Procedure ### Pre-Submission Checklist Before submitting, verify each item: **Repository** - [ ] Repository is public and accessible - [ ] `manifest.json` is valid JSON and complete - [ ] `README.md` exists with installation and usage documentation - [ ] `LICENSE` file exists with a valid SPDX identifier - [ ] Repository has a clear description and relevant topics - [ ] No secrets, API keys, or credentials in the codebase - [ ] `.gitignore` excludes build artifacts and secrets **Code** - [ ] Plugin installs and loads without errors (`cortex plugins install ./my-plugin`) - [ ] All capabilities work in a chat session (`cortex chat --agent my-agent`) - [ ] The plugin works in a chat session (`cortex chat --agent my-agent`) - [ ] All permissions declared are actually used - [ ] Error handling covers expected failure modes - [ ] Input validation is implemented for all capability parameters - [ ] The plugin handles timeout and cancellation gracefully **Versioning** - [ ] Version follows Semantic Versioning - [ ] Version is not already published on the marketplace - [ ] `CHANGELOG.md` is updated for this version - [ ] Git tag exists matching the version (`git tag v1.0.0`) **Documentation** - [ ] README includes installation command, configuration, examples - [ ] Screenshots (if applicable) are prepared in PNG format, 1280x720 - [ ] AI disclosure is provided if AI tools were used - [ ] Tags are accurate and descriptive **Legal** - [ ] Plugin complies with the CortexPrism Marketplace Terms of Service - [ ] All dependencies have compatible licenses - [ ] Plugin does not violate any third-party intellectual property - [ ] AI disclosure (if applicable) is complete and accurate ### Step-by-Step Submission #### 1. Prepare Your Release ```bash # Tag the release git tag v1.0.0 git push origin v1.0.0 # Verify the build cortex plugins install ./my-plugin # Test in a chat session cortex chat --agent my-agent #### 2. Submit via Web UI Navigate to the [Publish Plugin](/marketplace/publish/plugin) page and complete all sections: - **Basic Information**: Name (must match manifest), version, description - **Plugin Details**: Kind, entry point, capabilities list - **Author & Links**: Author name, GitHub repository URL, homepage, license - **Media**: Icon URL (256x256 PNG/SVG recommended), screenshots - **Tags**: Add category and feature tags for discoverability - **Category**: Select the most appropriate category #### 3. Submit via API (CI/CD) For automated publishing, use the API: ```bash #!/bin/bash # publish.sh — Automated plugin publishing script PLUGIN_NAME="my-plugin" VERSION=$(jq -r '.version' manifest.json) # Authenticate TOKEN=$(curl -s -X POST https://cortexprism.io/api/auth/login \ -H 'Content-Type: application/json' \ -d "{\"email\":\"$MARKETPLACE_EMAIL\",\"password\":\"$MARKETPLACE_PASSWORD\"}" \ | jq -r '.token') # Submit plugin curl -X POST https://cortexprism.io/api/marketplace/plugins \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d "$(cat </dev/null || echo '[]'), "tags": ["cortex-plugin", "esm"], "repository": "https://github.com/your-org/$PLUGIN_NAME", "license": "$(jq -r '.license // "MIT"' manifest.json)" } JSON )" echo "Submitted $PLUGIN_NAME v$VERSION for review." ``` #### 4. GitHub Actions CI/CD Add this workflow to `.github/workflows/publish.yml`: ```yaml name: Publish to Marketplace on: push: tags: - 'v*' jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: denoland/setup-deno@v2 with: deno-version: v2.x - run: deno task test publish: needs: test runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Publish plugin env: MARKETPLACE_EMAIL: ${{ secrets.MARKETPLACE_EMAIL }} MARKETPLACE_PASSWORD: ${{ secrets.MARKETPLACE_PASSWORD }} run: | chmod +x ./publish.sh ./publish.sh ``` Set `MARKETPLACE_EMAIL` and `MARKETPLACE_PASSWORD` as [GitHub Actions secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions). #### 5. Post-Submission After submission: 1. **Status** is set to `pending` automatically 2. **Review timeline**: Most submissions are reviewed within 48 hours 3. **Notifications**: You will receive a notification when your plugin is reviewed 4. **Track progress**: Check status on your [Dashboard](/dashboard) 5. **If rejected**: Review the rejection notes, fix the issues, and resubmit with an incremented version ### Marketplace Review Standards Reviewers evaluate submissions against these criteria: | Criterion | Weight | Description | |-----------|--------|-------------| | Functionality | Critical | Plugin works as described, all capabilities execute correctly | | Security | Critical | No dangerous patterns, permissions are minimal and correct | | Documentation | High | README is clear, installation works, examples are accurate | | Code Quality | Medium | Error handling, input validation, performance considerations | | Compliance | High | Licensing, AI disclosure, naming conventions, versioning | | Originality | Medium | Plugin provides distinct value, not a trivial wrapper | ### Resubmission After Rejection If your submission is rejected: 1. Read the reviewer notes carefully 2. Fix all identified issues 3. Increment the version (PATCH for fixes, MINOR for significant changes) 4. Update CHANGELOG.md with the changes made 5. Resubmit through the standard process Common rejection reasons and how to avoid them: | Rejection Reason | How to Avoid | |-----------------|--------------| | Missing or invalid manifest | Validate your manifest JSON before submitting | | Plugin fails to load | Test `cortex plugins install ./my-plugin` before submitting | | Insufficient documentation | Write a complete README with installation and examples | | Overly broad permissions | Only declare the permissions your plugin actually uses | | Missing license | Include a `LICENSE` file with a valid SPDX identifier | | AI disclosure not provided | Add `AI.md` or an `aiDisclosure` field if AI tools were used | | Version already exists | Increment the version for the new submission | | Repository not accessible | Make the repository public before submitting | URL: https://cortexprism.io/docs/developer-guide/submission-standards --- ### Wasm Plugin # WASM Plugin Development WASM (WebAssembly) plugins compile to `.wasm` bytecode and run in a sandboxed runtime. They offer the highest performance and strongest security isolation, making them ideal for CPU-intensive or security-sensitive operations. ## Overview WASM plugins export functions using the WASM ABI that the CortexPrism WASM runtime can call. The runtime handles memory management, type marshalling, and sandboxing. ## Supported Languages | Language | Toolchain | Status | |----------|-----------|--------| | Rust | `wasm-pack` / `wasm32-wasi` | Recommended | | Go | `GOOS=wasip1 GOARCH=wasm` | Supported | | C/C++ | `clang` with `wasm32-wasi` target | Supported | | AssemblyScript | `as-compiler` | Supported | | Zig | `zig build-exe -target wasm32-wasi` | Supported | ## Rust WASM Plugin (Recommended) ### Setup ```bash cargo new --lib my-wasm-plugin cd my-wasm-plugin ``` Add to `Cargo.toml`: ```toml [package] name = "my-wasm-plugin" version = "1.0.0" edition = "2021" [lib] crate-type = ["cdylib"] [dependencies] cortexprism-wasm-sdk = "0.1" serde = { version = "1", features = ["derive"] } serde_json = "1" [profile.release] opt-level = "s" lto = true ``` ### Implementing Capabilities ```rust use cortexprism_wasm_sdk::{register_capability, CapabilityContext}; use serde::{Deserialize, Serialize}; #[derive(Deserialize)] struct TransformInput { text: String, mode: String, } #[derive(Serialize)] struct TransformOutput { result: String, length: usize, hash: u64, } fn transform_text(input: TransformInput, _ctx: CapabilityContext) -> TransformOutput { let result = match input.mode.as_str() { "reverse" => input.text.chars().rev().collect(), "uppercase" => input.text.to_uppercase(), "lowercase" => input.text.to_lowercycle(), "rot13" => input.text.chars().map(rot13_char).collect(), _ => input.text, }; TransformOutput { length: result.len(), hash: simple_hash(&result), result, } } register_capability!("transform", transform_text); fn simple_hash(s: &str) -> u64 { s.bytes().fold(0u64, |acc, b| acc.wrapping_mul(31).wrapping_add(b as u64)) } ``` ### Building ```bash cargo build --release --target wasm32-wasi ``` The output is at `target/wasm32-wasi/release/my_wasm_plugin.wasm`. ## Plugin Manifest ```json { "name": "text-processor", "version": "1.0.0", "type": "wasm", "entryPoint": "text_processor.wasm", "description": "High-performance text transformation plugin", "wasm": { "memoryPages": 10, "maxMemoryPages": 50, "allocator": "wasi" } } ``` ## Go WASM Plugin ```go package main import ( "strings" "unicode/utf8" ) //export transform func transform(ptr uint32, len uint32) uint32 { input := readMemory(ptr, len) result := strings.ToUpper(input) return writeMemory(result) } //export count_tokens func countTokens(ptr uint32, len uint32) uint32 { input := readMemory(ptr, len) count := utf8.RuneCountInString(input) / 4 if count < 1 { count = 1 } return count } func main() {} ``` Build: ```bash GOOS=wasip1 GOARCH=wasm go build -o plugin.wasm main.go ``` ## Capability ABI Each exported WASM function follows this signature convention: ```wasm (func (param i32 i32) (result i32)) ``` - **Input pointer** (`i32`): Pointer to JSON-encoded input arguments in shared memory - **Input length** (`i32`): Length of the input buffer - **Return value** (`i32`): Pointer to JSON-encoded result in shared memory The runtime handles memory allocation and deallocation. ## Memory Model - WASM plugins operate on a linear memory space - The runtime allocates an initial number of pages (64KB each) - The plugin can request additional pages up to the configured maximum - String data is passed through shared memory using the WASI allocator or a custom allocator - Memory is cleared between capability calls for isolation ## Performance Characteristics | Operation | ESM | WASM | |-----------|-----|------| | Cold start | ~10ms | ~1ms | | Text processing (1MB) | ~50ms | ~5ms | | JSON parse (100KB) | ~2ms | ~0.3ms | | Memory overhead | ~30MB | ~5MB | ## Security - WASM runs in a sandboxed runtime with no access to the host system - Memory isolation: each call gets a fresh memory space - Resource limits: configurable memory pages and execution time - No network access by default (can be enabled via permissions) - System call filtering via WASI preview 1 ## Testing ```typescript import { testWasmPlugin } from "@cortexprism/plugin-sdk/testing"; const plugin = await testWasmPlugin("text_processor.wasm"); const result = await plugin.call("transform", { text: "hello world", mode: "uppercase", }); console.assert(result.result === "HELLO WORLD"); ``` ## Debugging Enable WASM runtime logging: ```bash cortex --verbose plugin call text-processor transform '{"text":"hello","mode":"reverse"}' ``` For Rust plugins, use `wasm32-wasi` debugging tools: ```bash wasm2wat plugin.wasm | less # Inspect the WASM module wasmtime run plugin.wasm # Test outside CortexPrism ``` URL: https://cortexprism.io/docs/developer-guide/wasm-plugin --- ## Getting Started ### Configuration # Configuration Complete reference for the CortexPrism configuration system. ## Config File Location Default: `~/.cortex/config.json` Override with: - `--config` / `-c` flag - `CORTEX_CONFIG` environment variable ## Full Configuration Schema ```json { "version": 1, "defaultProvider": "anthropic", "providers": { "anthropic": { "kind": "anthropic", "model": "claude-sonnet-4-5", "apiKey": "sk-..." }, "openai": { "kind": "openai", "model": "gpt-4o", "apiKey": "sk-..." }, "google": { "kind": "google", "model": "gemini-2.0-flash", "apiKey": "..." }, "mistral": { "kind": "mistral", "model": "mistral-large-latest", "apiKey": "..." }, "groq": { "kind": "groq", "model": "llama-3.3-70b-versatile", "apiKey": "gsk_..." }, "deepseek": { "kind": "deepseek", "model": "deepseek-chat", "apiKey": "sk-..." }, "openrouter": { "kind": "openrouter", "model": "openai/gpt-4o", "apiKey": "..." }, "xai": { "kind": "xai", "model": "grok-2-latest", "apiKey": "..." }, "together": { "kind": "together", "model": "meta-llama/Llama-3.3-70B-Instruct-Turbo", "apiKey": "..." }, "bedrock": { "kind": "bedrock", "model": "anthropic.claude-3-5-sonnet-20240620-v1:0", "apiKey": "AKIA...", "secretKey": "...", "baseUrl": "us-east-1" }, "cohere": { "kind": "cohere", "model": "command-r-plus", "apiKey": "..." }, "ollama": { "kind": "ollama", "model": "llama3.2", "baseUrl": "http://localhost:11434" } }, "agent": { "name": "My Agent", "maxTurns": 50, "streamOutput": true }, "router": { "enabled": false, "strategy": "cascade", "confidenceThreshold": 0.7, "cascade": [ { "provider": "ollama", "model": "llama3.2:3b" }, { "provider": "ollama", "model": "llama3.1:8b" }, { "provider": "anthropic", "model": "claude-sonnet-4-5" } ] }, "update": { "channel": "stable", "checkOnStartup": true, "autoUpdate": false, "checkIntervalHours": 24, "githubToken": "", "gpgKeyPath": "" } } ``` ## Router Configuration ### Strategy | Value | Description | |-------|-------------| | `cascade` | Try providers in order, falling through each level | | `threshold` | Route based on complexity scoring threshold | The `cascade` strategy attempts each provider in sequence: if the first provider fails or returns low confidence, the router falls through to the next. The `threshold` strategy evaluates task complexity and routes directly to the appropriate provider tier. ### Confidence Threshold Controls how strictly the router evaluates LLM responses before cascading to the next provider. Higher values (0.8+) enforce stricter quality gates; lower values (0.5) cascade less aggressively. ## Update Configuration The `update` section controls Cortex's self-update behavior: | Field | Type | Description | Default | |-------|------|-------------|---------| | `channel` | `string` | Update channel: `stable` or `pre-release` | `stable` | | `checkOnStartup` | `boolean` | Check for updates on startup | `true` | | `autoUpdate` | `boolean` | Automatically apply updates | `false` | | `checkIntervalHours` | `number` | Periodic check interval | `24` | | `githubToken` | `string` | GitHub token for API rate limits | `""` | | `gpgKeyPath` | `string` | Path to GPG key for signature verification | `""` | ### Update Channels | Channel | Description | |---------|-------------| | `stable` | Production-ready releases with full testing | | `pre-release` | Pre-release builds with latest features | ### Binary vs Source Mode - **Binary mode**: Downloads pre-built binaries with SHA-256 verification and optional GPG signature validation - **Source mode**: Pulls latest source and rebuilds (when running from source or binary unavailable) ## Environment Variables | Variable | Description | Default | |----------|-------------|---------| | `CORTEX_CONFIG` | Path to config file | `~/.cortex/config.json` | | `CORTEX_DATA_DIR` | Data directory path | `~/.cortex/` | | `CORTEX_VAULT_KEY` | Vault encryption passphrase | — | | `OPENAI_API_KEY` | OpenAI API key | — | | `ANTHROPIC_API_KEY` | Anthropic API key | — | | `GOOGLE_API_KEY` | Google AI API key | — | ## Data Directory Structure ``` ~/.cortex/ ├── config.json └── data/ ├── cortex.db → Core: sessions, jobs, policy rules ├── memory.db → 5-tier memory + FTS5 + embeddings ├── lens.db → Audit log ├── vault.db → Encrypted credentials ├── plugins.db → Plugin registry └── sess_*.db → Per-session message history ``` ## Provider Configuration Details ### OpenAI-Compatible Providers Providers like Groq, DeepSeek, OpenRouter, xAI, and Together AI use the `openai` compatible API format with custom `baseUrl`: ```json { "groq": { "kind": "openai", "model": "llama-3.3-70b-versatile", "apiKey": "gsk_...", "baseUrl": "https://api.groq.com/openai/v1" } } ``` ### AWS Bedrock Bedrock requires `secretKey` in addition to `apiKey`, with `baseUrl` set to the AWS region: ```json { "bedrock": { "kind": "bedrock", "model": "anthropic.claude-3-5-sonnet-20240620-v1:0", "apiKey": "AKIA...", "secretKey": "...", "baseUrl": "us-east-1" } } ``` ### Ollama (Local) Ollama runs locally and doesn't need an API key, just a `baseUrl` pointing to the Ollama server: ```json { "ollama": { "kind": "ollama", "model": "llama3.2", "baseUrl": "http://localhost:11434" } } ``` URL: https://cortexprism.io/getting-started/configuration --- ### First Run # First Run Guide to your first CortexPrism session. ## The Setup Wizard When you run `cortex` for the first time (or `cortex setup`), the setup wizard will guide you through: 1. **Mode Selection** — Choose CLI or Web interface 2. **LLM Provider** — Choose from 24 providers: Anthropic, OpenAI, Google, Mistral, Groq, DeepSeek, OpenRouter, xAI Grok, Together AI, AWS Bedrock, Cohere, Ollama, Cerebras, Fireworks AI, Perplexity, NVIDIA NIM, Moonshot (Kimi), Novita AI, LM Studio, LiteLLM, Hugging Face, Alibaba (Qwen), Venice AI, Kilo AI (or skip to configure later) 3. **AI Personalization** — Optional context about how you use AI 4. **Personality Template** — Choose from 8 soul templates (professional, friendly, developer, creative, analyst, teacher, minimalist, custom) 5. **Channel Setup** — CLI, CLI+Web, CLI+Discord, or all channels 6. **Telemetry** — Opt in or out of anonymous usage data collection ## Configuration File After setup, your configuration is stored at `~/.cortex/config.json`: ```json { "version": 1, "defaultProvider": "anthropic", "providers": { "anthropic": { "kind": "anthropic", "model": "claude-sonnet-4-20250514", "apiKey": "sk-ant-..." } }, "agent": { "name": "Cortex", "maxTurns": 50, "streamOutput": true }, "router": { "enabled": false, "confidenceThreshold": 0.7, "cascade": [] } } ``` ## Data Directory Default: `~/.cortex/data/` Override: ```bash CORTEX_DATA_DIR=/data/cortex cortex chat ``` The data directory contains: | File | Contents | |------|----------| | `cortex.db` | Core: sessions, jobs, policy rules | | `memory.db` | 5-tier memory: episodic, semantic, reflection | | `lens.db` | Audit log: all events, tool calls, policy checks | | `vault.db` | Encrypted credentials | | `plugins.db` | Plugin registry | | `sess_*.db` | Per-session message history | ## Your First Chat ```bash cortex chat ``` On first chat, the system: 1. Starts background daemons (validator, executor, scheduler) 2. Initializes the chat session 3. Injects any relevant memory into context 4. Connects to your configured LLM provider Type a message and the agent will respond. Try these: - `"What can you do?"` — Learn about agent capabilities - `"Search the web for latest AI news"` — Web search via DuckDuckGo - `"Run a Python script that calculates fibonacci"` — Sandboxed code execution - `"Read the file ~/.cortex/config.json"` — File reading via tool - `"Remember that I use VS Code"` — Store a fact in memory ## What Happens Behind the Scenes ``` Your message → Agent retrieves relevant memories → Builds prompt with context → Sends to LLM provider → LLM responds (may request tool calls) → Tool calls are validated by Parallax security → Approved tools execute (file read, web search, code run) → Results fed back to LLM for final response → Response streamed back to you → Session history saved to SQLite → Episodic memory written (async) → Reflection performed (async) ``` URL: https://cortexprism.io/getting-started/first-run --- ### Getting Started with CortexPrism # Quickstart Get started with CortexPrism in under 5 minutes. ## Prerequisites - [Deno](https://deno.land) v2.0 or later - An API key from one of the [supported LLM providers](/docs/knowledge-base/provider-guide) - Docker (optional, for sandbox isolation — subprocess fallback available) ## Installation ```bash git clone https://github.com/CortexPrism/cortex.git cd cortex deno run --allow-all src/main.ts setup ``` This installs dependencies and initializes all databases. ## Configure a Provider Run the setup wizard: ```bash cortex setup ``` This will guide you through configuring your first LLM provider. You'll be prompted to: 1. Select a mode (CLI or Web) 2. Choose from 24 LLM providers (or skip) 3. Complete AI personalization questions (optional) 4. Select a personality template (8 templates) 5. Configure channels (CLI, Web, Discord) 6. Set telemetry preference You can also manually edit `~/.cortex/config.json`. ## Start Chatting ```bash cortex chat ``` This starts an interactive streaming chat session with the default provider. The agent automatically starts background daemons for tool validation and execution. ### Try these commands: - `"What can you do?"` — See available capabilities - `"Search the web for latest AI news"` — Web search via DuckDuckGo - `"Run a Python script that calculates fibonacci"` — Sandboxed code execution - `"Remember that my project is called Project X"` — Stores to semantic memory ## Next Steps - [Detailed Installation Guide](/getting-started/installation) — System requirements and Docker setup - [First Run Guide](/getting-started/first-run) — Understanding the setup wizard, config file, and first session - [Configuration Reference](/getting-started/configuration) — Full configuration options, environment variables - [CLI Commands](/docs/cli) — Full command reference - [Architecture Overview](/docs/architecture) — Understand how CortexPrism works - [Browse Marketplace](/marketplace) — Discover plugins and agents URL: https://cortexprism.io/getting-started/ --- ### Installation # Installation Detailed installation guide for CortexPrism. ## System Requirements - **OS**: Linux, macOS, or Windows (native or WSL2) - **Runtime**: Deno v2.0 or later - **Memory**: 4GB RAM minimum (8GB+ recommended) - **Storage**: 500MB for base installation (more for plugin data) ## Quick Install ### macOS & Linux ```bash curl -fsSL https://cortexprism.io/install.sh | bash ``` ### Windows (PowerShell) ```powershell iwr -Uri https://cortexprism.io/install.ps1 -OutFile install.ps1 .\install.ps1 ``` Windows users can also use Git Bash or WSL2 with the macOS/Linux command above. ## Install Deno ```bash # macOS / Linux curl -fsSL https://deno.land/install.sh | sh ``` ```powershell # Windows (PowerShell) iwr https://deno.land/install.ps1 -useb | iex ``` Or use your package manager: ```bash # macOS (Homebrew) brew install deno # Linux (apt/curl) curl -fsSL https://deno.land/install.sh | sh ``` ```powershell # Windows (Scoop) scoop install deno # Windows (winget) winget install DenoLand.Deno ``` ## Clone and Setup ```bash # macOS / Linux git clone https://github.com/CortexPrism/cortex.git cd cortex deno run --allow-all src/main.ts setup ``` ```powershell # Windows (PowerShell) git clone https://github.com/CortexPrism/cortex.git cd cortex deno run --allow-all src/main.ts setup ``` The setup command runs database migrations and creates the initial config file. ## Docker Installation A Docker image is available for containerized deployments: ```bash docker pull cortexprism/cortex:latest # Interactive chat docker run -it --rm \ -v ~/.cortex:/home/cortex/.cortex \ -e CORTEX_VAULT_KEY=your-passphrase \ cortexprism/cortex:latest chat # Run server docker run -d --rm \ -p 3000:3000 \ -v ~/.cortex:/home/cortex/.cortex \ cortexprism/cortex:latest serve ``` ## Verify Installation ```bash cortex --version ``` You should see the version number printed: ``` cortex 0.35.3 ``` ## Next Steps - [First Run](/getting-started/first-run) — Walk through your first CortexPrism session - [Configuration](/getting-started/configuration) — Learn about configuration options and environment variables URL: https://cortexprism.io/getting-started/installation --- ## Knowledge Base ### Frequently Asked Questions # Frequently Asked Questions ## General ### What is CortexPrism? CortexPrism is an open-source agentic harness system written in TypeScript/Deno. It provides a runtime for building, deploying, and managing AI agents with support for 12+ LLM providers, a 5-tier memory system, sandboxed code execution, and a defense-in-depth security model. ### What is an "agentic harness"? An agentic harness is a runtime system that hosts, orchestrates, and empowers AI agents. It manages the full lifecycle of agent interactions including LLM calls, tool execution, memory persistence, security validation, and user interfaces. ### Do I need a GPU? No. CortexPrism runs entirely on CPU. All LLM calls are made through provider APIs — you only need a network connection. ### Is it free and open source? Yes. CortexPrism is released under the MIT License. The source code is available on [GitHub](https://github.com/CortexPrism/cortex). ### What are the system requirements? - **OS**: Linux, macOS, or Windows (via WSL2) - **Runtime**: Deno v2.0+ - **Memory**: 4GB RAM minimum (8GB+ recommended) - **Storage**: 500MB for base installation - **Optional**: Docker for sandboxed code execution ## LLM Providers ### What providers are supported? 12+ providers are supported: Anthropic Claude, OpenAI, Google Gemini, Mistral AI, Groq, DeepSeek, OpenRouter, xAI (Grok), Together AI, AWS Bedrock, Cohere, and Ollama (local). ### Can I switch providers mid-session? Yes. Use the `/model` slash command inside a chat session to switch models, or start a new session with `--model` or `--provider` flags. ### Can I use multiple providers at once? Yes. The CascadeRouter can be configured to try cheaper models first and escalate to more capable ones when confidence is low. ### Can I use CortexPrism offline? CortexPrism requires network access for LLM API calls. However, you can run local models via Ollama for fully offline operation. The memory system, plugin management, and tool execution work offline. ## Memory ### How does the memory system work? CortexPrism uses a 5-tier memory system with hybrid retrieval combining FTS5 keyword search and cosine vector similarity, scored with exponential time decay. Memories are automatically retrieved and injected into the agent's context. ### Is my data private? Memory data is stored locally in SQLite databases on your machine. The Vault uses AES-256-GCM encryption for sensitive credentials. No memory data is sent to external services except the LLM provider API calls. ## Security ### How does the Parallax security model work? Every tool call passes through a 3-stage validator: tool name check, shell command pattern check, and domain allow/deny rules. All decisions are logged to the Cortex Lens audit trail. ### What dangerous commands are blocked by default? - `rm -rf /` and variants - Shell fork bomb patterns - Direct disk writes (`dd` to block devices) - World-writable root permissions (`chmod 777 /`) URL: https://cortexprism.io/docs/knowledge-base/faq --- ### Knowledge Base # Knowledge Base Welcome to the CortexPrism knowledge base. Find answers to common questions, troubleshooting guides, best practices, provider setup guides, and reference materials. ## Topics | Article | Description | |---------|-------------| | [FAQ](/docs/knowledge-base/faq) | Frequently asked questions about CortexPrism | | [Troubleshooting](/docs/knowledge-base/troubleshooting) | Common issues and their solutions | | [Best Practices](/docs/knowledge-base/best-practices) | Tips and recommendations for effective usage | | [Provider Guide](/docs/knowledge-base/provider-guide) | Step-by-step LLM provider setup guides | | [Sandbox Guide](/docs/knowledge-base/sandbox-guide) | Code sandbox usage, configuration, and security | | [Migration Guide](/docs/knowledge-base/migration-guide) | Upgrading between versions and migrating data | | [Security Guidelines](/docs/knowledge-base/security-guidelines) | Security hardening and operational security | | [Performance Tuning](/docs/knowledge-base/performance-tuning) | Optimizing performance, memory, and throughput | ## Quick Links - [CLI Reference](/docs/cli) — Complete command reference - [Architecture Overview](/docs/architecture) — System architecture documentation - [Getting Started](/getting-started) — Installation and first-run guides - [Developer Guide](/docs/developer-guide) — Plugin and agent development URL: https://cortexprism.io/docs/knowledge-base/index --- ### Troubleshooting # Troubleshooting ## Common Issues ### API Key Not Found ``` Error: No API key found for provider "openai" ``` **Solution**: Run `cortex setup` to configure your API key, or set the corresponding environment variable (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.). ### API Key Not Set for Provider ``` Error: Provider "openai" has no apiKey set ``` **Solution**: Edit `~/.cortex/config.json` and add the `apiKey` field for the provider, or set the environment variable. ### Plugin Not Found ``` Error: Plugin "python-executor" not found ``` **Solution**: Install the plugin first: ```bash cortex plugin install marketplace:cortexprism.io/plugins/python-executor ``` ### Database Locked ``` Error: SQLITE_BUSY: database is locked ``` **Solution**: Close other CortexPrism processes and try again. If the issue persists, check for stale lock files: ```bash ls -la ~/.cortex/data/*-journal ``` ### Sandbox: Docker Not Available ``` Error: Docker is not available. Falling back to subprocess mode. ``` **Solution**: This is a warning, not an error — subprocess fallback works. Install Docker for sandbox isolation: ```bash # Ubuntu/Debian sudo apt install docker.io # macOS brew install --cask docker ``` ### Sandbox: Command Timeout ``` Error: Sandbox execution timed out after 30 seconds ``` **Solution**: Optimize your code to run faster, or increase the timeout in the configuration. The sandbox has a default 30-second timeout with 64KB output limit. ### Port Already in Use ``` Error: Address in use (os error 98) ``` **Solution**: Either stop the existing server (`cortex serve -s`) or use a different port (`cortex serve --port 8080`). ### Vault: CORTEX_VAULT_KEY Not Set ``` Error: CORTEX_VAULT_KEY environment variable is not set ``` **Solution**: Set the passphrase before using vault commands: ```bash export CORTEX_VAULT_KEY="your-strong-passphrase" ``` ## Debugging Enable verbose logging to get more details: ```bash cortex --verbose chat ``` Check the Cortex Lens audit log for security events and tool calls via the web UI at `http://localhost:3000`. ## Getting Help - Open an issue on [GitHub](https://github.com/CortexPrism/cortex/issues) - Check the [Architecture Docs](/docs/architecture) for system understanding - Review [Design Docs](https://github.com/CortexPrism/cortex/tree/main/docs/design) for detailed specifications URL: https://cortexprism.io/docs/knowledge-base/troubleshooting --- ### Best Practices # Best Practices Tips and recommendations for getting the most out of CortexPrism. ## Configuration ### Use Environment Variables for API Keys Instead of storing API keys directly in `config.json`, use environment variables: ```bash export OPENAI_API_KEY="sk-..." export ANTHROPIC_API_KEY="sk-ant-..." ``` The config file can reference these via provider configuration. ### Set Up Multiple Providers Configure multiple providers for redundancy and cost optimization: ```json { "defaultProvider": "anthropic", "providers": { "anthropic": { "kind": "anthropic", "model": "claude-sonnet-4-20250514", "apiKey": "..." }, "ollama": { "kind": "ollama", "model": "llama3.2", "baseUrl": "http://localhost:11434" } } } ``` ### Use the Vault for Secrets Always store sensitive credentials in the vault rather than plaintext config: ```bash export CORTEX_VAULT_KEY="strong-passphrase" cortex vault store "openai-key" --service openai ``` ## Memory ### Add Important Context to Semantic Memory Proactively store important information: ```bash cortex memory add "Project deploy URL: https://staging.example.com" cortex memory add "The team uses pnpm for package management" ``` This makes persistent knowledge available across all future sessions. ### Use Precise Memory Queries For better memory retrieval, use specific keywords: ```bash # Good cortex memory search "deployment config staging environment" # Less effective cortex memory search "thing about setup" ``` ## Security ### Review Policy Rules Regularly ```bash cortex policy list ``` Audit your policy rules periodically to ensure they match your security needs. ### Use Approval Gates for Sensitive Operations Configure approval gates for operations that modify the system or access sensitive data. The `shell` and `code_exec` tools have built-in approval gates. ## Development ### Use the Auto-Fix Loop When running code, enable the auto-fix loop to automatically correct errors: ```bash cortex run script.py --fix ``` ### Run the Server for Complex Workflows For multi-session workflows or monitoring, use the web UI: ```bash cortex serve -d ``` Then access the dashboard at `http://localhost:3000` with Chat, Lens, Memory, and Jobs tabs. ### Use Daemon Mode for Scheduled Tasks Keep the daemon running for scheduled jobs and periodic memory consolidation: ```bash cortex daemon start cortex jobs add --schedule "0 9 * * 1" --task "weekly-report" ``` URL: https://cortexprism.io/docs/knowledge-base/best-practices --- ### Provider Guide # Provider Guide Step-by-step setup guides for all supported LLM providers. ## Anthropic Claude ```bash # 1. Get your API key from https://console.anthropic.com # 2. Configure in config.json: ``` ```json { "anthropic": { "kind": "anthropic", "model": "claude-sonnet-4-20250514", "apiKey": "sk-ant-..." } } ``` Recommended models: `claude-sonnet-4-20250514`, `claude-haiku-4-5`, `claude-opus-4-5` ## OpenAI ```bash # 1. Get your API key from https://platform.openai.com/api-keys # 2. Configure: ``` ```json { "openai": { "kind": "openai", "model": "gpt-4o", "apiKey": "sk-..." } } ``` Recommended models: `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo` ## Google Gemini ```bash # 1. Get your API key from https://aistudio.google.com/apikey # 2. Configure: ``` ```json { "google": { "kind": "google", "model": "gemini-2.0-flash", "apiKey": "..." } } ``` Recommended models: `gemini-2.0-flash`, `gemini-2.5-pro` ## Mistral AI ```bash # 1. Get your API key from https://console.mistral.ai # 2. Configure: ``` ```json { "mistral": { "kind": "mistral", "model": "mistral-large-latest", "apiKey": "..." } } ``` ## Groq ```bash # 1. Get your API key from https://console.groq.com # 2. Configure (OpenAI-compatible): ``` ```json { "groq": { "kind": "groq", "model": "llama-3.3-70b-versatile", "apiKey": "gsk_..." } } ``` ## DeepSeek ```bash # 1. Get your API key from https://platform.deepseek.com # 2. Configure (OpenAI-compatible): ``` ```json { "deepseek": { "kind": "deepseek", "model": "deepseek-chat", "apiKey": "sk-..." } } ``` ## OpenRouter ```bash # 1. Get your API key from https://openrouter.ai/keys # 2. Configure (OpenAI-compatible): ``` ```json { "openrouter": { "kind": "openrouter", "model": "openai/gpt-4o", "apiKey": "..." } } ``` OpenRouter gives access to 200+ models from various providers. ## xAI (Grok) ```bash # 1. Get your API key from https://x.ai/api # 2. Configure (OpenAI-compatible): ``` ```json { "xai": { "kind": "xai", "model": "grok-2-latest", "apiKey": "..." } } ``` ## Together AI ```bash # 1. Get your API key from https://api.together.ai/settings/api-keys # 2. Configure (OpenAI-compatible): ``` ```json { "together": { "kind": "together", "model": "meta-llama/Llama-3.3-70B-Instruct-Turbo", "apiKey": "..." } } ``` ## AWS Bedrock ```bash # 1. Set up AWS credentials with Bedrock access # 2. Configure: ``` ```json { "bedrock": { "kind": "bedrock", "model": "anthropic.claude-3-5-sonnet-20240620-v1:0", "apiKey": "AKIA...", "secretKey": "...", "baseUrl": "us-east-1" } } ``` ## Cohere ```bash # 1. Get your API key from https://dashboard.cohere.com/api-keys # 2. Configure: ``` ```json { "cohere": { "kind": "cohere", "model": "command-r-plus", "apiKey": "..." } } ``` ## Ollama (Local) ```bash # 1. Install Ollama from https://ollama.com # 2. Pull a model: ollama pull llama3.2 # 3. Configure: ``` ```json { "ollama": { "kind": "ollama", "model": "llama3.2", "baseUrl": "http://localhost:11434" } } ``` Ollama runs entirely locally — no API key needed. URL: https://cortexprism.io/docs/knowledge-base/provider-guide --- ### Sandbox Guide # Sandbox Guide CortexPrism provides sandboxed code execution using Docker containers (with subprocess fallback). This guide covers usage, configuration, and security. ## Overview The sandbox system allows agents to execute code safely in isolated environments with resource constraints. Code runs in ephemeral containers that are destroyed after execution. ## How It Works ```bash cortex run script.py # Auto-detect language, run in sandbox cortex run script.py --no-sandbox # Skip sandbox, run as subprocess cortex run script.py --fix # Enable auto-fix on failure ``` ## Docker Sandbox When Docker is available, containers are created with strict resource limits: | Constraint | Value | |------------|-------| | Network | `--network=none` (no external access) | | Memory | 256MB limit | | CPU | 0.5 cores | | Process limit | 64 PIDs | | Security | `no-new-privileges` | | Timeout | 30 seconds | | Max output | 64KB | ## Supported Languages | Language | Extension | Docker Image | Interpreter | |----------|-----------|-------------|-------------| | Python | `.py` | `python:3.12-slim` | `python3` | | JavaScript | `.js` | `node:22-slim` | `node` | | TypeScript | `.ts` | `node:22-slim` | `npx tsx` | | Bash | `.sh` | `ubuntu:24.04` | `bash` | | Ruby | `.rb` | `ruby:3.3-slim` | `ruby` | | Go | `.go` | `golang:1.23-bookworm` | `go run` | | Rust | `.rs` | `rust:1.78-slim` | `rustc -o /tmp/out && /tmp/out` | ## Subprocess Fallback When `docker info` fails (Docker not installed or daemon not running), the sandbox falls back to subprocess mode. The code runs directly on the host machine with the same resource limits applied at the process level. ## Auto-Fix Loop When `--fix` is enabled, the system can automatically fix broken code: ``` runInSandbox(code) → exit != 0? → LLM receives: "Fix this error: \n\nCode:\n" → LLM returns fixed code → runInSandbox(fixedCode) → repeat up to maxRounds (default: 4) ``` ```bash # Enable auto-fix cortex run buggy-code.py --fix # Increase max fix attempts cortex run complex.js --fix --max-fix 8 ``` ## Security Considerations - Docker sandbox has **no network access** (`--network=none`) - Memory and CPU are strictly limited to prevent resource exhaustion - Containers are ephemeral — no data persists after execution - The `no-new-privileges` security flag prevents privilege escalation - Output is capped at 64KB to prevent log flooding ## Configuration The sandbox can be configured through environment variables: | Variable | Description | Default | |----------|-------------|---------| | `CORTEX_SANDBOX_TIMEOUT` | Execution timeout in seconds | `30` | | `CORTEX_SANDBOX_MEMORY` | Memory limit in MB | `256` | | `CORTEX_SANDBOX_MAX_OUTPUT` | Output cap in KB | `64` | ## Best Practices 1. **Always use the sandbox** for untrusted code — avoid `--no-sandbox` unless necessary 2. **Enable auto-fix** during development to iterate faster 3. **Keep scripts simple** — the sandbox has limited memory and no network 4. **Use Python for data analysis** — the Python sandbox includes pip for package installation URL: https://cortexprism.io/docs/knowledge-base/sandbox-guide --- ### Migration Guide # Migration Guide This guide covers upgrading between CortexPrism versions and migrating data between installations. ## Version Compatibility | From | To | Migration Required | |------|----|--------------------| | 0.0.x | 0.1.x | Database migration (`cortex migrate`) | | 0.1.x | 0.2.x | Config format update | | 0.2.x | 1.0.0 | Full migration (see below) | ## Checking Your Version ```bash cortex --version ``` ## Upgrading CortexPrism ### Source Install ```bash cd ~/cortex git pull origin main deno task setup # Runs migrations and dependency updates ``` ### Docker Install ```bash docker pull cortexprism/cortex:latest docker stop cortex-server docker rm cortex-server # Re-create with your docker run command ``` ## Database Migrations CortexPrism uses SQLite with automatic migration support: ```bash # Run all pending migrations cortex migrate # Check migration status cortex migrate --status # Dry run (see what would be applied) cortex migrate --dry-run ``` ### Manual Migration If automatic migration fails, you can run migrations manually: ```bash # Backup first cp ~/.cortex/data/cortex.db ~/.cortex/data/cortex.db.backup # Run specific migration cortex migrate --to v2 ``` ## Data Directory Migration To move your CortexPrism data to a new location: ```bash # Stop all cortex processes cortex daemon stop cortex serve -s # Copy data cp -r ~/.cortex /new/location/.cortex # Set new data directory export CORTEX_DATA_DIR=/new/location/.cortex # Start using new location cortex daemon start ``` ## Config Migration When config format changes between versions: ```bash # Backup existing config cp ~/.cortex/config.json ~/.cortex/config.json.backup # Run setup wizard to regenerate cortex setup # Or manually update config: cortex config migrate ``` ## Plugin Migration When upgrading CortexPrism, plugins may need updates: ```bash # Check plugin compatibility cortex plugin list --check-compatibility # Reinstall plugins for new version cortex plugin reinstall --all # Update a specific plugin cortex plugin update my-plugin ``` ## Rolling Back If an upgrade causes issues: ```bash # Restore database backup cp ~/.cortex/data/cortex.db.backup ~/.cortex/data/cortex.db # Revert to previous version git checkout deno task setup # Reinstall compatible plugins cortex plugin reinstall --all ``` ## Migrating from Other Tools ### From OpenAI Agents SDK CortexPrism supports importing configurations from the OpenAI Agents SDK: ```bash cortex import openai-agents --config agent_config.json ``` ### From LangChain ```bash cortex import langchain --config chain_config.json ``` ### From Custom Setup If you have an existing tool configuration, you can wrap it as a CortexPrism plugin: ```bash cortex plugin install ./my-existing-tool --adapt ``` The adapter mode generates a compatibility layer between your tool and the plugin system. ## Pre-Migration Checklist 1. **Back up databases** — `cp ~/.cortex/data/*.db ~/backup/` 2. **Export plugin list** — `cortex plugin list --format json > plugins.json` 3. **Export config** — `cp ~/.cortex/config.json config.backup.json` 4. **Check disk space** — Ensure enough space for migration 5. **Review changelog** — Check breaking changes in the [Changelog](/changelog) ## Post-Migration Checklist 1. **Verify version** — `cortex --version` 2. **Test chat** — `cortex chat --no-stream "Hello"` 3. **Check plugins** — `cortex plugin list` 4. **Verify data** — `cortex memory search "test"` (if you had memory) 5. **Check logs** — Review Lens audit log for errors URL: https://cortexprism.io/docs/knowledge-base/migration-guide --- ### Security Guidelines # Security Guidelines Security hardening and operational security recommendations for CortexPrism deployments. ## Overview CortexPrism's Parallax security model provides defense-in-depth protection. This guide covers how to configure and operate CortexPrism securely. ## Parallax Security Model ``` User Input → Policy Engine → Validator → Execution → Lens Audit │ ├── Tool Name Check ├── Command Pattern Check └── Domain Allow/Deny Rules ``` Every tool call passes through three validation stages before execution. All decisions are logged to the Lens audit trail. ## Configuration Security ### API Keys Never store API keys in plaintext configuration files on shared systems: ```bash # Good: environment variables export ANTHROPIC_API_KEY="sk-ant-..." export OPENAI_API_KEY="sk-..." # Better: vault export CORTEX_VAULT_KEY="strong-passphrase" cortex vault store "anthropic-key" --service anthropic cortex vault store "openai-key" --service openai ``` ### Vault Encryption The vault uses AES-256-GCM encryption with PBKDF2 key derivation: - **Encryption**: AES-256-GCM (authenticated encryption) - **Key derivation**: PBKDF2 with 600,000 iterations - **Key source**: `CORTEX_VAULT_KEY` environment variable - **Storage**: Encrypted SQLite database (`vault.db`) - **Access logging**: All vault access is logged to Lens ```bash # Set vault passphrase export CORTEX_VAULT_KEY="your-strong-passphrase-min-20-chars!!" # Store a credential cortex vault store "db-password" --service production-db # List stored services cortex vault list # Retrieve (logged to audit trail) cortex vault get "db-password" ``` ## Policy Rules ### Default Deny The policy engine uses a default-deny approach. Only explicitly allowed operations are permitted. ```bash # List current policies cortex policy list # Add a deny rule for dangerous commands cortex policy add deny --pattern "rm -rf /" # Add an allow rule for a specific domain cortex policy add allow --pattern "fetch:https://api.example.com/*" # Remove a policy cortex policy remove ``` ### Rule Evaluation Order 1. Explicit deny rules (checked first) 2. Explicit allow rules 3. Default action (deny) ### Recommended Rules ```bash # Block dangerous operations cortex policy add deny --pattern "rm -rf /" cortex policy add deny --pattern ":(){ :|:& };:" # Fork bomb cortex policy add deny --pattern "dd if=/dev/zero of=/dev/sd*" cortex policy add deny --pattern "chmod 777 /" cortex policy add deny --pattern "> /dev/sd*" # Allow safe operations cortex policy add allow --pattern "fetch:https://*.example.com/*" cortex policy add allow --pattern "read:$HOME/*" cortex policy add allow --pattern "write:$HOME/tmp/*" ``` ## Network Security ### Server Mode When running `cortex serve`, secure the HTTP server: ```bash # Bind to localhost only (default) cortex serve --host 127.0.0.1 # Use a reverse proxy for public access (recommended) # nginx configuration: ``` ```nginx server { listen 443 ssl; server_name cortex.example.com; ssl_certificate /etc/ssl/certs/cortex.crt; ssl_certificate_key /etc/ssl/private/cortex.key; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } } ``` ### API Authentication Enable API authentication in production: ```json { "server": { "port": 3000, "host": "127.0.0.1", "auth": { "required": true, "jwtSecret": "your-secure-secret-change-in-production" } } } ``` ## Sandbox Security ### Docker Sandbox The Docker sandbox provides strong isolation: ``` ┌─────────────────────┐ │ Docker Container │ │ ─────────────── │ │ No network access │ │ 256MB memory limit │ │ 0.5 CPU cores │ │ 64 PIDs max │ │ no-new-privileges │ │ Ephemeral filesystem│ └─────────────────────┘ ``` ### Subprocess Mode When Docker is unavailable, subprocess mode provides weaker isolation: ```bash # Warn when falling back to subprocess cortex run script.py # Logs warning if Docker unavailable # Force sandbox mode cortex run script.py --sandbox-only # Fails if Docker unavailable ``` ## Audit Logging (Cortex Lens) All security events are logged to the Lens database: ```bash # View recent audit events cortex lens tail # Search audit log cortex lens search "tool:shell" # Export audit log cortex lens export --format json > audit-export.json # Check for policy violations cortex lens search "action:deny" ``` ## Operational Security Checklist - [ ] API keys stored in vault or environment variables, not config files - [ ] Vault passphrase is strong (20+ characters) and stored securely - [ ] Policy rules reviewed and tested - [ ] Server bound to localhost or behind a reverse proxy - [ ] Docker sandbox enabled for code execution - [ ] Lens audit logging enabled and reviewed regularly - [ ] Plugin permissions reviewed before installation - [ ] Data directory permissions restricted (`chmod 700 ~/.cortex`) - [ ] Regular backups of data directory configured - [ ] CortexPrism version kept up to date ## Incident Response If you suspect a security incident: 1. **Isolate**: Stop all CortexPrism processes ```bash cortex daemon stop cortex serve -s ``` 2. **Audit**: Export and review Lens audit log ```bash cortex lens export --format json > incident-$(date +%s).json ``` 3. **Contain**: Review and tighten policy rules 4. **Analyze**: Check vault access logs and plugin activity 5. **Recover**: Restore from clean backup if needed 6. **Report**: Open a [GitHub security issue](https://github.com/CortexPrism/cortex/security) URL: https://cortexprism.io/docs/knowledge-base/security-guidelines --- ### Performance Tuning # Performance Tuning Guide to optimizing CortexPrism performance for different workloads and deployment scenarios. ## LLM Provider Selection Provider choice has the biggest impact on response time: | Provider | Avg. Latency | Best For | |----------|-------------|----------| | Groq | ~500ms | Fast inference, prototyping | | OpenAI GPT-4o mini | ~1s | General purpose, cost-sensitive | | Anthropic Claude Sonnet | ~2s | Code, analysis | | Ollama (local) | ~5-30s | Offline, privacy-sensitive | | DeepSeek | ~1.5s | Code generation, cost-effective | ### Cascade Router Optimize cost and latency with cascading providers: ```json { "router": { "enabled": true, "confidenceThreshold": 0.7, "cascade": [ { "provider": "groq", "model": "llama-3.3-70b-versatile" }, { "provider": "openai", "model": "gpt-4o-mini" }, { "provider": "anthropic", "model": "claude-sonnet-4-20250514" } ] } } ``` The router tries cheaper/faster models first and escalates when confidence is low. ## Memory Performance ### Hybrid Retrieval Memory search uses hybrid FTS5 + vector embedding retrieval: ```json { "memory": { "retrieval": { "ftsWeight": 0.4, "vectorWeight": 0.4, "recencyWeight": 0.2, "limit": 5 } } } ``` - Lower `limit` for faster queries - Adjust `ftsWeight` vs `vectorWeight` based on your data type - Indexed queries are faster — use specific keywords ### Memory Tiers Limit which tiers are searched: ```bash # Search only fast tiers cortex memory search "query" --tiers episodic,semantic # Exclude slow reflection tier cortex memory search "query" --tiers working,episodic,semantic ``` ### Pruning Regularly prune old or low-value memories: ```bash # Auto-prune on startup (config) { "memory": { "pruning": { "enabled": true, "maxEntries": 10000, "retentionDays": 90 } } } # Manual prune cortex memory prune --keep 5000 cortex memory prune --older-than 30d ``` ## Database Performance ### SQLite WAL Mode CortexPrism uses SQLite with WAL (Write-Ahead Logging) mode by default for concurrent read/write performance. ### Vacuum Periodically vacuum databases to reclaim space: ```bash # Vacuum all databases cortex setup --vacuum # Manual vacuum for specific db sqlite3 ~/.cortex/data/cortex.db "VACUUM;" ``` ### Connection Pooling The Prisma client handles connection pooling automatically. For high-throughput deployments: ```bash # Set connection limits export DATABASE_POOL_MIN=2 export DATABASE_POOL_MAX=10 ``` ## Sandbox Performance ### Docker vs Subprocess | Mode | Startup | Execution | Isolation | |------|---------|-----------|-----------| | Docker | ~2s | Fast | Strong | | Subprocess | ~10ms | Fast | Weak | | WASM | ~1ms | Fastest | Strong | For development: use subprocess mode for speed For production: use WASM or Docker for security ### Sandbox Resource Limits ```json { "sandbox": { "timeout": 30, "memory": 256, "maxOutput": 64, "cpuQuota": 0.5 } } ``` - Increase `timeout` for long-running scripts - Increase `memory` for data-heavy operations - Decrease `cpuQuota` to share resources across sessions ## Server Performance ### Concurrent Sessions ```bash # Increase max concurrent sessions cortex serve --max-sessions 50 # Or in config: { "server": { "maxSessions": 50, "sessionTimeout": 3600000 } } ``` ### WebSocket vs REST Use WebSocket for streaming chat (lower latency, fewer connections): ```bash # WebSocket endpoint ws://localhost:3000/api/chat # REST endpoint POST http://localhost:3000/api/chat ``` WebSocket is recommended for interactive sessions; REST for batch processing. ## Profiling Enable performance profiling: ```bash cortex chat --profile ``` Output includes: - LLM call latency per provider - Tool execution time - Memory retrieval time - Total agent loop time ## Benchmarking ```bash # Run built-in benchmarks cortex benchmark chat --rounds 10 cortex benchmark memory --queries 100 cortex benchmark sandbox --iterations 50 # Compare providers cortex benchmark providers --rounds 5 ``` ## Production Tuning Checklist - [ ] Cascade router enabled with fast fallback providers - [ ] Memory pruning configured and scheduled - [ ] Database vacuum scheduled (weekly) - [ ] Sandbox timeout and memory limits tuned for workload - [ ] Server max sessions adjusted for expected load - [ ] Docker sandbox enabled (or WASM for performance) - [ ] Profiling data collected to identify bottlenecks - [ ] Benchmarks run to establish baseline URL: https://cortexprism.io/docs/knowledge-base/performance-tuning ---