Local-first memory, decision engine, and governance harness for AI agents — portable across IDEs. Own the state. Rent the intelligence.

Athena – 휴대 가능한 자체 호스팅 AI 에이전트 메모리

개요 – Athena는 Python 기반 SDK로, LLM 에이전트의 “메모리”를 일반 Markdown 파일로 자신의 디스크에 보관할 수 있습니다. 동일한 컨텍스트가 다양한 IDE 통합 채팅 어시스턴트(Claude Code, Antigravity, Cursor, Gemini CLI, VS Code 등)와 모든 기반 모델 간에 함께 이동할 수 있다는 아이디어입니다. Athena는 이러한 IDE의 채팅 패널에 연결되는 작은 명령줄 인터페이스(athena init, /start, /end, /ultrastart 등)를 제공하여 세션을 기록하고, 나중에 하이브리드 키워드+벡터 RAG 파이프라인으로 관련 사실을 검색합니다.

왜 중요한가

휴대성 – 벤더 종속 메모리가 없습니다. 지식은 일반적이고 git 추적 가능한 Markdown에 존재하므로 컨텍스트를 잃지 않고 Claude에서 Gemini(또는 미래의 모든 모델)로 전환할 수 있습니다.
로컬 우선 – “경량” 설치에는 클라우드 종속성이 없습니다. 모든 것이 자신의 머신에서 실행됩니다. 선택적 “전체” 설치에는 클라우드 동기화 및 재순위를 위한 Supabase 기반 pgvector 저장소가 추가됩니다.
안전 훅 – Athena는 코드로 강제되는 가드레일(파괴 검사, 비밀 스캔, 그라운딩)을 주입하여 파괴적인 명령이 모델에 도달하기 전에 중지합니다.
비용 인식 – 다양한 사용 모드(lightweight, standard, deep)를 통해 세션당 로드/저장되는 토큰 수를 제어하여 API 비용을 예측 가능하게 유지합니다.

핵심 구성 요소

구성 요소	역할
IDE 훅	지원되는 IDE의 채팅 UI에서 `/start` … `/end` 명령을 캡처하는 최소한의 코드 강제 통합.
Athena SDK	세션 수명 주기를 처리하고, Markdown 로그를 작성하고, 하이브리드 검색 파이프라인(키워드 검색 + 선택적 벡터 임베딩 + 크로스 인코더 재순위)을 실행합니다.
디스크 저장소	일반 Markdown 파일로, git으로 버전 관리됩니다. 선택적 Supabase pgvector 저장소로 클라우드 동기화 및 더 빠른 벡터 검색을 제공합니다.

아키텍처는 3계층 흐름으로 시각화됩니다: IDE → Athena SDK → 디스크(또는 Supabase).

시작하기 (빠른)

# Clone & set up a virtual environment
git clone https://github.com/winstonkoh87/Athena-Public.git && cd Athena-Public
python3 -m venv .venv && source .venv/bin/activate

# Install the lightweight package (no cloud deps)
pip install -e "[local]"

# Initialise for your IDE (example: Claude Code)
athena init --ide claude

# Verify the installation
athena doctor   # should report 0 failures

그런 다음 IDE의 AI 채팅 패널에서 /start를 입력하고 평소처럼 작업한 후 /end로 마무리합니다. 세션은 자동으로 Markdown으로 저장됩니다.

안전성 및 신뢰성

가드레일 – 내장된 “파괴 검사”는 16개의 알려진 파괴적 명령 중 14개를 차단합니다. 나머지 2개는 docs/TECH_DEBT.md에서 추적됩니다.
비밀 스캔 – CI는 모든 커밋에서 Gitleaks를 실행합니다. README는 1,248개의 커밋에서 유출이 전혀 없다고 보고합니다.
벤치마킹 – 저장소에는 다음을 측정하는 스크립트가 포함되어 있습니다:
- KV 캐시 워밍업 속도 향상(2K 토큰 부팅 vs 32K 부팅에서 약 35-50배 빠름).
- 검색 품질(Hit@5 = 0.569, MRR@5 = 0.472)을 엄격한 평가기에서 측정.
테스트 – 644개의 단위 및 통합 테스트가 모두 통과(pytest). ruff를 사용한 린팅은 문제 없음.

누가 사용해야 하나요?

개발자 – AI 지원 코딩에 의존하며 개인 컨텍스트가 모델이나 제공업체 변경 후에도 유지되기를 원하는 사람.
팀 – 이미 문서를 버전 관리하고 있으며 LLM 어시스턴트를 위한 재현 가능하고 감사 가능한 메모리 계층을 원하는 팀.
개인정보 보호를 중시하는 사용자 – 독점 클라우드 메모리보다 로컬 저장소를 선호하는 사용자.

제한 사항

“복합 개인화” 주장은 단일 저자의 1,900개 이상 세션을 기반으로 합니다. 공식적인 다중 사용자 연구는 아직 없습니다.
반 아첨 메커니즘은 현재 Claude Code에만 구현되어 있습니다.
전체 클라우드 동기화 및 벡터 재순위에는 Supabase 계정과 추가 구성이 필요합니다.

더 알아보기

문서 – docs/GETTING_STARTED.md, docs/ARCHITECTURE.md, docs/CLI.md.
안전 – SAFETY.md는 제한 및 책임 있는 사용에 대해 설명합니다.
벤치마크 – docs/BENCHMARKS.md는 검색 및 KV 캐시 측정에 대해 자세히 설명합니다.
기여 – IDE 지원을 추가하거나 검색 파이프라인을 개선하려면 CONTRIBUTING.md의 지침을 따르세요.

TL;DR

Athena는 LLM 에이전트 메모리를 불투명한 플랫폼 서비스에서 사용자 소유의 Markdown 파일로 이동하는 실제 오픈 소스 도구입니다. IDE 훅, 하이브리드 RAG 검색, 안전 가드레일을 갖추고 있습니다. 로컬에서 즉시 작동하며 Supabase를 통해 클라우드 동기화로 확장할 수 있습니다.