Claude Imprint
Claude에게 영구 메모리(persistent memory), 다중 채널 메시징(multi-channel messaging), 그리고 자동화 기능을 부여하는 자체 호스팅 시스템입니다. Claude Code, Claude.ai, 또는 Telegram을 통해 대화해도 모든 것을 기억하고 채널 간에 컨텍스트를 공유합니다. 다른 채널(Discord, Slack 등)은 해당 MCP 서버를 통해 추가할 수 있습니다.
⚠️ 보안 공지 (2026년 10월). 이 리포지토리는 2026년 5월에 구축되었습니다. 만약 그때 Claude.ai 통합(imprint-memory --http)을 설정했다면, 다음 명령어로 업그레이드하세요: pip install -U imprint-memory (0.4.1+).
- 이전 버전의 imprint-memory는
127.0.0.1에서 오는 모든 요청이 토큰 검사를 건너뛰게 했습니다. Cloudflare Tunnel은 실제 클라이언트 IP를 전달하므로, 아래 설정은 잠겨 있었지만, 일반 TCP 포워더(frp, ssh -R, socat, port-forward 서비스)는 외부의 모든 요청을 로컬처럼 보이게 만듭니다. 0.4.1은 항상 토큰을 요구하며, 토큰 없이는 HTTP 모드로 시작하지 않습니다.
- imprint-memory 0.1.0 / 2026년 5월 17일 이전의 git 설치는 자격 증명이 설정되지 않았을 때 누구나 접근할 수 있게 했으며, 로컬 Claude Code를 구동할 수 있는
cc_execute 도구를 포함했습니다. 만약 이 중 하나를 노출했다면, 업그레이드하고 메모리가 읽힐 수 있다고 가정하세요.
cron-task.sh는 --dangerously-skip-permissions 옵션으로 Claude Code를 실행합니다. 이러한 프롬프트가 읽는 모든 것(웹 페이지, 이메일, 메시지)을 조종할 수 있으므로, cron 프롬프트는 신뢰할 수 있는 입력에만 사용하세요.
단순히 영구 메모리만 원하나요? 메모리 시스템은 독립적인 패키지입니다: imprint-memory. pip install로 단독 설치할 수 있으며, 전체 Imprint 스택이 필요하지 않습니다. 이 리포지토리는 다중 채널 메시징, 자동화, 대시보드 등 모든 것을 추가합니다.
기능
🧠 메모리
- 하이브리드 검색 (Hybrid search) — FTS5 전체 텍스트(full-text) + bge-m3 벡터 임베딩(vector embeddings) + 정확 일치 키워드를 결합하고, RRF 순위 지정 및 시간 감쇠 점수화로 통합합니다. Claude Code의 내장 파일 기반 메모리를 대체합니다.
- CJK 지원 — 중국어/일본어/한국어 텍스트를 jieba로 분할하여 정확한 전체 텍스트 검색을 수행합니다.
- 인터페이스 전역 통일성 (Unified across interfaces) — 동일한 SQLite 백엔드가 Claude Code (stdio MCP)와 Claude.ai (Cloudflare Tunnel을 통한 HTTP MCP)에 서비스를 제공합니다. 한 곳에 저장된 메모리는 다른 곳에서도 즉시 검색할 수 있습니다.
- 카테고리별 저장소 (Categorized storage) — 메모리를 유형(사실, 이벤트, 작업, 경험) 및 출처로 태그 지정합니다. 카테고리별로 검색하거나 하이브리드 검색이 최적의 일치를 찾도록 할 수 있습니다.
- 지식 은행 (Knowledge bank) — Markdown 파일(
memory/bank/)에 구조화된 장문 지식을 저장합니다. 선호도, 관계, 기술 경험 등 모든 것이 인덱싱되어 시맨틱 검색에 포함됩니다.
- 일일 로그 (Daily logs) — 자동 일일 저널을 작성합니다. 사전 압축 훅(Pre-compaction hooks)은 컨텍스트가 압축되기 전에 이를 포착합니다. 아무것도 손실되지 않습니다.
- Starlog — 모든 창에 걸친 하루의 타임라인입니다. 대화 세션이 끝날 때마다 작은 모델이 1인칭 문장(
14:20 [telegram] …)을 작성하고, 매 30분마다 이 문장들을 짧은 단락으로 직조하여, 다른 창에서 본 동일한 이벤트가 병합됩니다. 새로운 세션은 오늘 다른 창들이 무엇을 했는지 알고 시작합니다.
💬 다중 채널
- Telegram (주요) — 모든 기능 지원: 채팅, 파일 공유, 활동 알림(heartbeat notifications), 아침 브리핑, Claude.ai를 통한 직접 메시징. Anthropic의 공식 Claude Code Telegram 플러그인을 사용합니다.
- Claude.ai — Cloudflare Tunnel + OAuth를 통해 연결. 웹 및 모바일 앱에서 전체 메모리에 접근할 수 있습니다.
- 교차 채널 컨텍스트(Cross-channel context) — 모든 소스에서 메시지가 유입됩니다. Claude는 어디서 무슨 일이 일어났는지 공유 타임라인을 유지합니다. 기기를 전환해도 이미 컨텍스트를 알고 있습니다.
- 플러그인 가능 채널(Pluggable channels) — 시스템이 모든 Claude Code 채널 플러그인(Discord, Slack 등)을 자동으로 감지합니다. MCP 서버만 설치하면 메시지가 자동으로 기록되고, 태그가 지정되며, 검색할 수 있게 됩니다.
🎮 원격 제어 (Remote Control) (다음 항목 필요: 채팅 통합 + 추가 MCP 패키지)
- 직접 Telegram 메시징 — Claude.ai가 Bot API를 통해 사용자의 Telegram으로 전송합니다.
imprint_telegram MCP가 필요합니다 (설정은 Telegram 설정 참조).
- 시스템 모니터(System monitor) — CPU, RAM, 디스크, 실행 중인 서비스를 확인합니다.
imprint_utils MCP가 필요합니다.
- 웹페이지 리더(Webpage reader) — 모든 URL을 가져와 읽습니다.
imprint_utils MCP가 필요합니다.
- Spotify 제어 — 재생, 일시 정지, 건너뛰기, 볼륨 조절.
imprint_utils MCP가 필요합니다. macOS 전용 (AppleScript).
⚡ 자동화(Automation)
- 예약 작업(Scheduled tasks) — 아침 브리핑, 알림, 야간 메모리 통합. 사용자 지정 가능한 cron 프롬프트 템플릿을 제공합니다.
- 활동 에이전트(Heartbeat agent) — 타이머에 따라 사용자의 라이브 Telegram 세션을 깨웁니다 (tmux를 통해 맥박 신호를 전송). 따라서 확인하는 Claude는 대화하던 바로 그 Claude이며, 전체 컨텍스트가 유지됩니다. 세션이 없는 경우 일회성 헤드리스 실행으로 대체됩니다.
- 훅(Hooks) — 사전 압축 컨텍스트 저장소 + 자동 압축을 포함한 응답 후 대화 기록기.
📊 대시보드(Dashboard)
- 제어판(Control panel) — 단일 파일 FastAPI 앱 (localhost:3000). 서비스 시작/중지, 메모리 탐색, 예약 작업 보기, 대화 스트림 통계 및 GitHub 스타일의 상호작용 히트맵을 제공합니다.
Dashboard
플랫폼 지원
| 기능 | macOS | Linux / 클라우드 |
|---|
| 메모리 시스템, 대시보드, 훅(hooks), 크론(cron) | ✅ | ✅ |
| ... | | |
클라우드 서버 배포
핵심 기능들(메모리, HTTP 서버, 대시보드, Telegram, 하트비트, cron)은 Linux 클라우드 서버에서 작동합니다. Claude Code는 CLI 도구로 실행되며 — 기본적인 VPS (CPU 1개, RAM 1GB)만으로 충분합니다; AI 추론은 사용자님의 서버가 아닌 Anthropic의 서버에서 이루어집니다.
git clone https://github.com/Qizhan7/claude-imprint.git && cd claude-imprint
python3 -m venv .venv && source .venv/bin/activate
...
프로덕션 배포의 경우, systemd 서비스 템플릿이 deploy/에 제공됩니다. 전체 지침은 deploy/README.md를 참조하세요.
전제 조건 (Prerequisites)
- Python 3.10 이상 (imprint-memory의 타입 힌트 구문 필요)
- Claude Code (Pro 또는 Max 구독)
- macOS 또는 Linux
빠른 시작
git clone https://github.com/Qizhan7/claude-imprint.git
cd claude-imprint
...
이제 Claude Code에 영구 메모리가 생겼습니다. 더 많은 기능을 원하시면 아래 모듈들을 추가하세요.
모듈 (Modules)
채팅 통합 (Claude.ai → 로컬 메모리)
Cloudflare Tunnel + HTTP MCP를 통해 Claude.ai를 로컬 메모리에 연결하세요.
python3 scripts/generate_oauth.py
...
Cloudflare Tunnel(또는 클라이언트 IP를 포워딩하는 모든 것)을 사용해야 합니다. imprint-memory 0.4.1 이상이 필요하며; 이전 버전에서는 일반 TCP 포워더가 토큰을 우회합니다.
Telegram
claude /telegram:configure
./start.sh
```bash
python3 packages/imprint_heartbeat/agent.py
...
펄스가 작동하는 방식: 에이전트는 짧은 [Heartbeat · <시간>] 메시지(현재 시간 + 사용자의 HEARTBEAT.md 체크리스트)를 채널 세션에 붙여넣고 Enter 키를 누릅니다. Claude는 이를 다른 턴처럼 처리하며, 전체 대화 내용을 컨텍스트로 유지하고, 답변할 내용이 있을 때만 Telegram 답장 도구를 통해 메시지를 전송합니다. 만약 세션이 권한 프롬프트 상태라면, 이 틱은 건너뛰어 펄스가 절대로 사용자 대신 대화에 응답하지 않도록 합니다. Hooks는 펄스를 사용자의 메시지가 아닌 heartbeat로 기록합니다.
Cron은 빈 환경에서 실행됩니다: cron-task.sh는 프로젝트의 .venv/bin을 PATH에 추가하고(IMPRINT_VENV로 재정의), ~/.claude/cron-token에서 장기 토큰을 읽어옵니다(claude setup-token으로 생성 가능).
Cron 템플릿: morning-briefing.md, drink-water.md, health-check.md, nightly-consolidation.md, weekly-memory-audit.md. 사용자의 스타일에 맞게 편집하고 crontab으로 일정을 잡으세요.
참고: send_telegram 또는 system_status를 사용하는 템플릿은 전체 MCP 설정이 필요합니다. 러너는 cron-mcp-full.json(텔레그램 + 유틸리티 포함)을 감지하면 자동으로 사용하고, 그렇지 않으면 cron-mcp.json(메모리만)으로 폴백(fallback)합니다.
Hooks
~/.claude/settings.json에 추가하세요 (/path/to/claude-imprint를 대체):
{
"hooks": {
"PreCompact": [{ "hooks": [{ "type": "command", "command": "bash /path/to/claude-imprint/hooks/pre-compact-flush.sh" }] }],
...
PreCompact는 압축(compaction) 전에 컨텍스트를 저장합니다. Stop은 매 턴을 기록하고 starlog에 피드하며, SessionStart는 새로운 세션마다 오늘의 starlog를 전달합니다. Hooks는 프로젝트의 .venv/를 자동으로 가져오거나(IMPRINT_VENV 설정 가능), 사용할 수 있습니다.
Starlog
위의 Stop 및 SessionStart hooks가 필요합니다. 파일은 ~/.imprint/starlog/에 위치합니다:
timeline-2026-10-20.md raw lines, one per stretch of conversation
-
14:20 [telegram] 친구 생일 케이크로 말차 바스크 치즈케이크를 계획함
-
14:31 [cc·my-app] 로그인 리다이렉트 루프 수정됨; 테스트 통과
...
-
Lines는 Stop hook에서 가져옵니다. 충분한 새 텍스트(400자)가 쌓이고 최대 10분마다 창당 한 줄씩 있을 때, claude -p --model haiku를 사용하여 한 문장을 요청합니다. 이는 자체 구독으로 작동하며, 도구(tools), MCP 또는 저장된 세션이 필요하지 않습니다. hooks가 로그인 정보를 볼 수 없다면, ~/.claude/cron-token을 사용합니다.
-
Arranging은 매 심장 박동(heartbeat) 전에 실행되거나 cron에서 실행됩니다: */30 * * * * cd /path/to/claude-imprint && .venv/bin/python packages/imprint_starlog/starlog.py arrange. 이전 단락들은 고정되어 있으며, 가장 최근의 단락만 남아 있는 내용을 흡수하여 수정될 수 있습니다. 모델 호출이 실패하면, 라인들은 원본 상태로 유지됩니다.
-
New sessions는 오늘 날짜의 단락들, 어제 남은 부분, 그리고 아직 직조되지 않은 라인들(예산 STARLOG_INJECT_CHARS, 기본값 8000)을 가져옵니다. 장시간 실행되는 Telegram 세션은 각 심장 박동 주기마다 다른 창의 새 라인을 받습니다.
-
python3 packages/imprint_starlog/starlog.py show는 오늘 날짜를 출력합니다. 하루는 STARLOG_DAY_START(기본값 오전 5시)에 시작하므로, 늦은 밤도 같은 날로 계산됩니다. STARLOG_DISABLE=1을 설정하면 이 기능이 비활성화됩니다.
다른 채널 추가하기 (Discord, Slack 등)
시스템은 모든 Claude Code 채널 플러그인을 자동으로 감지합니다. 코드 변경이 필요하지 않으며 — 채널 MCP를 설치하기만 하면 모든 것이 작동합니다:
- 채널의 MCP 서버 설치 (예: 커뮤니티에서 제공하는 Discord MCP)
.mcp.json에 imprint-memory와 함께 등록- 채널과 imprint-memory를 모두 로드하여 Claude Code 시작
자동으로 작동하는 기능:
- 메모리 —
memory_remember, memory_search 등이 즉시 작동합니다.
- 대화 기록(Conversation logging) — 응답 후크(post-response hook)가 채널 이름을 감지하여 모든 메시지에 올바른 플랫폼(예:
discord) 태그를 지정합니다.
- 교차 채널 컨텍스트(Cross-channel context) — 메시지가
recent_context.md와 CLAUDE.md AUTO 섹션에 표시되며, 다른 모든 채널에서도 볼 수 있습니다.
- 검색 — 모든 플랫폼의 경우
conversation_search(query)를 사용하고, 특정 플랫폼의 경우 search_channel(query, "discord")를 사용합니다.
- 대시보드 — 스트림 통계가 새로운 플랫폼을 자동으로 표시하며, 알 수 없는 플랫폼은 중립적인 색상 태그를 받습니다.
- RRF 하이브리드 검색 — 모든 플랫폼에서 작동하며 설정이 필요 없습니다.
의미론적 검색(Semantic search) (선택 사항)
ollama pull bge-m3 && ollama serve
이것 없어도 키워드 검색은 여전히 작동합니다. 다만 벡터 유사도는 얻을 수 없습니다.
설정(Configuration)
| 변수 | 기본값 | 설명 |
|---|
IMPRINT_DATA_DIR | ~/.imprint | memory.db 및 파일의 디렉토리 |
| ... | | |
| imprint-memory에서 메모리 관련 설정을 확인하세요 (임베딩 제공자, 모델 등). | | |
Claude 사용자 정의하기(Customizing your Claude)
이 시스템은 몇 가지 Markdown 파일에 의해 형태를 갖춥니다. 전체 가이드는 **docs/customization.md**를 참조하세요.
간단 요약:
| 파일 | 기능 | 작성자 |
|---|
~/.claude/CLAUDE.md | 개성, 선호도, 규칙 — 두뇌 | |
| 당신 | | |
| ... | | |
감사의 글(Acknowledgements)
imprint-memory · Anthropic · Ollama + bge-m3
라이선스
