LucieEveille/kiwi-mem

🥝 kiwi‑mem – 인공지능을 뇌처럼

무엇인가요

• 채팅 클라이언트와 대규모 언어 모델(LLM) API(OpenAI 호환 또는 Anthropic 네이티브) 사이에 위치하는 자체 호스팅 게이트웨이입니다. 모든 요청에 인간처럼 장기 기억을 주입하고, 모델의 응답에서 새로운 기억을 추출합니다.

핵심 아이디어

• 기억의 열량 – 저장된 각 사실은 "온도"를 가집니다. 시간이 지나면서 냉각되며, 대화에서 다시 언급되면 가열되고, 자주 언급되지 않으면 더 빠르게 냉각됩니다. 뜨거운 기억은 완전히 주입되고, 따뜻한 것은 요약 형태로, 차가운 것은 무시됩니다.
• 드림(수면) 사이클 – 매일 밤 실행되는 프로세스로, 오래된 조각을 정리하고 관련된 정보를 기억 장면으로 통합하며, 작은 추론 단계를 통해 명시되지 않은 사실을 추론합니다. 그 결과는 고수준의 기억으로 저장됩니다.
• 캘린더 압축 – 채팅 기록은 자동으로 계층적인 요약(일 → 주 → 월 → 분기 → 년)으로 압축되어 오래된 기간은 몇 토큰만 사용합니다.
• 충돌 해결 및 잠금 – 새로운 사실이 오래된 사실과 모순될 경우, 오래된 항목은 비활성화됩니다. 중요한 기억은 잠그면 영원히 쇠퇴하지 않습니다.
• 토큰 절약형 프롬프트 레이아웃 – 정적 데이터(성격, 잠긴 기억, 캘린더)는 캐시된 접두사에 배치되고, 동적 데이터(검색 결과, 수면 힌트)는 그 뒤에 오며, 입력 토큰 비용을 최대 90%까지 절감합니다.

작동 방식

1. 채팅 클라이언트가 https://your‑domain/v1/chat/completions에 요청을 보냅니다(키위-멤 게이트웨이).
2. 게이트웨이는 하이브리드 RRF 검색(벡터 + 키워드)을 사용해 관련 기억을 검색하고, 열량 수준에 따라 프롬프트 앞부분에 추가합니다.
3. 요청은 설정된 LLM 제공자에게 전달됩니다.
4. LLM의 응답은 클라이언트에 반환되며, 또한 새로운 기억 조각을 분석하여 초기 열량과 함께 저장됩니다.
5. 주기적으로(또는 요청 시) 드림 작업이 실행되어 통합 및 추론이 이루어집니다.

주요 기능

기능	기능 설명
열량 기반 감소 및 강화	기억은 자동으로 희미해지며, 반복 언급 시 재가열됩니다.
드림 수면 통합	3단계 정리, 통합, 전망 추론.
계층적 캘린더	일 → 주 → 월 → 분기 → 년 요약을 세부 정보를 줄이며 주입.
충돌 처리	새로운 모순 사실이 오래된 것을 비활성화. 잠긴 기억은 영원히 유지.
도구 드로어	검색, 알림, 웹 검색 등 20개 이상의 내장 도구는 시스템이 필요하다고 예측할 때만 로드되어 토큰을 절약.
다중 제공자 지원	OpenAI 호환 엔드포인트 및 Anthropic 네이티브 API 모두 지원. 추가 번역 없이 작동.
프로젝트 격리	글로벌 기억은 공유되지만, 각 "프로젝트"는 다른 프로젝트에 유출되지 않는 개인 지시사항, 파일, 대화 기록을 가질 수 있음.
웹 관리 패널	제공자 설정, 기억 조회/편집, 드림 실행, 프로젝트 관리, 백업 내보내기/가져오기.
Docker 우선 배포	docker compose up -d로 한 번에 전체 스택(FastAPI 게이트웨이 + PostgreSQL + pgvector) 시작.

기술 스택

• Python + FastAPI – HTTP 게이트웨이 및 기억 로직.
• PostgreSQL + pgvector – 기억, 임베딩, 열량 값을 저장.
• Docker / Docker‑Compose – 한 번의 클릭으로 배포 가능하며, VPS, 클라우드 VM, Zeabur 등 다양한 환경에서 이식 가능.
• AGPL‑3.0‑or‑later – 호스팅된 수정 사항도 오픈소스로 공개하도록 보장.

누구를 위한가요

• 습관, 선호도, 건강 데이터 등을 기억해야 하는 개인용 AI 어시스턴트.
• 장기적인 채팅 동반자(정서적 지원, 역할극, 이야기 만들기).
• 여러 세션에 걸쳐 세계관 세부 사항을 유지해야 하는 창의적 파트너.
• 진도와 약점을 추적하는 학습 튜터.

시작하기 (빠른 실행)

# 새 서버에서
curl -fsSL https://get.docker.com | sh
git clone https://github.com/LucieEveille/kiwi-mem.git
cd kiwi-mem
cp .env.example .env   # API_KEY를 미리 채우고 싶다면 수정
docker compose up -d

• curl http://localhost:8080 → "status":"running"로 작동 확인.
• https://your‑domain/admin 열기(기본적으로 비밀번호 없음)로 LLM 제공자 추가, 연결 테스트, OpenAI 스타일 API를 지원하는 클라이언트로 채팅 시작.

업데이트 방법

• bash scripts/update.sh 실행 – DB 백업, 최신 코드 다운로드, 컨테이너 재빌드, 새 버전이 시작되지 않으면 자동 롤백.
• 선택적으로 cron 설치(--install‑cron)로 매일 자동 업데이트.

제한 사항

• 개인용 기억을 위한 설계이며, 기업용 문서 검색이나 지식 그래프 용도에는 적합하지 않음.
• 게이트웨이 자체에는 인증이 없으므로, 공개적으로 노출된 경우엔 엔드포인트를 보호해야 함(예: Cloudflare Access, 기본 인증, IP 허용 목록).

라이선스

• AGPL‑3.0‑or‑later – 사용, 수정, 재배포 가능하지만, 네트워크를 통해 서비스를 제공할 경우 소스(변경 포함)를 사용자에게 공개해야 함.

---

kiwi‑mem은 인간의 기억과 유사한 잊음과 통합을 갖춘, 진정으로 "당신을 기억하는" AI를 제공하는 것을 목표로 합니다.