Cortex

장기 실행 인간-에이전트 작업을 위한 파일 기반 운영 환경.

Cortex는 CLI 에이전트를 프로젝트 조정, 지속 가능한 컨텍스트(context), 전문 에이전트, 그리고 세션 간 실제 기계들을 연결하는 지휘자 채팅(conductor chat)으로 변환합니다. 이 시스템의 진실 공급원(source of truth)은 사용자가 소유한 투명한 파일들로 구성된 작업 공간입니다: 태스크(tasks), 로그북(logbooks), 지침(instructions), 받은 편지함(inboxes), 프로젝트 노트(project notes), 그리고 운영 상태(operational state).

Quickstart · How it works ·
Multi-server setup ·
Who it is for · Examples

장기 실행 작업에 지속 가능한 공간을 제공합니다.

연구 및 엔지니어링 작업은 몇 달 동안 지속될 수 있지만, AI 대화는 에피소드적입니다. 결정들은 채팅 곳곳으로 흩어지고, 실험들은 원래의 컨텍스트를 초과하며, 에이전트들은 이전 작업을 반복하고, 중요한 지식은 순수한 대화 기록 속에 사라집니다.

Cortex는 이러한 컨텍스트를 에이전트가 선택적으로 다시 로드할 수 있는 구조화된 작업 상태로 외부화합니다. 사용자는 일반 채팅처럼 지휘자를 사용합니다: 질문을 하거나, 아이디어를 논의하거나, 자연어로 작업을 요청할 수 있습니다. 이 지휘자는 관련 프로젝트 파일, 태스크, 결과물, 그리고 지속 가능한 메모리들을 정리하고, 다른 에이전트가 유용할 때 제한된 작업(bounded work)을 위임할 수 있습니다 (현재는 사용자 요청 시에만 가능).

Cortex는 개인이 에이전트를 사용하여 자신의 진행 중인 작업을 조직하고 운영하는 것을 돕습니다.

왜 Cortex를 사용해야 하는가

투명하고 유연한 에이전트 역할: 에이전트는 공유 규칙부터 역할 정의, 전문 지침에 이르기까지 계층화된, 사람이 읽을 수 있는 명령어 파일(instruction files)을 통해 프로그래밍됩니다. 사용자, 환경, 프로젝트 컨텍스트가 여기에 중첩됩니다. 이들의 동작은 일반 텍스트 파일을 편집하여 검사하고, 조정하며, 버전을 관리할 수 있습니다.
프로젝트 중심의 연속성: 지속 가능한 객체는 에이전트나 대화 자체가 아니라 프로젝트입니다. 결정, 작업, 실험, 참고 자료, 결과물은 개별 채팅을 넘어서 생존합니다.
인간과 소통하는 단일 지휘자(conductor): Cortex가 유용해지기 전에 복잡한 에이전트 그래프를 설계할 필요가 없습니다. 하나의 지휘자 채팅으로 시작하고, 작업에 전문 에이전트의 도움이 필요할 때만 추가하면 됩니다. 여러 개의 동시 지휘자 세션이 가능하며, 공유되는 영구 컨텍스트(shared persistent context)를 사용하여 병렬 작업을 수행할 수 있습니다.
진실의 원천으로서의 파일: 일반 텍스트 파일은 시스템을 검사 가능하고(inspectable), 버전 관리 가능하며(versionable), 스크립팅이 가능하고(scriptable), 백업에 용이하며, 이식성이 높게 유지합니다.
명확한 컨텍스트 경계: 프레임워크, 사용자, 환경, 프로젝트의 사실 정보는 각각 별도의 공간을 가집니다. 개인화된 내용은 비공개로 유지되는 반면, 재사용 가능한 프레임워크 코드는 공개 상태를 유지할 수 있습니다.
재사용 가능한 지식: 작업 목록(task lists)은 계획되고 활발한 작업을 추적하고; 로그북(logbooks)은 완료된 단계, 결정 및 결과를 보존하며; 치트 시트(cheat sheets)는 안정적인 사실을 기록하고; 단축키 파일(shortcut files)은 입증된 절차를 유지하며; 명령어 파일(instruction files)은 지속 가능한 규칙과 선호도를 담고 있습니다.
운영 범위: 작업자(workers)와 노드(nodes)는 제한된 구현, 연구, 모니터링, 메시징, 백업 및 다중 머신 작업을 처리할 수 있습니다.
자연어 적응: 지휘자에게 반복되는 선호도, 누락된 규칙 또는 워크플로우 개선 사항에 대해 알려주면, 그것은 해당 내용을 소유한 지속 가능한 표면(durable surface)에 기록할 수 있습니다.
제공업체 유연성: Cortex는 역량 있는 제공업체 CLI와 그 네이티브 세션을 사용합니다. 작업 공간 모델의 대부분은 특정 LLM 공급업체에 종속되지 않습니다.
커스터마이징 가능성 (Customizability): Cortex는 프레임워크에 대해 모든 것을 아는 Conductor 에이전트를 사용하여 구현되었습니다. 만약 작동 방식, 커스터마이즈 방법, 확장 또는 버그 수정 방법을 알고 싶다면, Conductor에게 이야기하기만 하면 됩니다.

