ContextKeep 🧠

AI 에이전트를 위한 무제한 장기 기억 장치

ContextKeep는 AI 에이전트(Claude, Cursor, Gemini, OpenCode 등)에게 지속적이고 검색 가능한 두뇌를 제공하는 강력한 독립형 메모리 서버입니다. 같은 말을 반복하지 마세요. AI가 모든 것을 영구적으로 기억하게 하세요.

기능 • V1.3 새로운 기능 • 설치 • MCP 도구 • 웹 대시보드 • 설정

🌟 기능

• ♾️ 무제한 컨텍스트: 프로젝트 세부 정보, 환경 설정, 결정 사항, 스니펫을 제한 없이 저장하세요. 만료 기한이나 크기 제한이 없습니다.

• 💰 비용 및 토큰 절감: 중요한 메모리만 불러와 컨텍스트 윈도우 사용량과 API 비용을 대폭 줄입니다.

• 🔌 범용 호환성: Stdio(로컬) 또는 SSE(원격/홈랩)를 통해 모든 MCP 호환 클라이언트와 작동합니다.

• 🧭 메모리 인덱스 프로토콜: list_all_memories() → retrieve_memory()로 이어지는 신뢰할 수 있는 2단계 검색 시스템을 통해 에이전트가 항상 올바른 키를 찾을 수 있습니다.

• 🖥️ 현대적인 웹 대시보드: 세련된 다크 인터페이스에서 그리드, 목록, 달력 보기로 메모리를 시각적으로 관리하세요.

• 🔒 개인정보 보호 우선: 100% 로컬 저장소입니다. 데이터가 외부 서버로 전송되지 않습니다.

• 🔎 스마트 검색: 모든 메모리 콘텐츠에 대한 키워드 및 의미론적 검색을 지원합니다.

• 🐧 Linux 서비스: systemd 서비스로 백그라운드에서 조용히 실행됩니다.

• 🐳 Docker 준비 완료: Docker Compose를 통한 한 번의 명령으로 배포 가능합니다.

• ⬇️ 내보내기 및 백업: MCP 도구 또는 웹 UI를 통해 모든 메모리를 JSON으로 내보낼 수 있습니다.

🆕 V1.3 새로운 기능 — Harbor

🐳 Docker 지원

커뮤니티 요청 1위 기능입니다. 이제 ContextKeep은 Dockerfile과 docker-compose.yml을 제공하여 한 번의 명령으로 배포할 수 있습니다:

docker compose up --build

이것으로 끝입니다. :5100 포트의 MCP 서버와 :5000 포트의 웹 UI가 Docker 볼륨을 통해 지속적인 저장소와 함께 실행됩니다.

📦 현대적인 Python 패키징

• pyproject.toml — uv, poetry, pip를 위한 표준 의존성 사양

• uv 지원 — 설치 프로그램이 uv를 자동 감지하여 uv sync를 통해 매우 빠르게 설정합니다.

• 하위 호환성 — pip install -r requirements.txt도 여전히 작동합니다.

🛠️ 3가지 새로운 MCP 도구 (총 5개 → 8개)

⬇️ 웹 UI 내보내기

• 툴바의 모두 내보내기 버튼(또는 Ctrl+E 누르기)

• 타임스탬프가 포함된 contextkeep_backup_YYYY-MM-DD.json 파일 다운로드

🧹 코드 품질

• memory_manager.py의 죽은 코드(도달할 수 없는 중복 try/except) 수정

• 올바른 Python 패키징을 위해 누락된 core/__init__.py 추가

• 전체 코드에서 단순 except:를 except Exception:으로 교체

🚀 설치

옵션 1: 빠른 시작 (pip)

1. 저장소 복제:

   git clone https://github.com/mordang7/ContextKeep.git
   cd ContextKeep

2. 설치 프로그램 실행:

   • Linux/macOS:

     python3 install.py

   • Windows:

     python install.py

3. 마법사 따르기: 설치 프로그램이 가상 환경을 생성하고, 의존성을 설치하며, 즉시 사용 가능한 mcp_config.json을 생성합니다.

옵션 2: uv (빠름)

git clone https://github.com/mordang7/ContextKeep.git
cd ContextKeep
uv sync
uv run python server.py

옵션 3: Docker (홈랩 권장)

git clone https://github.com/mordang7/ContextKeep.git
cd ContextKeep
docker compose up --build -d

다음 서비스가 시작됩니다:

메모리는 Docker 볼륨(contextkeep-data)에 지속적으로 저장됩니다.

🛠️ MCP 도구

ContextKeep은 연결된 모든 에이전트에 8개의 MCP 도구를 노출합니다:

권장 에이전트 지침

GEMINI.md, AGENTS.md 또는 CLAUDE.md에 다음을 추가하세요:

## Memory Index Protocol (MANDATORY)
1. FIRST — call `list_all_memories()` to get the complete key directory
2. THEN — call `retrieve_memory(exact_key)` using the exact key from step 1
Only use `search_memories()` for content-based searches, NOT for key lookup.

🔌 설정

mcp_config.example.json의 내용을 AI 클라이언트의 설정 파일에 복사하고 경로를 업데이트하세요.

옵션 1: 로컬 (Claude Desktop / Gemini CLI / Cursor)

{
  "mcpServers": {
    "context-keep": {
      "command": "/absolute/path/to/ContextKeep/venv/bin/python",
      "args": ["/absolute/path/to/ContextKeep/server.py"]
    }
  }
}

