cortex

가정이나 팀을 위한 자체 호스팅 브레인: 사람들이 서로 대화하고, 공유된 노트를 읽은 에이전트와도 대화하는 대시보드 — 자신의 모델로, 자신의 머신에서.

상태: 알파. API와 구성 표면이 정리 중입니다. 마이너 버전 사이에 호환되지 않는 변경이 예상됩니다. 인덱스와 체크포인트 형식은 일회용 캐시입니다 — .cortex/를 삭제하면 대화는 사라지지만 노트는 사라지지 않습니다.

pip install cortxai
cortex setup                 # wizard: brain dir, model endpoint, admin account
cortex serve --host 0.0.0.0  # dashboard on :8642

또는 bash install.sh(pipx/uv/venv 자동 감지), 또는 docker-compose.yml에 문서화된 일회성 cortex setup /brain 후 docker compose up.

하지 않는 일: cortex는 모델을 호스팅하지 않습니다 — 엔드포인트를 직접 가져와야 합니다: Ollama, vLLM, LM Studio, LiteLLM 프록시, OpenRouter 또는 Anthropic API. 벡터 검색은 프로세스 내 정확 코사인 방식으로, 개인 및 팀 규모의 브레인에 적합하며 수백만 청크에는 부적합합니다. 볼트 편집은 충돌 감지(409와 배너)가 있는 마지막-쓰기-승리 방식이지, git급 병합이 아닙니다. 캘린더 커넥터는 아직 반복 규칙을 확장하지 않습니다.

대시보드

• 채팅 — 에이전트와의 비공개 스레드. 답변 전에 검색하고, 도구 호출을 스트리밍하며(⚙ search_brain … ✓ 33ms), 파일 경로로 인용합니다. 인용을 클릭하면 볼트 보기에서 열립니다.

• 채널 — 브레인에 있는 사람들을 위한 동료 채팅. @cortex를 멘션하면 에이전트가 채널에서 답변하며, 공유 볼트만 읽습니다 — 개인 볼트는 절대 읽지 않습니다.

• 볼트 — 공유 및 개인 볼트, Obsidian 스타일 렌더링으로 브라우저에서 편집: [[wikilinks]], ![[embeds]], > [!note] 콜아웃, frontmatter, 쓰기-통과 작업 체크박스, #tags. Ctrl-S로 저장. 동시 편집 시 조용한 덮어쓰기 대신 충돌 배너가 표시됩니다.

• 가져오기 — 기존 Obsidian 볼트를 zip 업로드, git URL 또는 서버 경로로 가져오기. .obsidian/, .git/ 및 비볼트 파일 유형은 건너뜁니다.

• 관리 — 계정(admin / member), 인덱스 통계.

계정은 사용자 이름 + 비밀번호(scrypt)이며, 세션은 HttpOnly 쿠키입니다. 각 사용자는 공유 볼트, 자신의 볼트, 커넥터 소스를 볼 수 있습니다 — 검색, grep, 에이전트는 요청별로 범위가 지정되며, 쿼리 내부에서 필터링되고 쿼리 후에 잘라내지 않습니다.

Related MCP server: claudecode-mcp

에이전트 스택

LangChain 채팅 모델 위의 LangGraph ReAct 에이전트, 스레드별 AsyncSqliteSaver 체크포인트에 대화 상태 저장:

providers:
  local:
    kind: openai                    # Ollama, vLLM, LM Studio — one wire
    base_url: "http://localhost:11434/v1"
    chat_model: qwen3
    embed_model: nomic-embed-text
  router:
    kind: openrouter                # cloud aggregator, OpenAI wire
    api_key_env: OPENROUTER_API_KEY
    chat_model: anthropic/claude-sonnet-5
  claude:
    kind: anthropic                 # direct Anthropic Messages API
    api_key_env: ANTHROPIC_API_KEY
    chat_model: claude-sonnet-5
roles:
  chat: router
  embed: local