Cortex의 작동 방식 (How Cortex Works)

flowchart LR
    H[Human] --> C[Conductor]
    C <--> W[(File-native workspace)]
...

Conductor가 주요 진입점입니다. 일반적인 요청에 대해 다음과 같은 작업을 수행합니다:

관련 프로젝트, 사용자 선호도 및 환경 사실을 식별합니다.
빈 대화에서 시작하는 대신 기존 작업(tasks), 결정(decisions) 및 아티팩트(artifacts)를 검사합니다.
직접 답변하거나 적절한 에이전트에게 제한된 작업을 위임합니다 (명시적 요청 시에만).
결과를 검증하고 생존해야 할 정보만을 기록합니다.
사용자에게 간결한 결과(result)를 반환합니다.

Cortex는 Conductor만으로도 유용하게 유지됩니다. 더 큰 규모의 시스템은 선택 사항입니다: 읽기 전용 노드는 검사하거나 계산할 수 있고, 워커(workers)는 범위가 지정된 변경을 수행할 수 있으며, Watch 에이전트는 방치된 작업이나 메시징 채널을 모니터링할 수 있습니다. 프레임워크 워커는 감사 및 프레임워크 자체를 발전시키는 데 사용할 수 있습니다.

작업 공간(workspace)은 네 가지 종류의 컨텍스트를 분리합니다:

프레임워크 (Framework): 재사용 가능한 스크립트, 역할 정의, 기본값(defaults), 문서
사용자 (User): 선호도, 알림, 제공업체 사용 정보
환경 (Environment): 호스트 이름(hostnames), 경로(paths), 원격지(remotes), 백업 루트, 인프라
프로젝트 (Project): 작업, 로그북(logbooks), 참조(references), 규칙, 실험, 결과

이러한 분리는 라이브 사설 체크아웃(live private checkout)이 공개 프레임워크 릴리스에 배포 세부 정보가 유출되지 않으면서 진화할 수 있게 합니다.

여러 개의 Conductor 창을 동시에 열 수 있습니다. 각 창은 agents/conductor/sessions/ 아래에 세션별 실행 시간 메타데이터(session-local runtime metadata)를 가지고 있는 반면, 모든 창은 동일한 프로젝트 상태와 Conductor 받은 편지함(inbox)을 공유합니다. 한 번에 하나의 창만 받은 편지함 분류 또는 에이전트 디스패치(agent dispatch) 작업을 수행해야 합니다.

권장되는 다중 서버 설정

멀티 서버 환경을 구축하려면 Cortex 폴더를 중앙 서버에 두고, Cortex를 사용하려는 모든 노드에서 공유 스토리지로 마운트해야 합니다. 각 노드에서는 이 공유 폴더로 로컬 심볼릭 링크(symlink)를 생성하는 것이 좋으며, 이상적으로는 동일한 경로에 두어야 합니다. 이렇게 하면 모든 컨덕터와 에이전트가 동일한 프로젝트, 지침, 받은 편지함 및 영구적인 컨텍스트에 접근할 수 있습니다.

Cortex의 활용 대상