옵션 2: SSH를 통한 원격 (홈랩 / Raspberry Pi)

홈 서버에서 ContextKeep을 실행하고 네트워크상의 모든 기기에서 액세스하세요:

{
  "mcpServers": {
    "context-keep": {
      "command": "ssh",
      "args": [
        "-i", "/path/to/private_key",
        "user@192.168.1.X",
        "'/path/to/ContextKeep/venv/bin/python'",
        "'/path/to/ContextKeep/server.py'"
      ]
    }
  }
}

옵션 3: SSE 모드 (HTTP)

OpenCode, 웹 앱 또는 HTTP 전송을 선호하는 모든 클라이언트에 적합합니다:

{
  "mcpServers": {
    "context-keep": {
      "transport": "sse",
      "url": "http://localhost:5100/sse"
    }
  }
}

옵션 4: Docker

mcp_config.docker.example.json을 사용하거나 클라이언트를 컨테이너로 지정하세요:

{
  "mcpServers": {
    "context-keep": {
      "transport": "sse",
      "url": "http://localhost:5100/sse"
    }
  }
}

🌐 웹 대시보드

ContextKeep은 CLI를 사용하지 않고도 메모리를 관리할 수 있는 모든 기능을 갖춘 웹 UI를 제공합니다.

• URL: http://localhost:5000

• 그리드 보기: 태그 칩, 문자 수, 인라인 작업이 포함된 메모리 카드

• 목록 보기: 마지막 업데이트 순으로 정렬된 모든 메모리를 보여주는 밀도 높은 테이블

• 달력 보기: 월별로 메모리 기록 탐색

• 검색: 제목, 키, 콘텐츠에 대한 실시간 필터링

• 전체 CRUD: 브라우저에서 메모리 생성, 보기, 편집, 삭제

• 내보내기: 클릭 한 번으로 모든 메모리를 JSON으로 다운로드 (Ctrl+E)

수동으로 시작하려면:

./venv/bin/python webui.py

🐧 Linux 서비스 설정 (홈랩 권장)

MCP 서버와 웹 UI를 모두 지속적인 백그라운드 서비스로 실행하세요:

chmod +x install_services.sh
./install_services.sh

다음이 설치됩니다:

서비스 관리:

sudo systemctl status contextkeep-server
sudo systemctl restart contextkeep-webui

📋 변경 로그

V1.3 — Harbor

• ✅ Docker 지원 — 한 번의 명령으로 배포 가능한 Dockerfile + docker-compose.yml

• ✅ 현대적인 패키징 — pip와 함께 pyproject.toml + uv 지원

• ✅ 새로운 MCP 도구: delete_memory() — 에이전트가 메모리 삭제 가능

• ✅ 새로운 MCP 도구: get_memory_stats() — 메모리 개수 및 크기 확인

• ✅ 새로운 MCP 도구: export_memories() — JSON 전체 백업

• ✅ 웹 UI: Ctrl+E 단축키를 사용한 모두 내보내기 버튼

• ✅ 웹 UI: 통계 API 엔드포인트

• ✅ 수정: memory_manager.py의 죽은 코드 제거

• ✅ 수정: Docker/패키지 임포트를 위해 누락된 core/__init__.py 추가

• ✅ 수정: 단순 except를 except Exception으로 교체

• ✅ uv 감지 기능이 포함된 V1.3 설치 프로그램 업데이트

• ✅ 커뮤니티 기여자 감사 🙏

V1.2 — Obsidian Lab

• ✅ 새로운 list_all_memories() MCP 도구 — 한 번의 호출로 전체 메모리 디렉토리 확인

• ✅ Obsidian Lab UI 재설계 — 시안/네온 액센트가 있는 다크 프리미엄 미학

• ✅ 헤더에 메모리 개수 실시간 배지 표시

• ✅ 달력 월 탐색 (앞으로/뒤로)

• ✅ 그리드 카드에 태그 칩 및 문자 수 배지 표시

• ✅ 더 깔끔한 달력 레이아웃을 위해 "최근 메모리" 사이드바 제거

• ✅ 메모리 인덱스 프로토콜 V1.2 — 표준화된 2단계 에이전트 검색 패턴

V1.1

• 그리드, 목록, 달력 보기를 갖춘 웹 대시보드

• Stdio와 함께 SSE 전송 지원

• Linux systemd 서비스 설치 프로그램

• 메모리 제목 및 타임스탬프

V1.0

• store_memory, retrieve_memory, search_memories를 갖춘 핵심 MCP 서버

• JSON 기반 지속적 저장소

• SSH 원격 전송 지원

🤝 기여하기

기여를 환영합니다. PR을 열거나, 이슈를 제기하거나, 기능을 제안해 주세요. 모든 의견을 소중하게 생각합니다.

V1.3 커뮤니티 기여자

Harbor 릴리스에 기여해 주신 모든 분께 진심으로 감사드립니다:

• @shuft — Docker 지원을 요청하는 이슈 #1 제기

• @Cyberdogs7 — PR #2: 초기 Docker 및 Docker Compose 구현

• @frehov — PR #3: Dockerfile, pyproject.toml, uv 지원, __init__.py 수정

• @thinkstylestudio — 커뮤니티 옹호

☕ 프로젝트 후원

ContextKeep이 시간, 토큰 또는 정신 건강을 지켜주었다면 커피 한 잔을 후원해 주세요.