CORTEX
cortex-desc.png
<p align="center">CORTEX는 Large Language Models (LLMs)의 효율적인 통합 및 오케스트레이션을 위해 설계된, Go로 구축된 고성능 AI Agent 프레임워크입니다.</p>
<p align="center">
<img alt="GitHub commit activity" src="https://img.shields.io/github/commit-activity/m/xichan96/cortex"/>
<img alt="Github Last Commit" src="https://img.shields.io/github/last-commit/xichan96/cortex"/>
</p>
<p align="center">
<a href="#overview">개요</a>
· <a href="#features">기능</a>
· <a href="#quick-start">빠른 시작</a>
· <a href="#core-components">핵심 구성 요소</a>
· <a href="#dino">Dino</a>
· <a href="#tools">도구(Tools)</a>
· <a href="#agent-skills">Agent 스킬</a>
· <a href="#memory-system">메모리 시스템</a>
· <a href="#examples">예제</a>
· <a href="#triggers">트리거</a>
· <a href="#license">라이선스</a>
</p>
<p align="center">
영어 | <a href="README-CN.md">简体中文</a>
</p>
개요 (Overview)
가벼운 프레임워크의 단순성과 Go의 견고함을 결합하여, CORTEX는 주요 LLMs와의 원활한 통합을 가능하게 합니다. 이는 복잡한 도구 실행 및 추론이 가능한 AI 에이전트를 구축하기 위한 포괄적인 툴킷을 제공합니다.
프로덕션 환경을 위해 설계된 CORTEX는 신뢰성(reliability), 구성 가능성(configurability), 그리고 자원 효율성을 최우선으로 합니다. 이는 개발자들이 Go 생태계 고유의 성능 및 안전성 보장을 갖춘 차세대 AI 애플리케이션을 구축할 수 있도록 힘을 실어줍니다.
설계 철학: CORTEX는 간소화된 통합과 낮은 자원 사용량에 중점을 둔 미니멀리스트 접근 방식을 채택합니다. 이는 무거운 의존성과 복잡한 오케스트레이션 오버헤드를 제거하여, 완전한 워크플로우 자동화 플랫폼의 비대함 없이 강력한 Agent 기능이 필요한 개발자에게 이상적인 선택지입니다.
agent 대 Dino: agent (github.com/xichan96/cortex/agent)는 기본(baseline) 구성입니다. 모델이 복잡한 다중 턴 채팅을 자율적으로 결정하고 도구를 연결할 필요가 없는 경우, engine + llm과 선택적 도구들을 사용하여 프로젝트에 직접 통합하십시오 (Dino 불필요). 원샷 보고서 생성, 요약, 추출, 분류, 구조화된 출력 등을 수행할 수 있습니다. dino (github.com/xichan96/cortex/dino)는 지능형 에이전트(Intelligent Agents) (어시스턴트, IDE 에이전트, 봇 등)를 위한 고급 스택입니다: 다중 턴 대화, 자동 도구 결정 및 다단계 실행, 그리고 세션 격리(session isolation), 예산 책정(budgets), 승인(approvals), 관측 가능성(observability) 기능을 제공합니다.
주요 기능 (Features)
-
지능형 에이전트 엔진 (Intelligent Agent Engine): 고급 추론(reasoning) 및 도구 호출(tool-calling) 기능을 갖춘 에이전트를 구축하기 위한 강력한 핵심 구조.
-
광범위한 LLM 지원 (Broad LLM Support): OpenAI, DeepSeek, Volce 및 사용자 지정 제공업체(custom providers)와의 원활한 통합.
-
멀티모달 네이티브 (Multi-Modal Native): 텍스트, 이미지 및 기타 미디어 형식을 손쉽게 처리하고 생성.
-
동적 스킬 (Dynamic Skills): 지연 로딩(lazy loading)을 사용하는 파일 시스템 기반의 스킬. YAML 프론트매터는 paths, when_to_use, 및 allowed_tools를 지원하며, 로더에서 경로-글로브 필터링 (doublestar)과 선택적 심볼릭 링크 해결/실제 경로 중복 제거(real-path dedupe) 기능을 제공.
-
확장 가능한 도구 모음 (Extensible Tooling): agent/tools/builtin은 fs, search, shell/백그라운드 작업(background jobs), net/web, Docker, email, math, 및 mcp_client를 포괄하며, 필요에 따라 사용자 지정 types.Tool을 등록할 수 있음.
-
실시간 스트리밍 (Real-Time Streaming): 응답 스트리밍에 대한 완벽한 지원을 제공하여 상호 작용적이고 낮은 지연 시간의 사용자 경험을 가능하게 함.
-
하이브리드 메모리 아키텍처 (Hybrid Memory Architecture): 전체 기록(Full history)와 순환 요약(rolling summaries)을 제공하며, 압축 작업이 중복되지 않도록 비동기 압축(asynchronous compression) (뮤텍스 직렬화(mutex-serialized), CompactAfterTurns를 통한 턴 인식) 기능을 갖춤. 프롬프트 조립(Prompt assembly)은 대략적인 토큰 예산(MaxBudgetTokens, RemainPromptTokens)까지 최근 채팅 내용을 자를 수 있음. 제공업체는 더 스마트한 게이팅을 위해 저렴한 StoredMessageCount를 노출할 수 있음. LangChain, MongoDB, Redis, MySQL, SQLite와 호환됨.
-
세밀한 설정 구성(Granular Configuration): 에이전트의 동작 및 성능을 미세 조정할 수 있는 광범위한 옵션을 제공합니다.
-
병렬 실행(Parallel Execution): 대기 시간을 최소화하기 위해 여러 도구 호출을 효율적으로 동시에 실행합니다.
-
프로덕션급 신뢰성(Production-Grade Reliability): 안정성을 위해 구축된 포괄적인 오류 처리 및 재시도 메커니즘을 갖추고 있습니다.
-
Dino 프로덕션 오케스트레이션: 다중 세션 격리, 실시간 이벤트 구독, 토큰/도구/시간 예산 설정, 루프 감지, 위험한 도구 승인, 우선순위 작업 큐, 플래너 모드 및 서브에이전트 기능; 세션 스냅샷 저장/복원(메시지 창, 사용량, 메모리 턴 카운터); YAML 메모리 튜닝(max_budget_tokens, compact_after_turns) 및 선택적 부모 메모리로의 서브에이전트 재연결; 선별된 빌트인 기능 외에도 MCP 및 스킬 통합 기능을 제공합니다.
아키텍처 개요 (Architecture Overview)
Cortex는 다음의 주요 구성 요소를 갖춘 모듈식 아키텍처를 따릅니다:
참고: agent 패키지는 LangChain을 기반으로 구축되었으며, 강력한 LLM 상호 작용 및 도구 호출 기능을 활용하여 지능형 에이전트 시스템을 구축합니다.
cortex/
├── agent/ # 핵심 에이전트 기능
│ ├── engine/ # 에이전트 엔진 구현
...
빠른 시작 (Quick Start)
설치 (Installation)
go get github.com/xichan96/cortex
최소 예제 (Minimal Example)
단 몇 초 만에 날씨를 확인하는 AI 에이전트를 생성해 보세요:
package main
import (
...
서비스 실행 (Run the Service)
Cortex는 즉시 배포 가능한 HTTP 서버와 함께 제공됩니다:
기본 엔드포인트(포트: 5678):
POST /chat: 표준 채팅
POST /chat/stream: 스트리밍 채팅 (SSE)
ANY /mcp: MCP 프로토콜 엔드포인트
핵심 구성 요소 (Core Components)
agent 패키지 (기본형, baseline)
Dino가 없을 때, agent는 전체 기본 기능을 제공합니다. 이는 사용자가 요청 수명 주기(request lifecycle)를 직접 소유하는 단발성 또는 얕은 호출(one-shot or shallow calls)을 위한 LLM, 엔진, 도구 및 메모리입니다. 모델이 반복적으로 도구를 선택하는 장기 실행 루프가 아닙니다. 아래의 LLM 스니펫도 해당 경로의 일부입니다.
LLM 통합 (LLM Integration)
주요 LLM 제공업체에 대한 통합 인터페이스:
llmProvider, _ := llm.OpenAIClient("sk-...", "gpt-4o")
...
Dino
<p align="center"><img src="https://raw.githubusercontent.com/xichan96/cortex/HEAD/docs/images/dino.png" alt="dino" width="120" /></p>
Dino는 지능형 에이전트 (intelligent agent) 워크로드: 다중 턴 대화(multi-turn dialogue), 자동 도구 선택 및 체인 실행(automatic tool choice and chained execution), 장기 실행(long-lived runs)을 목표로 합니다. 이는 세션 수명 주기(session lifecycle), 관찰 가능성(observability), 가드레일(guardrails)은 소유하면서, 실행에는 agent를 재사용합니다.
역할 분리 (Role split)
agent: 기본 통합(Baseline integration); 단일 요청/배치 작업(single-request/batch jobs), 일회성 보고서 스타일 작업(one-shot report-style tasks), 간단한 API; LLM 제공업체, 엔진, 스킬(skills), 메모리 제공업체, 훅(hooks), 내장 기능(builtins).
dino: 지능형 에이전트 스택 (Intelligent-agent stack); 다중 턴 처리 및 자동 도구 선택/실행 루프; NewDinoFactory / NewClient / Session, 이벤트 버스 (bus), DefinedTool 및 도구 콜백(tool callbacks), 도구별 및 전역 타임아웃, 예산(budgets), 루프 감지(loop detection), 허용/거부/승인 목록(allow/deny/approval lists), SQLite 메모리, 서브 에이전트 및 관리자(subagents and manager), 선택적 queue 배치 처리, 그리고 플래너 모드(planner mode).
세션 및 관찰 가능성 (Sessions and observability)
-
세션별 격리된 컨텍스트; Send, SendAndWait 등으로 턴을 구동합니다.
-
팩토리 옵션은 SSE/WebSocket 브릿지를 위한 스트림 이벤트 싱크(stream event sink)를 연결할 수 있습니다.
Config.Tools: Allowed, Denied, ApprovalRequired; 동적 제한을 위한 ToolTimeouts와 ToolTimeoutCalculator가 제공됩니다.
defined_tool: 인간 개입형(human-in-the-loop) 위험 작업에 대한 DefinedTool, ToolContext, 승인 저장소(approval storage)를 제공합니다.
- 내장 기능은 파일 읽기/쓰기/편집,
glob/grep, bash, list_directory 등을 다루며; cfg.Skills를 통해 MCP 및 파일 시스템 스킬을 연결할 수 있습니다.
리소스 및 안정성 (Resources and stability)
- 예산(Budget): 토큰, 도구 호출 및 벽 시간(wall time)을 제한합니다.
- 메모리 조정(Memory tuning) (YAML / factory):
memory.max_budget_tokens, memory.compact_after_turns; 서브 에이전트 기록 제한(subagent history cap) (기본값 48); 부모 세션에 잘린 작업/출력을 기록하면서 작업을 위임하기 위한 선택적 replay_to_parent_memory.
- 세션 스냅샷(Session snapshots): 내구성 있는 세션을 위해 창별 메시지, 누적 사용량 및 엔진 메모리-턴 카운터를 저장하고 복원합니다.
- 루프 감지(Loop detection): 무한 루프를 방지하기 위한 의미론적 유사성 및 반복 횟수 계산.
- 플래너 모드(Planner mode): 신뢰할 수 있는 경우 자동 승인 기능이 포함된 선택적 계획 후 실행 흐름(plan-then-execute flow).
최소 사용법
go get github.com/xichan96/cortex/dino
import (
"context"
"fmt"
...
)
전체 옵션, 큐 API, 서브 에이전트 및 이벤트 유형: dino/README.md. 실행 가능한 샘플: examples/dino.
내장 기능은 패키지별로 agent/tools/builtin/에 존재하며, 엔진에 types.Tool 인스턴스를 등록하여 활성화할 수 있습니다 (기본값은 에이전트 설정에 따라 다릅니다).
| Package | Tool names |
|---|
fs/ | read_file, write_file, edit_file, file |
| ... | |
기능을 확장하려면 types.Tool 인터페이스를 구현합니다:
type MyTool struct{}
func (t *MyTool) Name() string { return "my_tool" }
...
에이전트 스킬(Agent Skills)
Cortex는 코드를 재컴파일할 필요 없이 에이전트에게 새로운 기능을 가르칠 수 있는 독특한 **파일 시스템 기반 스킬 시스템(filesystem-based skill system)**을 구현합니다.
작동 방식
- 정의(Define): 디렉터리(예:
./skills/my-skill/SKILL.md)에 SKILL.md 파일을 생성합니다.
- 설명(Describe): 마크다운을 사용하여 작업을 설명하고 실행 가능한 예제(예:
curl 명령어, SQL 쿼리)를 제공합니다. 선택적 YAML 프론트매터는 name, description, paths (스킬이 적용되는 globs), when_to_use, allowed_tools 등을 설정할 수 있습니다. 활성 경로 필터링(active-path filtering)은 일치하는 스킬만 시스템 프롬프트에 병합합니다.
- 탐색(Discover): Cortex는 스킬 디렉터리를 스캔하고(선택적 심볼릭 링크 해상도 및 실제 경로별 중복 제거) 적용 가능한 스킬을 주입합니다.
- 실행(Execute): 에이전트가 작업을 수행해야 할 때, 사용자의
SKILL.md에 있는 지침을 따릅니다.
예시 스킬 (skills/weather/SKILL.md)
---
name: weather
description: 명령줄 도구를 사용하여 현재 날씨를 가져옵니다.
...
```bash
curl -s "wttr.in/New+York?format=3"
이러한 접근 방식은 모든 CLI(Command Line Interface) 도구, API 또는 스크립트를 일급 에이전트 기능으로 활용할 수 있게 합니다.
작업 예약 시스템 (Task Scheduling System)
Cortex는 강력한 내장 작업 예약 시스템(xcron)을 특징으로 하여, 에이전트가 예약된 작업을 자율적으로 관리할 수 있도록 합니다. 이는 에이전트가 즉각적인 요청뿐만 아니라 주기적인 작업이나 지연된 작업도 처리할 수 있게 권한을 부여합니다.
주요 기능 (Key Features)
- 유연한 예약 모드(Flexible Scheduling Modes):
oneshot: 지연 후 한 번 실행됩니다(예: "10분 후에 물 마시라고 상기시켜 줘").
periodic: 정기적인 간격으로 실행됩니다(예: "2시간마다 서버 상태를 확인해 줘").
cron: Cron 표현식을 사용한 정확한 타이밍 설정이 가능합니다(예: "매일 아침 8시에 일일 보고서를 보내 줘").
- 영속성(Persistence): 작업은 영속화되어 서비스 재시작 후에도 유지됩니다.
- 에이전트 주도형(Agent-Driven): 에이전트는 내장 도구(
schedule_job, list_jobs, delete_job)를 사용하여 작업을 자율적으로 생성, 쿼리 및 관리할 수 있습니다.
예시 시나리오 (Example Scenario)
사용자: "어제 Hacker News의 주요 기사들을 매일 아침 9시에 요약해 줘."
에이전트는 자동으로 schedule_job 도구를 호출합니다:
{
"name": "hn_daily_summary",
"type": "cron",
...
}
메모리 시스템 (Memory System)
Cortex는 장시간 대화를 위해 설계된 고급 **하이브리드 메모리 아키텍처(Hybrid Memory Architecture)**를 특징으로 합니다.
주요 기능 (Key Features)
- Raw History(원시 기록): 완전한 감사 가능성(auditability)을 위해 모든 상호작용을 보존합니다 (검색은 윈도우 방식이며, 전체 저장소는 백엔드에 따라 다릅니다).
- Rolling Summary(롤링 요약): 과거 대화의 간결한 요약을 비동기적으로 생성합니다. 압축(compaction)은 턴 수(
CompactAfterTurns)와 선택적 저장된 메시지 수를 통해 제어할 수 있습니다.
- Smart Retrieval(스마트 검색): 요약과 최근 메시지를 기반으로 프롬프트를 구성합니다. LLM 호출 전에 최근 채팅 기록을 대략적인 토큰 예산 내로 자를 수 있습니다 (
MaxBudgetTokens, RemainPromptTokens, agent/types의 휴리스틱 토큰 추정치).
- Async Processing(비동기 처리): 요약 및 압축은 패닉 복구(panic recovery)와 잠금(locking) 기능을 갖추고 백그라운드에서 실행되므로 사용자 턴이 응답성을 유지합니다.
저장소 백엔드 (Storage Backends)
단 한 줄의 설정으로 스토리지를 전환할 수 있습니다:
- Memory (기본값): 테스트용 임시(Ephemeral) 저장소.
- Redis: 고성능 KV 스토어 (프로덕션 환경에 권장).
- MongoDB: 유연한 문서 저장소(document store).
- MySQL / SQLite: 관계형 데이터베이스 지원.
redisClient := redis.NewClient(&redis.Options{Addr: "localhost:6379"})
memory := providers.NewRedisMemoryProvider(redisClient, "session-id")
...
예시 (Examples)