Cortex는 여러 프로젝트, 세션, 실험 또는 머신에 걸쳐 작업하는 기술 전문가나 소규모 연구/엔지니어링 그룹을 위해 설계되었습니다. 특히 에이전트가 실제 업무에 참여하면서도 이해하기 쉽고 영구적인 기록을 남기고자 할 때 매우 유용합니다.

Cortex는 의도적으로 단일 운영자(single-operator) 프레임워크이며, 다중 사용자 시스템은 아닙니다. users/ 폴더는 계정을 제공하거나 공유 사용자 조정 기능을 제공하기보다는 개인의 선호 설정과 알림을 깔끔하게 분리하여 유지합니다. 따라서 주된 목표가 고객 대면 에이전트 애플리케이션 구축, 프로덕션 워크플로우 그래프 정의, 엔터프라이즈 호스팅 제어 평면(control plane) 확보 또는 로컬 작업 공간을 유지하지 않고 턴키 채팅 비서 사용인 경우에는 적절한 계층이 아닐 수 있습니다.

빠른 시작

요구 사항

최소 사양:

Linux 또는 macOS
bash
git
Python 3
Cortex가 실행할 수 있는 프로바이더 CLI 하나: claude 또는 codex (다른 프로바이더 값은 허용되지 않음)
워커를 실행하는 경우 Linux의 bwrap (bubblewrap): scripts/start_agent.sh는 사용 가능한 샌드박스 백엔드가 없으면 워커 시작을 거부합니다. macOS에서는 bwrap이 없을 때 auto 백엔드가 macos-direct로 폴백(fallback)합니다 (CORTEX_WORKER_SANDBOX_BACKEND, roles/sandbox.sh의 resolver).

일반적으로 유용한 것:

장기 실행 에이전트를 위한 screen (기본값) 또는 tmux
원격 노드 설정을 위한 ssh
메시징 인그레스(ingress)를 원하는 경우 선택적 Signal / Telegram 도구(scripts/signal_inbox_daemon.sh, scripts/telegram_inbox_daemon.sh)

권장 첫 실행

저장소(repo)를 클론한 후, 컨덕터를 시작합니다:

첫 실행 시, Cortex는 실제 체크아웃에 필요한 로컬 디렉터리들을 생성합니다.

포함되는 항목:

user.instruct 및 environment.instruct
users/<사용자>/...
environments/<환경>/...
agents/conductor/...
inbox, broadcast, 그리고 log 디렉터리들

이 과정에서 모든 선택적 서브시스템을 미리 구성할 필요는 없습니다. 새로 클론한 상태에서도 Signal, Telegram, watch, 백업 또는 public-sync 설정 없이 깔끔하게 시작할 수 있습니다.

Cortex는 첫 채팅 시 선택적 설정을 진행하기 전에 프로젝트에 대해 질문합니다. 추가적인 후속 질문은 사용자가 활성화하려는 기능(공유 멀티 머신 운영, 백업, Signal/Telegram 연동, 공개 내보내기 또는 상시 워커)에 대해서만 합니다. 사적인 environments/<환경>/settings.env 파일은 conductor/agent 제공자 기본값, 백업 보존 기간, 릴레이 호스트 및 공개 내보내기 원격지 등 선택적 런타임 선택 사항을 저장하는 영구 홈입니다. 자격 증명(credentials)은 agents/conductor/secrets/에 보관하고, 절대로 해당 settings 파일에 넣지 마십시오.

메시징 수신(Messaging ingress)은 데몬으로 실행됩니다: bash scripts/signal_inbox_daemon.sh start|stop|restart|status|foreground와 bash scripts/telegram_inbox_daemon.sh start|stop|restart|status|foreground는 수신된 메시지를 inboxes/signal과 inboxes/telegram에 기록합니다. 이들은 agents/conductor/secrets/signal.env 및 agents/conductor/secrets/telegram.env (각각 CORTEX_DEFAULT_SIGNAL_SECRETS_FILE, CORTEX_DEFAULT_TELEGRAM_SECRETS_FILE)에서 설정을 가져옵니다. 외부로 나가는 Telegram 메시지는 scripts/telegram_send.py를 거치며, 이 스크립트는 환경 변수로부터 TELEGRAM_BOT_TOKEN과 TELEGRAM_USER_CHAT_ID를 읽어옵니다.

