Claude-Mem은 Claude Code 환경에서 AI 에이전트의 영구적인 메모리 및 컨텍스트 관리를 위한 시스템이다. 이 시스템의 핵심 목표는 Claude의 코딩 세션 전반에서 발생하는 모든 활동을 자동으로 캡처하고, 이를 지능적으로 압축하여 AI 모델의 과거 작업에 대한 지식을 다음 세션에도 일관성 있게 유지하도록 돕는 것이다.

핵심 방법론 (Core Methodology):
Claude-Mem은 Claude의 에이전트 작업 흐름에 통합되어, tool usage observations을 자동으로 포착하고, 이를 semantic summaries로 압축하며, 관련 컨텍스트를 향후 세션에 주입하는 방식으로 작동한다. 이 과정은 다음과 같은 주요 구성 요소를 통해 구현된다:

1. 라이프사이클 훅 (Lifecycle Hooks): SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd와 같은 6개의 훅 스크립트를 활용하여 Claude 세션의 특정 시점에 데이터를 캡처한다. 특히 PostToolUse 훅은 Claude가 도구를 사용한 후의 관찰 결과를 기록하는 데 중요하게 사용된다.
2. 워커 서비스 (Worker Service): Bun 런타임에 의해 관리되는 HTTP API 서버로, localhost:37777 포트에서 Web Viewer UI를 제공하며 10개의 검색 엔드포인트를 통해 메모리 접근을 관리한다.
3. 데이터베이스 시스템 (Database System):
   • SQLite: 세션, 관찰 기록(observations), 요약(summaries) 등의 영구적인 데이터를 저장하는 데 사용된다. FTS5 확장을 통해 효율적인 전문 검색(full-text search)을 지원한다.
   • Chroma Vector Database: AI 에이전트의 문맥 검색을 위해 hybrid semantic + keyword search를 구현하는 데 활용된다. 이는 사용자의 자연어 쿼리에 대한 의미론적 유사성을 기반으로 관련 컨텍스트를 검색하는 데 필수적이다.
4. mem-search 스킬: Claude가 자연어 쿼리를 사용하여 과거 기록을 검색할 수 있도록 하는 기능으로, Progressive Disclosure 원칙에 따라 토큰 비용을 최소화하면서 관련 정보를 점진적으로 노출한다.

MCP 검색 도구 (MCP Search Tools):
Claude-Mem은 token-efficient한 3단계 작업 흐름을 통해 메모리 검색을 최적화한다. 이는 AI 모델에 주입되는 컨텍스트의 양을 효과적으로 제어하여 비용을 절감하는 핵심 메커니즘이다:

5. search: 사용자의 쿼리에 가장 관련성이 높은 압축된 인덱스(compact index)를 반환한다. 각 결과는 고유 ID를 포함하며, $\approx 50-100$ 토큰으로 구성되어 빠른 개요를 제공한다.
6. timeline: 특정 관찰 기록(observation) 또는 쿼리 주변의 시간 순서 컨텍스트를 제공하여, 사건의 흐름을 파악하는 데 도움을 준다.
7. get_observations: 이전 단계에서 식별된 특정 ID에 대해서만 전체 관찰 기록 세부 정보($\approx 500-1,000$ 토큰/결과)를 가져온다. 이 방식은 필요한 정보만 상세하게 로드함으로써, 불필요한 토큰 소비를 최소화하여 약 10배의 토큰 절약 효과를 가져온다.

주요 기능 (Key Features):

• Persistent Memory: 세션 간 컨텍스트를 보존한다.
• Progressive Disclosure: 토큰 비용 가시성을 제공하며 계층적으로 메모리를 검색한다.
• Skill-Based Search: mem-search 스킬을 통해 프로젝트 기록을 자연어로 쿼리할 수 있다.
• Web Viewer UI: localhost:37777에서 실시간 메모리 스트림을 확인할 수 있다.
• Privacy Control: $<private>$ 태그를 사용하여 민감한 내용을 저장소에서 제외할 수 있다.
• Automatic Operation: 수동 개입 없이 자동으로 작동한다.
• Citations: 과거 관찰 기록을 ID로 참조할 수 있다.
• Beta Channel: Endless Mode와 같은 실험적인 기능을 제공한다.

시스템은 Node.js, Claude Code, Bun, uv, SQLite 3를 필요로 하며, 설정은 ~/.claude-mem/settings.json 파일을 통해 관리된다. 라이선스는 AGPL-3.0을 따르며, ragtime/ 디렉토리는 PolyForm Noncommercial License 1.0.0으로 별도 라이선스된다.