Cortex belongs to the same broad family as modern agent harnesses such as Claude Code, Codex, OpenClaw, and other tool-using coding runtimes: systems that turn an LLM from a conversational model into an operator with files, tools, memory, policy, and feedback.
Cortex's bet is that long-running agents need more than a larger prompt and a larger tool list. A harness built for real multi-session work needs a runtime model where attention, memory, permissions, channels, plugins, and side effects are explicit operational objects. Cortex implements that model as an operator-owned runtime: agents should be able to preserve continuity across sessions, coordinate tools, remember responsibly, expose what happened, and let humans govern consequential actions.
The design is grounded in cognitive science and production runtime practice: global workspace theory, working memory, complementary learning systems, metacognition, hierarchical control, event sourcing, durable execution, and explicit trust boundaries. These ideas are treated as engineering constraints, not as decoration.
Mature harnesses have already proven the core interaction pattern: let the model inspect a workspace, call tools, iterate on feedback, and collaborate with the operator. Cortex starts from that baseline and focuses on the runtime problems that appear after the first impressive demo: continuity, governance, memory quality, channel identity, plugin trust, and operational inspection.
Cortex treats the agent as a runtime concern:
- The foreground turn is a limited attention channel, not an unbounded stream.
- Memory is captured, materialized, and stabilized instead of being appended as loose notes.
- Tool effects pass through policy, risk, and permission gates.
- Runtime state is journaled so behavior can be inspected and recovered.
- Plugins and channels are explicit boundaries with declared capabilities.
Cortex treats memory as an active runtime substrate, not a transcript archive. Each turn assembles a request-local working frame from the live conversation, actor identity, policies, tool state, and recalled evidence. That frame is the agent's temporary global workspace: memory may enter it to support continuity, but it does not become an instruction, and it loses to current observation, explicit user direction, and runtime schemas.
Long-term memory has a lifecycle. New candidates can come from explicit user
directives, tool evidence, conversation outcomes, and post-turn extraction.
They are persisted as structured entries with type, kind, owner actor, source
trust, evidence events, claim fields, strength, timestamps, contradictions,
supersession links, validity windows, usage outcomes, and feedback
attribution. A memory advances from Captured to Materialized to
Stabilized only when access, evidence, user confirmation, and observed
usefulness support it. Weak or stale entries decay toward Deprecated; a
recently recalled stabilized memory opens a reconsolidation window so new
evidence can revise the belief instead of merely accumulating around it.
Recall is deliberately multi-signal. Cortex combines lexical relevance, embeddings, recency, reliability status, access frequency, actor scope, and graph proximity. The memory graph stores typed relations such as dependency, preference, causality, ownership, replacement, and temporal order; recall can expand across nearby nodes and score multi-hop context instead of flooding the prompt with all history. The result is closer to controlled retrieval into working memory than to a growing scratchpad.
Metacognition is the supervision loop around that substrate. Cortex watches context pressure, working-memory capacity and decay, repeated tool cycles, duration, fatigue, frame anchoring, confidence, provider and embedding health, memory fragmentation, recall degradation, and tool utility. Those signals are journaled and can drive compression boundaries, strategy hints, exploration hints, skill activation, permission pauses, recovery suggestions, or memory consolidation. The point is not to claim model self-awareness; it is to give the harness enough self-observation to notice when the agent is losing traction, over-trusting stale context, or turning uncertainty into side effects.
Cortex supports bounded self-evolution: the runtime can update what should change with experience without granting the model arbitrary authority over the system. Post-turn analysis looks for weighted signals such as user corrections, explicit preferences, new working domains, first-session bootstrap evidence, tool-intensive turns, and long inputs. When those signals justify adaptation, Cortex can update prompt layers through an evidence-scoped self-update pass.
That path is intentionally constrained. The delivery draft is not treated as prompt content, updates are validated against layer boundaries, bootstrap and incremental evolution use different rules, and runtime policy remains outside prompt self-update. Memory evolution follows the same discipline: entries are split, consolidated, stabilized, deprecated, and graph-reorganized through auditable events instead of silent prompt drift.
Skill evolution is governed in the same style. Repeated tool-call patterns can
materialize new instance-level SKILL.md files, but Cortex does not silently
overwrite an existing skill. Existing skills carry utility and health state
(strong, healthy, needs_review, quarantined, or deprecated) derived
from execution outcomes. Weak skills lose ranking, quarantined and deprecated
skills stop being automatically activated, and better workflows are recorded as
evolution proposals that relate a candidate skill to a target skill. The
operator can inspect proposals with /skill proposals and accept or reject
them; acceptance deprecates the target and marks the candidate healthy without
erasing the old source. The result is adaptation that is observable, auditable,
and reversible enough for an operator-owned harness.
- Interactive CLI, single-prompt pipe mode, daemon mode, ACP bridge, outbound ACP agent clients, and MCP server mode.
- systemd user or system service deployment with multiple named instances.
- LLM and embedding provider configuration, including custom provider endpoints.
- Permission modes for strict, balanced, and open tool confirmation behavior.
- Policy linting and simulation for tool effects.
- Plugin installation, review, conformance testing, signing, packing, and runtime enablement.
- Skill health tracking, automatic candidate discovery, and operator-governed skill evolution proposals.
- Outbound ACP client connections that let Cortex add, connect to, remove, and
talk with external agents through the
acptool. - Messaging channel pairing and policy for supported transports, including Telegram, QQ, WhatsApp, and QClaw.
- Managed Node.js and browser integration helpers for MCP-based workflows.
- Local dashboard assets served by the daemon without remote CDN dependencies.
Channels are daemon-owned transports. They route external messages into the same actor, session, memory, permission, and policy model used by the CLI, socket, and HTTP/RPC surfaces.
Supported channels:
- Telegram: Bot API transport for private or group conversations. It uses
CORTEX_TELEGRAM_TOKENand supports pairing, approval, subscriptions, and channel policy modes. - QQ: QQ Bot transport using
CORTEX_QQ_APP_IDandCORTEX_QQ_APP_SECRET, with optional markdown rendering controls. - WhatsApp: WhatsApp transport for Cloud/API-style deployments using access token configuration and webhook verification material.
- QClaw: Weixin iLink / ClawBot adapter. It can use
CORTEX_QCLAW_TOKENdirectly or runcortex channel qclaw loginfor QR login and credential persistence.
Each channel is configured per Cortex instance:
cortex channel telegram
cortex channel qq
cortex channel whatsapp
cortex channel qclawPairing, allow/deny lists, subscriptions, and actor aliases are managed through
cortex channel ... and cortex actor .... See the
Usage Guide for complete channel setup.
The Cortex Dev Plugin is the recommended development capability pack for Cortex. It adds trusted native tree-sitter code intelligence for Rust, Python, TypeScript, and TSX, plus workflow skills for exploration, implementation, review, debugging, refactoring, testing, release, incident response, security review, and disciplined commits. Install it from signed releases when Cortex is expected to work deeply inside software repositories.
Quick start:
curl -fsSL https://raw.githubusercontent.com/by-scott/cortex/main/scripts/install.sh | bash -s -- --permission-level balanced
cortex doctor
cortexFor a provider-backed first install:
export CORTEX_PROVIDER=openai
export CORTEX_MODEL=gpt-4.1
export CORTEX_API_KEY=sk-...
curl -fsSL https://raw.githubusercontent.com/by-scott/cortex/main/scripts/install.sh | bash -s -- --permission-level balancedAfter the daemon is installed, start the interactive CLI with cortex and
complete the first-run initialization in conversation. Use cortex "question"
for a one-shot prompt.
Cortex is split into small Rust crates with clear ownership:
crates/cortex-app: CLI, deployment commands, service management, and operator workflows.crates/cortex-runtime: daemon, HTTP/RPC, channels, plugins, dashboard serving, and runtime orchestration.crates/cortex-turn: turn orchestration, LLM calls, tools, skills, risk, and memory workflows.crates/cortex-kernel: config, persistence, journal, policy, prompt, and storage primitives.crates/cortex-types: shared wire, config, event, memory, plugin, and policy contracts.crates/cortex-sdk: public Rust SDK for trusted native plugins.static: embedded dashboard assets.
Cortex assumes that model output, tool output, plugin data, channel messages, network content, memory content, and dashboard API responses are untrusted until they cross an explicit boundary. Security-sensitive behavior is designed around fail-closed permission checks, declared plugin capabilities, policy simulation, audit-friendly events, and embedded dashboard assets.
Trusted native plugins run in process and must be reviewed, tested, signed, and packed before distribution. Process-isolated plugins use child-process JSON tools with manifest-declared command, timeout, environment, and filesystem rules.
Docker is the canonical development environment:
./scripts/build.shThe build gate runs formatting, strict Clippy, workspace build, docs with warnings denied, and repository hygiene checks. Cargo commands use locked dependencies, and the Docker base image pins the Rust toolchain.
Cortex is licensed under the MIT License.