Claude Code를 위한 영구 기억 시스템을 직접 만들었다 — Tsuzuri for Claude Code

세션을 종료하면 Claude는 모든 것을 잊어버립니다

Claude Code는 우수하지만, 세션을 종료하면 대화의 문맥을 모두 잊어버립니다.

며칠 전에 "이 방식으로 가자"라고 결정했을 텐데, 새로운 세션에서는 아무것도 기억하지 못합니다. 매번 똑같은 설명을 다시 해야 합니다. 결정 사항이 다시 논의됩니다. 오래 사용할수록 이 "건망증"은 스트레스가 됩니다.

그래서 로컬 완결·무료·일본어 대응 영구 기억 시스템을 직접 만들었습니다. 그것이 바로 Tsuzuri(綴り) 입니다.

"Tsuzuri(綴り)"는 흩어진 대화를 하나의 실로 엮어 문맥을 꿰맨다는 의미를 담고 있습니다.

기존 도구들의 불만 사항

"Claude Code memory"로 검색하면 이미 많은 도구가 나옵니다. mem0, Letta, Zep, 각종 claude-memory 계열 리포지토리… 군웅할거의 시대입니다.

하지만 자신의 용도로 사용하려고 하면 모두 걸리는 점이 있었습니다.

일본어 검색이 약함— 해외 제품은 토크나이저(Tokenizer)가 영어를 전제로 하여, 일본어 전체 텍스트 검색(Full-text search) 및 의미 검색(Semantic search)의 정밀도가 나오기 어려움 -
API 과금이 발생함— 임베딩(Embedding)에 OpenAI API 등을 사용하면 대화가 늘어날수록 비용이 증가함 -
클라우드로 전송됨— 업무 문맥이나 코드를 외부 서비스에 맡기고 싶지 않음

"일본어로·무료로·로컬에서 완결되는" 것이 필요했습니다. 없다면 직접 만든다는 생각으로 제작했습니다.

설계 사상: 3가지 원칙

Tsuzuri는 다음 세 가지에 집중했습니다.

로컬 완결— 데이터는 SQLite에 저장. 의미 검색도 Ollama로 로컬 실행. 외부 전송 제로 -
무료— API 과금 없음. 추가적인 pip / npm 의존성도 거의 제로(표준 라이브러리 중심) -
일본어 대응— SQLite FTS5의 trigram 토크나이저 + 일본산 임베딩 모델 Ruri

그리고 가장 큰 특징은 설치 후에는 아무것도 할 필요가 없다는 점입니다. Claude Code의 hooks를 사용하여 대화를 자동으로 저장하고, 다음 실행 시 자동으로 주입합니다.

구조

전체상

[대화] ──UserPromptSubmit/Stop hook──▶ [SQLite에 자동 저장]
│
[새 세션] ◀──SessionStart hook── [요약을 자동 주입]
...

Claude Code의 hooks (UserPromptSubmit / Stop / SessionStart)에 작은 Node.js / Python 스크립트를 연결해 두었을 뿐입니다.

2층 메모리

기억을 "항상 떠올리는 것"과 "필요할 때 파헤치는 것"으로 나누었습니다.

Tier1 (주입)— handoff.md (인수인계 메모)와 project-state.md (영구 정보)를 세션 시작 시 반드시 주입. "항상 머릿속에 있는 기억" -
Tier2 (검색)— 과거의 생 로그(Raw log)를 SQLite FTS5로 전체 텍스트 검색. "기억해내기 위해 파헤치는 기억"

모든 것을 매번 주입하면 컨텍스트(Context)를 과도하게 소모하므로, 요약만 상시 주입하고 상세 내용은 검색을 통해 가져오는 구조입니다.

고안 1: blob 분리로 검색 정밀도 향상

대화에는 자연문뿐만 아니라 코드 블록이나 스택 트레이스(Stack trace), 방대한 로그가 섞여 있습니다. 이것들을 그대로 임베딩 벡터(Embedding vector)로 만들면 노이즈가 되어 검색 정밀도가 떨어집니다.

그래서 대화 본문을 "대화 텍스트"와 "코드/로그 blob"으로 분리했습니다.

