Claude Engram

AI 코딩 어시스턴트를 위한 지속적 메모리 및 세션 인텔리전스. Claude Code의 라이프사이클에 후크를 걸어 실수, 결정 사항, 컨텍스트를 자동으로 추적하고, 전체 세션 기록을 마이닝하여 패턴을 표면화하고, 필요한 내용을 예측하며, 지금까지 나눈 모든 대화 내용을 검색합니다.

수동 작업이 전혀 필요 없습니다. 모든 MCP 호환 클라이언트에서 작동합니다.

주요 기능

자동화 (후크 — 호출 불필요):

• 모든 편집, 오류, 테스트 결과 및 세션 이벤트 추적

• 프롬프트에서 결정 사항 자동 캡처 ("X를 사용하자", "Y로 전환하자" 등)

• 모든 파일 편집 전 가장 관련성 높은 3개의 메모리 주입

• 과거의 실수를 반복하려 할 때 경고

• 편집 루프 감지 (진전 없이 동일한 파일을 3회 이상 편집)

• 컨텍스트 압축 시에도 유지 — 압축 전 체크포인트 생성, 압축 후 재주입

• 모든 세션 종료 후 백그라운드에서 세션 기록 마이닝

세션 마이닝 (자동, 백그라운드):

• 모든 세션 종료 후 Claude Code의 전체 대화 로그(JSONL) 파싱 — 하위 에이전트 대화(Explore, Plan, code-reviewer 등) 포함

• 구조적 분석 + AllMiniLM 의미론적 점수(오타 허용)를 사용하여 결정 사항, 실수, 접근 방식 및 사용자 수정 사항 추출

• 모든 과거 대화에 대한 검색 가능한 인덱스 구축 (하위 에이전트 포함 2만 개 이상의 청크)

• 반복되는 어려움, 오류 패턴 및 파일 편집 상관관계 감지

• 편집 전 필요한 파일 및 컨텍스트 예측

• 로컬 LLM을 사용하여 패턴을 성찰하고 근본 원인 및 아키텍처 통찰력 합성

• 최초 설치 시 전체 세션 기록을 소급하여 마이닝

온디맨드 (MCP 도구):

• memory — 메모리 저장, 검색, 보관 및 관리

• session_mine — 과거 대화 검색, 결정 사항 찾기, 파일 기록 재생, 패턴 감지

• work — 추론과 함께 결정 사항 및 실수 기록

• 기타: 범위 보호, 컨텍스트 체크포인트, 규칙 추적, 영향 분석

Related MCP server: Doclea MCP

작동 방식

Claude Code
 |
 +-- Hooks (remind.py) <- Intercepts every tool call
 | SessionStart / Edit / Bash / Error / Compact / Stop
 |
 +-- Session Mining (mining/) <- Background intelligence
 | JSONL parser -> Extractors -> Search index -> Pattern detection
 |
 +-- MCP Server (server.py) <- Tools for manual operations
 | memory, session_mine, work, scope, context, ...
 |
 +-- Scorer Server (scorer_server.py) <- Persistent AllMiniLM process
 TCP localhost, ~90MB RAM, batch embeddings

후크는 모든 도구 호출 시 실행됩니다(각 1-2초 예산). 무거운 처리는 세션 종료 후 백그라운드 하위 프로세스에서 발생합니다. 스코어러 서버는 빠른 의미론적 점수 계산을 위해 메모리에 상주합니다.

벤치마크

통합 벤치마크

제품의 실제 기능을 테스트합니다.

재현 방법: python tests/bench_integration.py, bench_session_mining.py, bench_obsidian_vault.py

검색 벤치마크

검색 전용(recall@k) — 상위 결과에 올바른 메모리가 포함되어 있는지 여부.

재현 방법: python tests/bench_longmemeval.py, bench_locomo.py, bench_convomem.py

호환성

설치

git clone https://github.com/20alexl/claude-engram.git
cd claude-engram
python -m venv venv
source venv/bin/activate # or venv\Scripts\activate on Windows

pip install -e . # Core
pip install -e ".[semantic]" # + AllMiniLM for vector search and semantic scoring

python install.py # Configure hooks, MCP server, and /engram skill

프로젝트별 설정

python install.py --setup /path/to/your/project

또는 .mcp.json을 프로젝트 루트에 복사하세요.