LiteLLM 프록시는 base_url이 있는 kind: litellm입니다 — 라우팅 및 폴백 정책은 프록시에 유지되므로 cortex는 LiteLLM SDK를 포함하지 않습니다. 엔드포인트는 네트워크 사실로 분류됩니다: 사설, 루프백, CGNAT 및 Tailscale 주소는 신뢰되고, 공개 주소는 노트가 네트워크를 떠난다는 일반 경고를 받습니다.

검색은 하이브리드입니다: SQLite FTS5와 벡터 코사인을 별도로 순위화한 후, 상호 순위 융합(reciprocal rank fusion)으로 결합하고 최신성으로 보정합니다 — Cerebras 지식 베이스의 설계입니다. 청크 스키마 또는 임베딩 모델이 변경되면 인덱스는 처음부터 재구축됩니다. 벡터 공간을 조용히 혼합하는 것은 손상이기 때문입니다. 임베딩 엔드포인트가 없으면 가짜 벡터 점수가 아닌 전체 텍스트 검색임을 명시합니다.

확장하는 네 가지 방법

깨진 확장은 보고되고 격리되며, 결코 치명적이지 않습니다. 등록은 권한 부여가 아닙니다: 민감한 것을 다루는 도구는 호출 가능 객체 내부에 자체 검사를 유지합니다.

대시보드에서 관리하세요. 관리자 전용 확장 패널은 모든 플러그인, 스킬, 커넥터 및 MCP 서버를 제공 기능, 로드 오류(있는 경우), 소스 파일을 편집하지 않는 활성화 토글과 함께 나열합니다. 플러그인이나 커넥터를 브라우저에서 작성할 수 있습니다: 저장 전에 로드되므로, 임포트되지 않는 코드는 다음 턴을 조용히 깨뜨리는 대신 로더 자체의 메시지로 거부되고, 성공적인 저장은 에이전트를 재구축하여 재시작 없이 새 도구가 활성화됩니다. 커넥터에는 설정 상자와 "지금 실행" 버튼이 있고, MCP 서버에는 양식이 있습니다. cortex.yaml에 정의된 서버는 읽기 전용으로 표시됩니다 — 파일이 선언한 것의 소유자로 유지됩니다.

플러그인이나 커넥터를 저장하면 cortex 사용자로 서버에서 해당 코드가 실행됩니다. 이는 stdio MCP 서버를 구성하는 것과 동일한 신뢰 수준이며, 패널이 관리자 전용인 이유입니다. 터미널에서는 cortex ext list, cortex ext disable plugin <name>, cortex ext delete로 브라우저 없이 동일한 관리를 수행합니다.

Cortex는 또한 MCP 서버입니다 — claude mcp add home-brain -- cortex mcp --brain ~/brain은 Claude Code, Cursor 또는 Hermes에 동일한 도구 레지스트리를 박스 소유자 범위로 제공합니다.

브레인의 구조

~/brain/
├── cortex.yaml        # providers, roles, mcp servers, connectors
├── vaults/shared/     # everyone's notes
├── vaults/<user>/     # each user's private vault
├── sources/           # connector output
├── skills/ plugins/ connectors/
└── .cortex/           # index, checkpoints, usage.jsonl — disposable cache

폴더를 복사하여 백업하세요. 홈 브레인, 회사 브레인, 클럽 브레인: 세 개의 폴더, 세 개의 cortex serve 프로세스.

관측 가능성

모든 모델 및 도구 호출은 엔드포인트가 보고할 때 prompt_tokens/completion_tokens와 함께 JSONL을 .cortex/usage.jsonl에 추가합니다 — 누락된 수치는 0이 되는 대신 누락된 채로 유지되며, 이는 preflight가 보정을 위해 기대하는 방식입니다. 텔레메트리는 결코 호출을 실패시키지 않습니다.

개발

uv venv --python 3.12 && uv pip install -e '.[dev]'
.venv/bin/pytest                    # 102 tests
.venv/bin/ruff check src tests
cd web && npm install && npm run dev   # SPA dev server, proxies to :8642

프론트엔드 계약은 docs/product-spec.md에 있습니다. 릴리스 절차는 RELEASING.md입니다.

문서: unchained-labs.github.io/cortex · 브랜드: Unchained-Labs/branding · 라이선스: MIT