// memory-blob.js 보다 (발췌)
function splitBlobs(content) {
// 1) ``` 펜스(fence)가 있는 코드 블록을 추출
// 2) 연속되는 쉘 커맨드/JSON/스택 트레이스/로그 행을 묶어서 blob화
// → text(대화만)와 blobs(코드/로그)로 나눔
return { text, blobs };
}

의미 검색의 임베딩 대상은 **text(대화만)**입니다. 반면 전체 텍스트 검색(FTS5)과 상세 표시에는 전체 내용을 남겨두므로, 정보를 잃지 않으면서 신호(Signal)만 높일 수 있습니다.

...

node .claude/hooks/memory-distill.js # 처리되지 않은 대화 요약 표시
node .claude/hooks/memory-remember.js decision # 결정을 구조화하여 추가
node .claude/hooks/memory-remember.js bug # 버그 수정을 구조화하여 추가

내용 해시(Content Hash)를 통해 중복을 자동으로 스킵하므로, 동일한 내용을 중복해서 기록하지 않습니다. 그리고 의미 검색(Semantic Search)의 임베딩(Embedding) 대상을 '생 로그(Raw Log)'가 아닌 '이 구조화된 메모리'로 향하게 함으로써, 검색의 신호 품질(Signal Quality)을 더욱 높였습니다.

...

ollama pull kun432/cl-nagoya-ruri-large
export MEMORY_EMBED_PROVIDER=ollama
python3 .claude/hooks/memory-search.py "曖昧な質問でも意味で探す" --hybrid

키워드(FTS5)와 의미(임베딩)를 **RRF(Reciprocal Rank Fusion)로 융합한 하이브리드 검색(Hybrid Search)**도 가능합니다. 그리고 중요한 점은, Ollama를 설치하지 않아도 동작한다는 것입니다. MEMORY_EMBED_PROVIDER

...

node install.js

이로써 .claude/hooks/

...

node .claude/hooks/memory-distill.js
node .claude/hooks/memory-remember.js decision
node .claude/hooks/memory-mark-processed.js

검색하고 싶을 때는 이것을 사용합니다.

# 키워드 검색 (추가 의존성 없음, 일본어 OK)
python3 .claude/hooks/memory-search.py "검색어"
# 의미 검색 (Ollama 필요)
python3 .claude/hooks/memory-search.py "검색어" --hybrid

향후 계획

현재는 '영구 기억의 코어'가 완성된 단계이며, 다음과 같은 확장을 고려하고 있습니다.

• sbx (Docker Sandbox) ↔ 호스트의 기억 동기화 — Claude Code를 Docker 컨테이너 내부에서 실행하여 작업한 기억을 호스트 측에 공유하는 메커니즘. 현재는 sbx 내부에서도 깨지지 않고 동작하도록 대응해 두었으며, 동기화 자체는 앞으로 구현할 예정입니다.
• 글로벌 설치를 통한 모든 프로젝트 횡단 메모리 — ~/.claude/ 측에 두어 프로젝트를 넘나들며 기억할 수 있도록 구현.
• 의미 검색 품질 개선 — 짧은 문장이나 정형 문구의 노이즈를 청크 분할(Chunking)이나 정형 문구 제거를 통해 감소.

"우선 동작하는 코어를 내놓고 반응을 보며 키워나간다"는 방침이므로, 요청이 있다면 우선순위를 높여 구현하겠습니다.

마치며

Tsuzuri는 "Claude Code에 기억을 갖게 하고 싶다"는 개인적인 불만에서 시작된 프로젝트이지만,

• 로컬 완결 · 무료 · 일본어 대응 - 설치 후에는
• 자동으로 기억 - 추가 의존성이 거의 없고, 의미 검색은
• 원하는 사람만

이라는 구성으로, 비슷한 고민을 가진 분들에게 도움이 되길 바라며 공개했습니다. MIT 라이선스입니다.

"세션을 닫을 때마다 Claude가 기억을 잃는 것이 은근히 괴롭다"고 느끼시는 분들은 꼭 한번 시도해 보세요. 피드백, Issue, Star를 기다리고 있습니다 🧠

Discussion