Cairn

에이전트 기반 장애 분석 코파일럿입니다. "왜 새벽 3시에 체크아웃 지연이 급증했지?"라고 평범한 영어로 물어보세요. Cairn이 관측 스택을 조회하고, 배포 타임라인과의 상관관계를 분석하며, 관련 런북을 검색한 뒤 증거와 함께 근본 원인을 제안합니다. 또한 인간 승인 게이트를 거쳐 수정 조치를 실행할 수도 있습니다.

이 저장소는 docs/architecture.md를 구현합니다.

대시보드

동반 npm 패키지(npx @nouman-amjad/cairn dashboard)는 빌드 단계, 의존성, 네트워크 없이 모든 프로젝트에 대해 로컬 실시간 대시보드를 제공합니다.

Related MCP server: semley

네 가지 핵심 원칙과 코드 내 위치

구조

packages/
  cairn-core/          domain model, config, auth, DB, sensitivity, artifacts
  cairn-mcp-kit/       MCP scaffolding: identity, OPA guard, result capping, versioning
services/
  cairn-gateway/       OIDC, rate limits, cost budgets, circuit breaker, SSE fan-out
  cairn-orchestrator/  the agent loop as a state machine persisted to Postgres
  cairn-router/        model routing, cost accounting, vLLM + Anthropic clients
  cairn-approval/      approval state machine and the Slack gate
  cairn-mcp-observability/  metrics, logs, traces, deploys, artifacts
  cairn-mcp-runbooks/       hybrid search, ingest, past-incident recall
  cairn-mcp-actions/        approval-gated write tools
  cairn-eval/          30 scenarios, 7 metrics, the CI gate, a seeded stack
  cairn-cli/           `cairn ask "why did checkout spike?"`
ui/                    Next.js: chat, trajectory viewer, approvals
cairn-deploy/          Helm chart, ArgoCD app-of-apps, OPA bundle, prompts
cairn-infra/           Terraform: VPC, EKS, RDS, Karpenter, IRSA, S3
docker/                one Dockerfile for all Python services, plus vLLM
docs/adr/              14 architecture decision records

cairn-deploy와 cairn-infra는 검토를 위해 여기에 벤더링되어 있습니다. 프로덕션에서는 별도의 수명주기를 가진 별도의 저장소입니다 — ADR-013 참조.

시작하기

make install     # uv sync + npm ci
make up          # Postgres (pgvector), Redis, MinIO, OPA
make migrate
make test        # 246 tests
make selfcheck   # 21 module self-checks
make eval        # 30 scenarios through the real agent loop

위 어느 것에도 GPU나 API 키가 필요하지 않습니다. make eval은 휴리스틱 모드로 실행되며, 모델 대신 스크립트된 대역을 사용하여 전체 파이프라인(루프, 도구 상한, 영속성, 7개 메트릭, 게이트)을 실행합니다. 주의사항을 참조하세요.

실제 모델로 실행하려면 CAIRN_ROUTER_ANTHROPIC_API_KEY를 설정하고 CAIRN_ROUTER_VLLM_URL을 vLLM 서버로 지정하세요.

MCP 클라이언트로 디버깅하기

모든 MCP 서버는 Streamable HTTP뿐만 아니라 stdio도 지원합니다:

make mcp-stdio
# or, the way an outside user would:
uvx cairn-mcp-observability --stdio

Cursor, Zed 또는 다른 MCP 클라이언트를 연결하면 에이전트가 보는 것과 정확히 동일한 화면을 볼 수 있습니다. 이는 약 20줄 정도의 비용(ADR-002)이 들지만, 도구 결과가 예상과 전혀 다르게 보이는 첫 순간에 그 가치를 톡톡히 합니다.

무엇이 검증되었고 무엇이 검증되지 않았는가

"작동한다"는 모호한 주장은 피하기 위해 구체적으로 설명합니다.

여기서 직접 실행하여 검증된 것:

• 246개 테스트가 실제 PostgreSQL 16 + pgvector에서 통과합니다. 여기에는 승인 게이트 안전 속성(자기 승인 불가, 이중 실행 불가, 승인 없는 실행 불가, 데이터베이스 트리거로 강제되는 추가 전용 감사 로그)과 제한된 데이터가 클라우드 모델에 도달하지 않는다는 라우터 속성이 포함되며, 모든 작업 클래스와 계층 상태에 대해 철저히 검사됩니다.

• 21개 모듈 자체 점검이 통과합니다.

• Alembic 마이그레이션이 실제 데이터베이스에 깨끗하게 적용됩니다.

• 12/12 OPA 정책 테스트가 통과합니다.

• 30개 시나리오 평가가 실제 에이전트 루프를 통해 종단 간 실행됩니다. 7개 메트릭 모두 목표치를 상회하며, 게이트가 시뮬레이션된 회귀와 목표 미달 실행을 모두 올바르게 차단합니다.

• UI가 타입 검사와 빌드를 통과합니다. CLI의 5개 명령이 모두 해석됩니다.

여기서 검증되지 않은 것과 그 이유:

• 평가 정확도 수치. 커밋된 기준선은 휴리스틱 모드로, 에이전트가 아닌 하네스를 평가합니다. 실제 수치에는 라이브 라우터에 대한 make eval-record가 필요합니다. LLM 원인 판정기는 구축되었지만 보정되지 않았습니다 — 100회 실행에 대한 라벨링이 없어 κ가 알려지지 않았습니다.

• Terraform. 이 환경에는 terraform 바이너리가 없습니다. fmt, validate, tflint는 CI에서 실행됩니다. AWS 계정에 적용된 것은 없습니다.

• Helm 렌더링. helm lint, template, kubeconform이 세 환경 모두에 대해 CI에서 실행됩니다. 로컬에서는 실행되지 않았습니다.

• docs/cost.md의 모든 비용 수치. 이를 측정할 회계 시스템은 구축되고 테스트되었지만, 이를 채울 트래픽은 존재하지 않습니다.

• vLLM 성능 표. 메모리 대역폭에서 계산한 산술값이지 측정값이 아닙니다. docs/inference.md에 벤치마크 명령과 반증 임계값이 있습니다.

• 카오스 테스트. 로드맵의 7단계는 아직 실행되지 않았습니다.

docs/roadmap.md가 이 단계를 단계별로 추적합니다.

문서

• docs/architecture.md — 이 구현이 따르는 설계

• docs/adr/ — 각각의 결과를 포함한 14개의 결정 기록

• docs/security.md — 위협 모델과 각 통제 수단의 위치

• docs/inference.md — GPU 크기 산정, KV-캐시 산술, vLLM 플래그

• docs/cost.md — GPU가 비용을 상쇄하는지 여부를 포함한 비용 모델

• docs/operations.md — 런북: 무엇이 페이지를 만들고, 무엇을 해야 하는가

• docs/roadmap.md — 단계, 위험, 그리고 실제로 완료된 것

• services/cairn-eval/README.md — 게이트 실패를 읽는 방법