jzjzzzzzzz/agent-me

Distill your knowledge, memories, and decisions into an open-source, inspectable AI Agent Twin.

Agent‑Me – 당신의 오픈소스 "AI 트윈"

무엇인가요 – Agent‑Me는 버전 관리된 Markdown으로 저장된 개인 지식을 작고 검사 가능한 AI 에이전트로 전환할 수 있는 실행 가능한 FastAPI + React 애플리케이션입니다. 이 에이전트는 단순히 사실을 반복하지 않고 결정론적이고 다단계 파이프라인(검색 → 계획 → 조사 → 비판 → 작성 → 선택적 검증)을 따르며, 어떤 일이 일어났는지에 대한 전체 추적 기록을 반환합니다.

왜 중요한가요 – 대부분의 개인용 챗봇은 단일 프롬프트와 벡터 스토어에 의존합니다. Agent‑Me는 개인용 AI를 시스템으로 간주하며, 명시적인 메모리, 출처, 증거 기반 답변을 갖춥니다. 모든 중간 단계가 노출되어 있어, 트윈이 왜 어떤 말을 하는지 확인할 수 있으며, 증거가 부족할 경우 합성을 차단할 수 있습니다.

핵심 개념

구성 요소	역할	구현 (README에 설명됨)
개인 지식	트윈의 정적 사실, 선호, 경험 등	검토 가능한 버전 관리된 Markdown 파일 (예: `knowledge/example-profile.md`).
RAG	답변 전 관련 요약을 찾음	로컬 코퍼스 위에서 작동하는 경계가 있고 결정론적인 로컬 리트리버.
플래너	질문에 대한 전반적인 접근 방식을 결정	타입화된 `Plan` 데이터클래스를 생성.
리서처	계획에 필요한 정확한 소스 요약을 추출	`EvidenceBundle`를 반환하며, 요약과 메타데이터를 포함.
크리틱	수집된 증거가 합성에 충분한지 확인	`Critique`를 발행; 증거가 부족하면 "부족한 증거" 응답으로 파이프라인을 차단.
라이터	증거를 인용하여 최종 답변을 생성	인용과 안전한 요약을 포함한 `WrittenAnswer`를 발행.
검증자 (선택 사항)	인용 경로 및 기타 불변 조건에 대한 추가 검사 수행	`Verification` 결과를 생성; 검사 실패 시 답변을 거부.
공개 추적	전체 실행을 관찰 가능하게 함	각 단계의 결과, 안전한 요약, 메트릭을 포함한 JSON 페이로드.
평가	회귀 테스트를 위한 결정론적 동작 보장	버전 관리된 피규어(`course/fixtures/...`)와 결정론적 평가자가 CI에서 실행.

작동 방식 (고수준 흐름)

사용자가 요청 전송 /api/v1/collaborate (또는 챗 엔드포인트)에. 요청에는 질문과 원하는 워크플로우(default = 플래너-리서처-크리틱-라이터, verified = 검증자 추가)가 포함됨.
검색 로컬 코퍼스에서 관련 Markdown 요약을 추출.
플래너 답변해야 할 내용을 설명하는 구조화된 계획 생성.
리서처 계획에 필요한 정확한 요약을 수집.
크리틱 수집된 증거가 충분한지 검증; 부족하면 고정된 "부족한 증거" 응답 반환.
라이터 인용을 고려한 답변 작성.
검증자 (활성화된 경우) 인용 경로 및 기타 불변 조건 검사; 실패 시 차단.
응답 답변, 소스 목록, grounded 플래그, 각 단계의 전체 trace 포함.

시작하기 (빠른 시작)

방법	단계
Docker Compose (권장)	1️⃣ `git clone https://github.com/jzjzzzzzzz/agent-me.git` 2️⃣ `cd agent-me && cp .env.example .env` 3️⃣ `docker compose up --build` UI는 http://localhost:5173에서, API 문서는 http://localhost:8000/docs에서 접근.
로컬 툴체인	Python 3.11+, `uv`, Node 22+, npm 필요. `make setup` 실행 후 백엔드(`uvicorn …`)와 프론트엔드(`npm run dev`) 시작.
선택적 LLM 제공자	`.env`에서 `LLM_BASE_URL`, `LLM_API_KEY`, `LLM_MODEL`을 OpenAI 호환 엔드포인트(예: OrcaRouter)로 설정. `/api/v1/chat` 엔드포인트만 외부 모델 사용; `/collaborate`는 완전히 로컬로 유지.

일반적인 사용 사례

개인 지식 어시스턴트 – 자신의 프로젝트, 선호, 과거 결정에 대해 트윈에게 질문하고, 답변이 어떤 Markdown 항목에서 왔는지 정확히 인용받기.
연구 재현성 – 공개 추적을 통해 결론에 도달한 경로를 감사할 수 있어, 준수 또는 학술 환경에서 유용.
교육용 데모 – 리포지토리에는 개발자가 단계별로 파이프라인을 구축하는 이중 언어 커리큘럼이 포함되어 있음.
지속적으로 학습하는 AI 트윈의 프로토타입 – 아키텍처는 의도적으로 모듈화되어 있어, Markdown 저장소를 더 풍부한 그래프로 교체하거나, 동의 기반 인게스트를 추가하거나, 도구 호출 모듈을 연결할 수 있음.

제한 사항 (리포지토리에 기재됨)

메모리는 현재 정적 Markdown 파일 집합에 국한됨; 자동 인게스트나 잊기 기능 없음.
구조화된 아이덴티티 모델, 시간적 추론, 신뢰도 점수는 미래 작업.
검증자는 인용 경로 불변 조건만 검사; 사실의 진실을 보장하지 않음.
외부 LLM 제공자를 사용할 경우, 챗 엔드포인트만 데이터를 외부로 전송; 핵심 협업 파이프라인은 로컬로 유지됨.
이 시스템은 실험적 아키텍처이며, 프로덕션 준비된 개인 어시스턴트가 아님.

다음에 살펴볼 곳

아키텍처 세부 정보 – docs/ARCHITECTURE.md
API 스키마 – docs/API.md
신뢰 모델 – docs/TRUST.md
로드맵 및 기여 – ROADMAP.md 및 CONTRIBUTING.md
평가 피규어 – course/fixtures/collaboration_cases.json

결론 – Agent‑Me는 개인 지식을 검사 가능한 형태로 저장하고, 투명한 다단계 에이전트 파이프라인을 통해 질문에 답하는 "AI 트윈"을 구축하기 위한 구체적이고 오픈소스 플랫폼입니다. 의도적으로 제한되어 있음(로컬 검색, 결정론적 실행)이지만, 지속적으로 학습하고 개인정보를 보호하는 개인의 디지털 표현으로 확장될 수 있도록 설계되었습니다.