Claude, Python, 그리고 Local LLM을 사용하여 개인용 AI 운영체제를 구축한 방법

탭을 닫는 순간 제가 나누었던 모든 AI 대화가 사라졌습니다. 몇 주간의 연구, 기획 세션, 결정 맥락 — 모두 사라졌습니다. 그래서 저는 이 문제를 해결하는 시스템을 구축했습니다.

Atlas OS는 Claude Cowork에 지속적인 메모리(persistent memory), 로컬 RAG 검색, 예약된 자동화, 그리고 웹 대시보드를 결합한 오픈 소스 "개인용 운영체제"입니다. 이는 상태가 없는(stateless) 챗봇을 모든 것을 기억하고 당신이 잠든 동안에도 작동하는 무언가로 변화시킵니다.

GitHub: paulholland511/atlas-os | pip install atlas-os

아키텍처 (The Architecture)

┌─────────────────────────────────────────────┐
│                 atlas CLI                    │
│   init · doctor · search · embed · dashboard │
...

전체 시스템은 로컬 우선(local-first) 방식입니다. 당신의 노트, 임베딩(embeddings), 그리고 지식 그래프(knowledge graph)는 절대 당신의 기기를 떠나지 않습니다. "데이터베이스"는 마크다운(markdown) 파일들로 구성된 폴더입니다. 히스토리는 일반적인 git입니다. 모든 것은 차이점 비교(diffable)가 가능하고, 휴대 가능하며, 당신의 것입니다.

주요 설계 결정 (Key Design Decisions)

벡터 저장소로 왜 SQLite를 선택했는가 (Pinecone/Weaviate가 아닌 이유)

저는 벡터 저장소(vector store)로 sqlite-vec를 선택했습니다. 설정이 필요 없고(zero-config), 프로세스에 직접 내장되며, 실행 중인 서비스가 필요 없기 때문입니다. 약 10,000개의 청크(chunks)를 가진 개인 지식 베이스의 경우, KNN 검색은 충분히 빠르며 운영 오버헤드가 제로에 가깝습니다. C 확장(C extension)이 없는 환경을 위해 NumPy 코사인 유사도(cosine fallback) 방식도 제공합니다.

왜 하이브리드 검색인가 (단순 임베딩이 아닌 이유)

순수 벡터 검색(Pure vector search)은 정확한 일치를 놓칩니다. 순수 키워드 검색(Pure keyword search)은 의미를 놓칩니다. Atlas OS는 이 둘을 융합합니다:

BM25가 단어 빈도(term frequency)에 따라 각 청크의 점수를 매깁니다.
**벡터 코사인(Vector cosine)**이 의미적 유사성(semantic similarity)에 따라 점수를 매깁니다.
**상호 순위 결합(Reciprocal Rank Fusion)**이 두 순위 목록을 병합합니다.
**TF-IDF 재순위화(reranking)**가 상위 결과들을 정교화합니다.

이 방식은 단일 접근 방식보다 일관되게 뛰어난 성능을 보이며, 특히 사용했던 "단어"를 기억하면서도 "개념적" 일치가 필요한 개인용 저장소(personal vault)에서 더욱 그렇습니다.

왜 Flask인가 (React가 아닌 이유)

대시보드는 Python 패키지의 일부로 제공되며, atlas dashboard 명령어로 실행됩니다. npm install도, 빌드 단계도, node_modules도 필요 없습니다. 시스템 상태(system health), 감사 추적(audit trail), 예약된 작업(scheduled tasks), 기술(skills), 벡터 저장소 통계(vector store stats), RAG 검색(RAG search), 그리고 D3.js 지식 그래프(knowledge graph)까지 총 7개의 패널로 구성됩니다. 모든 패널은 Jinja2와 인라인 CSS를 사용하여 서버 사이드(server-side)에서 렌더링됩니다.

실제로 매일 수행하는 작업

시스템은 예약된 작업을 자율적으로 실행합니다:

세션 캡처 (Session capture) — 모든 Cowork 대화는 하루에 두 번 당신의 저장소(vault)에 마크다운(markdown) 노트로 저장됩니다. 요약, 주요 작업, 수정된 파일 등이 포함됩니다.
RAG 인덱싱 (RAG indexing) — 의미론적 청킹 (semantic chunking) + 임베딩 (embedding)이 점진적으로 실행됩니다. 새로운 노트는 몇 분 이내에 검색 가능해집니다.
이메일 브리핑 (Email briefings) — 저장소 상태, 대기 중인 작업, 시스템 상태 점검 내용이 담긴 모닝 리포트가 이메일 수신함으로 전송됩니다.
트레이딩 리서치 (Trading research) — 멀티 에이전트 (multi-agent) 모듈이 시장 브리핑을 작성하여 저장소에 기록합니다 (저는 이를 암호화폐 리서치 용도로 사용하며, 금융 조언이 아닙니다).

수치로 보는 성능

400개 이상의 테스트, GitHub Actions를 통한 CI/CD 지원
마켓플레이스 및 레지스트리를 포함한 160개 이상의 설치 가능한 기술 (skills)
플러그형 LLM 백엔드 (Pluggable LLM backends) — LM Studio, Ollama, llama.cpp를 자동으로 감지
추가 전용 감사 추적 (Append-only audit trail) — 모든 자율적 작업이 JSONL 형식으로 기록됨
Docker 지원, MIT 라이선스

내가 배운 점

세션 지속성 (Session persistence)은 핵심 기능입니다. RAG, 대시보드, 스킬 등 다른 모든 요소는 Vault(금고)가 기억하고 있기 때문에 의미가 있습니다. 이것이 없다면 매 세션마다 컨텍스트를 다시 구축해야 합니다.
하이브리드 검색 (Hybrid search)은 복잡성을 감수할 가치가 있습니다. BM25 + 벡터 + RRF 파이프라인은 순수 임베딩 (Embedding) 검색에 비해 단일 항목 중 가장 큰 품질 향상을 가져왔습니다.
로컬 우선 (Local-first) 방식은 실제적인 제약 사항이지만 그만한 가치가 있습니다. 클라우드 의존성이 없다는 것은 시스템이 오프라인이나 비행기 안에서도 작동하며 데이터를 절대 유출하지 않음을 의미합니다. 하지만 이는 직접 임베딩 서버를 관리해야 함을 뜻합니다.
동기화 계층으로서의 Git은 과소평가되어 있습니다. Vault의 모든 변경 사항은 커밋 (Commit)됩니다. 이를 통해 무료로 버전 관리, 브랜칭 (Branching), 충돌 감지 기능을 얻을 수 있습니다. 머지 충돌 (Merge conflicts)이 어려운 부분이지만 (v3.0 로드맵에서 이 문제를 다룹니다), 매우 유용합니다.

향후 계획 (v3.0)

확장 아키텍처 (Extension architecture) — 트레이딩/음성/작업 모듈을 선택 가능한 추가 기능으로 분리
MCP 스킬 — 모든 스킬이 모델 컨텍스트 프로토콜 (Model Context Protocol) 서버가 됨
보안 샌드박스 (Security sandbox) — 커뮤니티 스킬을 위한 AST 분석 + 런타임 격리
Git 강화 — 동시 Vault 접근을 위한 적절한 머지 전략
플러그형 벡터 백엔드 (Pluggable vector backends) — sqlite-vec과 함께 LanceDB 및 ChromaDB 지원

리포지토리는 github.com/paulholland511/atlas-os에 있습니다. pip install atlas-os로 설치하고, atlas init을 실행하면 5분 안에 시작할 수 있습니다. 피드백과 기여를 환영합니다.