안전 기본값은 해당 채팅 중에 공개됩니다. 아무것도 무단으로 시작되지 않으며, 지휘자(conductor)와 배포된 이름 지정 워커는 기본적으로 Codex를 사용하고, 노드는 Claude를 기본으로 합니다. CORTEX_AGENT_PROVIDER가 노드/워커의 기본값을 덮어쓰며, 명시적인 실행 플래그가 우선합니다. 대화형 지휘자 권한은 재정의되지 않는 한 제공업체 구성을 유지합니다. 워커는 런처 파일 시스템 샌드박스 내에서 제공업체 승인 우회 기능을 사용하지만, macOS의 macos-direct에는 해당 파일 시스템 격리가 없습니다. 초기 백업 매니페스트는 Cortex 작업 트리만 포함합니다. 공개 릴리스는 항상 scripts/sync_public.sh를 통한 정리된 내보내기이며, 라이브 운영 브랜치를 푸시하는 경우는 절대 아닙니다.

Codex는 지속적으로 개발되고 있으며 에이전트(특히 지휘자 에이전트)의 동작은 쉽게 사용자 정의할 수 있습니다. 이 프레임워크는 지휘자 에이전트를 사용하여 구축되었으며, 지휘자에게 프롬프팅함으로써 추가로 수정하고 확장할 수 있습니다. Cortex 프레임워크에 대한 작업은 자동으로 자체 프로젝트 폴더를 얻게 되며 다른 모든 프로젝트와 마찬가지로 처리됩니다(예: 로그 파일 및 바로 가기는 지휘자에 의해 자동으로 유지됩니다).

필요한 로컬 상태가 누락되었고 대화형 셸에 있다면, bash cortex.sh는 동일한 부트스트랩 흐름을 자동으로 제공합니다. 이 동작을 억제하려면 --no-init을 사용하거나, 로컬 사용자/환경/지휘자 상태를 생성하고 채팅 시작 없이 종료하려면 --init [--user NAME] [--env NAME]을 사용하십시오. --startup-checks는 기본 최소 시작 루틴을 전체 루틴(로그/작업 검토, 받은 편지함 비우기, 워커 활성 상태 확인, 다음 단계 제안)으로 대체합니다.

체크아웃에 projects/ 아래에 적어도 하나의 프로젝트가 있을 때까지, 지휘자는 시작 시 첫 번째 프로젝트 설정을 안내하기 위해 setup.instruct를 따릅니다.

다음과 같은 일반적인 요청으로 시작할 수 있습니다:

제 새로운 실험을 위한 프로젝트를 만들고 아이디어를 계획으로 바꾸는 것을 도와주세요.

더미 데이터셋으로 실험을 진행하기 전에, 이제 실제 데이터셋을 연결하고 이전에 설계했던 세 가지 다른 아키텍처로 세 번의 실행을 시작하세요. 서버에서 찾을 수 있는 모든 무료 GPU를 사용해도 됩니다.

우리가 이 프로젝트를 작업했을 때 마지막에 결론지은 것이 무엇이었죠?

제 실험이 그동안 끝났어야 하는데, 결과 좀 보여줄 수 있나요?

현재 구현을 검사하고, 변경 사항을 적용한 다음, 관련 테스트를 실행하고, 지속 가능한 결과를 기록하세요.

제공자 및 세션 옵션

기본적으로 cortex.sh는 Codex와 함께 새로운 컨덕터(conductor) 세션을 시작합니다. Codex 런처는 항상 인라인으로 실행되므로 런처 뷰가 일반 터미널 스크롤백 상태를 유지합니다. --no-alt-screen은 해당 동작에 대한 Codex 전용 명시적 호환성 플래그이며, --provider claude와 함께 사용하면 거부됩니다. 제공자를 명시적으로 재정의할 수 있습니다:

bash cortex.sh --provider codex
bash cortex.sh --provider claude
bash cortex.sh --label paper

특정 모델을 선택하려면, 짧은 버전 별칭과 함께 --model을 전달하세요. 허용되는 별칭은 다음과 같습니다:

SonyCSLParis/cortex: 장기 실행 인간-에이전트 작업을 위한 파일 기반 운영 환경

요약

핵심 포인트