참고: 이 저장소의 CLAUDE.md는 engram 전용 문서이며, engram이 작동하기 위한 필수 요소는 아닙니다. 후크는 자동으로 실행되며 /engram 스킬은 필요할 때 빠른 참조를 제공합니다. 프로젝트에 이미 CLAUDE.md가 있는 경우, 그대로 유지하고 덮어쓰지 마세요. 프로젝트 규칙과 함께 engram 문서를 사용하려면 CLAUDE-ENGRAM.md(또는 유사한 이름)로 이름을 변경하여 기존 파일을 덮어쓰지 않도록 하세요. Claude는 관련이 있을 때 이를 확인합니다.

업데이트

cd claude-engram
git pull
pip install -e ".[semantic]" # Reinstall if dependencies changed
python install.py # Re-run to update hooks and /engram skill

후크와 MCP 도구는 코드 변경 사항을 즉시 반영합니다(편집 가능한 설치). Claude Code에서 MCP 서버를 다시 연결(/mcp)하여 서버 프로세스를 다시 로드하세요.

프로젝트 중간 도입

이미 프로젝트가 많이 진행되었나요? 정상적으로 설치하세요. 첫 세션에서 engram은 기존 Claude Code 세션 기록을 자동으로 감지하고 백그라운드에서 마이닝하여 모든 과거 대화에서 결정 사항, 실수, 패턴을 추출합니다. 수동 작업은 필요 없습니다.

주요 특징

메모리 시스템

• 하이브리드 검색 — 키워드 + AllMiniLM 벡터 + 리랭킹. ChromaDB를 사용하지 않습니다.

• 점수 기반 주입 — 모든 편집 전 파일 일치, 태그, 최신성, 중요도에 따라 상위 3개 메모리 주입.

• 계층형 저장소 — 핫(빠름) + 아카이브(콜드, 검색 및 복원 가능). 규칙과 실수는 절대 아카이브되지 않습니다.

• 다중 프로젝트 — 하위 프로젝트별로 메모리 범위 지정. 워크스페이스 규칙은 하위로 상속됩니다.

세션 마이닝

• 구조적 추출 — 템플릿 매칭 대신 대화 흐름(확인, 리다이렉트, 오류->수정 시퀀스, 접근 방식 변경)을 분석합니다.

• 도구 콘텐츠 인덱싱 — bash 명령 + 출력, 편집 diff, 오류 추적을 대화 텍스트와 함께 검색할 수 있습니다.

• 배치 임베딩 — 배치 TCP 프로토콜을 통해 개별 호출보다 22배 빠릅니다.

• 세션 간 검색 — 4만 4천 개 이상의 대화 청크 인덱싱, 의미론적 + 키워드 + 하이브리드 검색.

• 패턴 감지 — 세션 전반에 걸친 반복적인 어려움, 오류 패턴, 편집 상관관계.

• 예측 컨텍스트 — 편집 전, 기록에서 관련 파일 및 발생 가능한 오류를 표면화합니다.

• 프로젝트 간 학습 — 모든 프로젝트의 패턴을 집계합니다.

• 소급 부트스트랩 — 최초 설치 시 기존의 모든 세션 기록을 마이닝합니다.

• 스코어러 자동 시작 — 실행 중이지 않은 경우 필요에 따라 AllMiniLM 서버가 시작됩니다. 성능 저하가 없습니다.

라이프사이클

• 결정 사항 자동 캡처 — 구조적 패턴(확인, 리다이렉트, 명시적 선택) + 보너스로 의미론적 점수 계산.

• 실수 자동 추적 — 실패한 모든 도구에서 실수를 추적합니다. 프로젝트 파일의 오류만 기록합니다(일시적인 노이즈 필터링). 반복 편집 전 경고합니다.

• 압축 생존 — 세션 결정/실수와 함께 체크포인트를 생성하고, 압축 후 재주입합니다.

• 편집 루프 감지 — 진전 없이 동일한 파일을 3회 이상 편집할 경우 플래그를 지정합니다.

구성

재인덱싱

검색 품질이 낮거나 업데이트 후 다시 빌드하려는 경우:

python scripts/reindex.py "E:\workspace" --force # rebuild search index
python scripts/reindex.py "E:\workspace" --force --extract # also re-extract decisions/mistakes

또는 MCP를 통해: session_mine(operation="reindex", mode="bootstrap")

문서

라이브러리 북 — 설계 철학, 내부 구조, 전체 사용 가이드, API 참조, 주의 사항 및 변경 로그.

/engram — 빠른 도구 참조를 위한 슬래시 명령어 (install.py로 설치).

라이선스

MIT

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• audit_batchC
• claude_engram_statusB
• code_pattern_checkC
• code_quality_checkC
• contextA
• conventionB
• deps_mapC
• file_summarizeC