Zikkaron

Zikkaron(זיכרון)은 히브리어로 "기억"을 뜻합니다.

당신의 AI는 탭을 닫을 때마다 당신을 잊어버립니다. 당신이 설명했던 모든 아키텍처 결정, 함께 헤쳐 나갔던 모든 디버깅 토끼굴, "기억해, 우리는 SQLite가 아니라 Postgres를 쓰고 있어"라는 모든 수정 사항. 모두 사라집니다. 다음 세션을 시작할 때 당신은 자신의 도구에게 낯선 사람이 되어 있습니다.

Zikkaron은 계산 신경과학에 기반한 Claude Code용 영구 메모리 엔진입니다. 당신이 무엇을 작업했는지, 어떻게 생각하는지, 무엇을 결정했고 왜 그랬는지를 기억합니다. 컨텍스트에 밀어 넣는 단순한 텍스트 덤프가 아니라, 통합하고 지능적으로 망각하며 적절한 때에 올바른 컨텍스트를 재구성하는 살아있는 메모리 시스템입니다.

26개의 하위 시스템. 24개의 MCP 도구. 전적으로 당신의 머신에서 실행됩니다. SQLite 파일 하나.

같은 말을 다시 하지 않게 되는 2분

pip install zikkaron

Claude Code 설정에 추가하세요:

{
  "mcpServers": {
    "zikkaron": {
      "command": "zikkaron"
    }
  }
}

Claude에게 사용법을 알려주세요. 전역 ~/.claude/CLAUDE.md(프로젝트별이 아닌 홈 디렉토리)에 다음을 넣으세요:

## Memory
- On every new session, call `recall` with the current project name
- Before starting any task, call `get_project_context` for the current directory
- After completing significant work, call `remember` to store decisions and outcomes

아니면 그냥 Zikkaron이 처리하게 하세요. 시작할 때마다 sync_instructions를 통해 ~/.claude/CLAUDE.md를 최신 지침과 자동으로 동기화합니다. 한 번 설정해 두면 다시는 신경 쓸 필요가 없습니다.

Related MCP server: memory-mcp

실제로 어떤 느낌인가

월요일. 당신은 까다로운 인증 토큰 경쟁 조건(race condition)을 디버깅하는 데 한 시간을 보냅니다. Claude가 Redis와 JWT 설정 사이의 TTL 불일치까지 추적하는 것을 돕습니다. 당신은 고칩니다. Claude는 그 기억을 저장합니다.

목요일. 사용자가 간헐적 로그아웃을 보고합니다. 같은 프로젝트에서 Claude Code를 엽니다. 버그를 설명하기도 전에 Claude는 월요일의 Redis TTL 수정을 회상하고, 관련이 있는지 확인한 다음, Redis가 세션 중간에 재시작되는 엣지 케이스를 당신이 추가한 미들웨어가 처리하고 있는지 물어봅니다.

그것이 차이입니다. "여기 당신의 대화 기록이 있습니다"가 아닙니다. 진짜 회상입니다. 당신의 도구가 단순히 지난번에 입력한 단어가 아니라 당신이 구축해 온 것의 형태를 이해하는 그런 종류의 회상입니다.

실제로 작동하는 검색

우리는 Zikkaron을 LoCoMo(Maharana 외, ACL 2024)로 테스트했습니다. 긴 대화 메모리의 표준 벤치마크입니다. 10개의 대화, 1,986개의 질문, 단순한 사실 조회부터 다중 홉 추론, 당신을 속이기 위해 설계된 적대적 함정 질문까지 모든 것이 포함됩니다.

중요한 점은, 쿼리 시점에 실행되는 LLM이 없다는 것입니다. API 호출도 없고, 수십억 파라미터 모델도 없습니다. 단지 22MB 임베딩 모델, SQLite 파일, 그리고 무거운 작업을 수행하는 신경과학 알고리즘들뿐입니다. 이런 수치를 달성하는 대부분의 시스템은 GPT-4를 루프에 넣어야 합니다. Zikkaron은 Hopfield 에너지 스코어링, 확산 활성화, 그리고 교차 인코더 리랭커로 이 수치에 도달합니다.

BEAM: 1,000만 토큰의 대화, 하나의 메모리 시스템

BEAM(Tavakoli 외, ICLR 2026)은 존재하는 가장 어려운 장기 메모리 벤치마크입니다. 각각 1,000만 토큰에 달하는 10개의 대화. 10가지 메모리 능력에 걸친 200개의 탐색 질문. 여기에는 이전 벤치마크가 테스트하지 않은 세 가지(모순 해결, 사건 순서화, 지시 따르기)가 포함됩니다.

논문의 모든 시스템은 이 규모에서 붕괴합니다. 보고된 최고 결과(Llama-4-Maverick에서 실행되는 LIGHT 프레임워크)는 0.266을 기록합니다. 대부분의 능력은 1,000만 토큰에서 거의 0으로 떨어집니다. 컨텍스트 윈도우 접근 방식은 맞출 수 없습니다. RAG 접근 방식은 노이즈에 빠져 죽습니다.

Zikkaron은 전체 0.404를 기록하여 ICLR 2026 논문의 최고 시스템보다 52% 개선되었습니다.

10가지 능력 중 7가지가 발표된 최신 기술 수준을 능가합니다. 가장 큰 개선은 구조화된 메모리가 가장 도움이 되어야 하는 능력에서 정확히 발생합니다: 모순 해결(+226%), 시간적 추론(+133%), 지식 업데이트(+73%). 이는 논문의 모든 시스템이 거의 0점을 기록하는 능력입니다. 컨텍스트 윈도우 접근 방식에는 사실이 어떻게 변하는지 또는 사건이 언제 발생했는지 추적하는 메커니즘이 없기 때문입니다. Zikkaron의 열역학적 감쇠, 재통합, 시간적 메타데이터가 이를 기본적으로 처리합니다.

LIGHT가 이기는 세 가지 능력(기권, 사건 순서화, 요약)은 진정한 한계를 반영합니다. 기권은 정보가 없을 때 이를 인식해야 하며, 이는 무엇이 논의되었는지 명시적으로 추적하는 LIGHT의 스크래치패드의 이점을 받습니다. 사건 순서화는 올바른 사건을 검색하는 것뿐만 아니라 완벽한 연대기적 순서화를 요구합니다. 요약은 많은 소스 구절을 동시에 검색해야 하며, 우리의 검색 예산은 관련 콘텐츠의 일부만을 다룹니다.

한 가지 중요한 주의 사항: BEAM 논문의 기준선은 리더 모델로 GPT-4.1-nano를 사용합니다. 우리는 훨씬 더 강력한 Claude Opus 4.6을 사용합니다. 지시 따르기 결과(검색 MRR이 0.086에 불과한데 0.750)는 리더 품질이 검색 품질과 독립적으로 QA 점수에 기여함을 보여줍니다. 우리의 검색 지표(MRR 0.422, Recall@10 0.353)는 모델 독립적이며 논문의 기준선과 직접 비교할 수 있습니다.

벤치마크 구성: BEAM-10M 분할, 10개 대화, 200개 질문, 논문의 RAG 모드와 일치하는 쌍-청크 수집, 논문의 평가 코드와 일치하는 int() 캐스트를 사용한 루브릭별 이진 너겟 점수, 사건 순서화를 위한 scipy의 Kendall tau-b, 대화별 새 데이터베이스.

해마 재생: 압축에서 살아남는 컨텍스트

아무도 이야기하지 않는 문제가 있습니다. Claude Code에는 200k/1M 토큰 컨텍스트 윈도우가 있습니다. 긴 세션 중에 그 윈도우가 가득 차면 압축이 발생합니다: 오래된 메시지를 요약하고, 도구 출력을 제거하고, 당신의 지시를 의역합니다. 중요한 뉘앙스가 증발합니다. 대화 초반에 고정한 결정은 모호한 요약으로 녹아내립니다.

해마 재생(Hippocampal Replay) 이 이를 해결합니다. 뇌가 수면 중에 중요한 경험을 재생하여 장기 기억으로 통합하는 신경과학 현상에서 이름을 따왔으며, 컨텍스트 압축을 "수면"으로 취급하고 Claude가 "깨어날" 때 중요한 것을 재생합니다.

작동 방식:

압축이 발생하기 전에 훅이 발화합니다. Zikkaron이 활성 컨텍스트를 배출합니다: 무엇을 작업 중이었는지, 어떤 파일이 열려 있었는지, 어떤 결정을 내렸는지, 어떤 오류가 해결되지 않았는지. 이 모든 것을 체크포인트로 저장합니다.

압축 후에 두 번째 훅이 발화합니다. Zikkaron이 컨텍스트를 지능적으로 재구성합니다. 모든 것을 다시 덤프하는 것이 아니라 올바른 조각을 조립합니다: 최신 체크포인트, 중요하다고 고정한 사실, 가장 뜨거운 프로젝트 메모리, 그리고 사용 패턴에 기반한 다음에 필요할 것에 대한 예측.

중요한 것을 명시적으로 지정할 수도 있습니다:

Tool: anchor
  content: "We're using the event-sourcing pattern. All state changes go through the event bus."
  reason: "Architecture constraint"

고정된 메모리는 최대 보호를 받습니다. 어떤 경우에도 압축에서 항상 살아남습니다.

프로젝트당 일회성 설정:

Tool: install_hooks
  project_directory: "/path/to/your/project"

그 후에는 모든 것이 자동입니다. 생각할 필요도 없고, 수동으로 호출할 필요도 없습니다. 훅이 발화하고, 컨텍스트가 배출되고, 컨텍스트가 복원됩니다. 긴 세션이 그냥... 작동합니다.

제로 갭 메모리 (v1.3.0)

이전 버전에는 여전히 갭이 있었습니다. 한 시간 동안 점진적으로 진행하면서 작업했는데, Zikkaron의 쓰기 게이트가 각각의 작은 단계가 이전 단계에 비해 "놀랍지 않게" 보여서 절반을 차단했습니다. 중요한 아키텍처 결정을 내렸는데 그것이 천천히 요지로 붕괴했습니다. 새 세션으로 돌아왔을 때 Claude는 방금 무엇을 하고 있었는지 전혀 몰랐습니다.

v1.3.0은 이 모든 것을 수정합니다:

적응형 쓰기 게이트. 시스템은 이제 마지막 10개의 저장된 메모리를 추적합니다. 같은 작업(같은 디렉토리, 같은 시간대, 유사한 콘텐츠)을 명확히 하고 있을 때 놀라움 임계값을 낮추어 점진적 진행이 통과되도록 합니다. 게이트는 여전히 노이즈를 차단합니다. 단지 당신의 작업을 차단하지 않을 뿐입니다.

결정 자동 보호. "Redis를 Memcached 대신 사용하기로 결정했습니다" 또는 "CRUD 대신 이벤트 소싱 패턴을 선택했습니다"라고 말하면 Zikkaron이 결정 패턴을 감지하고 자동으로 보호됨으로 표시합니다. 보호된 메모리는 절대 압축되지 않고 빠르게 감쇠하지 않습니다. 당신의 결정은 세션보다 오래갑니다.

자동 작업 캡처. PostToolUse 훅이 Claude가 만드는 모든 단일 도구 호출 후에 발화합니다. 파일 편집, bash 명령, 검색 — 모두 가벼운 작업 로그에 캡처됩니다. 통합 데몬이 주기적으로 이를 실제 메모리로 처리합니다. 일상적인 작업에 remember를 호출할 필요가 없습니다. 시스템이 그냥 압니다.

세션 컨텍스트 주입. SessionStart 훅이 모든 새 세션에서 발화하고 프로젝트 컨텍스트(뜨거운 메모리, 고정된 사실, 최근 작업, 마지막 체크포인트)를 Claude의 컨텍스트 윈도우에 직접 주입합니다. Claude는 모든 세션을 이미 무엇을 하고 있었는지 아는 상태로 시작합니다.

마이크로 체크포인팅. 50개의 도구 호출마다 체크포인트를 만드는 대신, 시스템은 이제 중요한 이벤트(발생한 오류, 내린 결정, 높은 놀라움 정보)에서 자동으로 체크포인트를 만듭니다. 중요한 상태 전환이 발생하는 순간 캡처됩니다.

세션 일관성. 마지막 4시간 내에 생성된 메모리는 선형적으로 사라지는 열 보너스를 받습니다. "10분 전에 방금 말했잖아" 문제를 다시는 겪지 않을 것입니다.

모든 훅은 stdio 및 HTTP 전송 모드 모두에서 작동합니다 — 서버 통신 없이 SQLite 데이터베이스에 직접 접근합니다.

프로젝트 시딩: 콜드 스타트 해결

Zikkaron은 세션을 거치며 유기적으로 메모리를 구축합니다. 진행 중인 작업에는 훌륭하지만, 1년 동안 작업해 온 코드베이스에 설치하면 어떨까요? Claude가 프로젝트에 대한 의미 있는 커버리지를 갖기 전에 수십 개의 세션을 보내야 할 것입니다. 그때쯤이면 이미 50번은 같은 말을 반복했을 것입니다.

seed_project가 이 문제를 해결합니다. 한 번의 호출로 Zikkaron이 전체 프로젝트를 스캔하고 구조, 설정, 문서, CI/CD, 진입점, 컴포넌트별 요약에서 기초 기억을 생성합니다. Claude는 다음 세션을 시작할 때 프로젝트가 무엇인지, 무엇으로 구축되었는지, 어떻게 구성되어 있는지 이미 알고 있습니다.

# CLI
zikkaron seed /path/to/your/project

# Preview without storing
zikkaron seed /path/to/your/project --dry-run

또는 Claude Code 내에서 MCP 도구로 호출할 수 있습니다:

Tool: seed_project
  directory: "/path/to/your/project"

추출하는 내용:

• 프로젝트 개요 — 이름, 기술 스택, 파일 수, 디렉터리 트리

• 설정 파일 — package.json, pyproject.toml, Cargo.toml, go.mod 및 15개 이상의 기타 파일. 정규식 스크래핑이 아닌 적절한 파싱(TOML은 tomllib, JSON은 json)을 통해 처리됩니다. 의존성, 스크립트, 워크스페이스, 빌드 백엔드 — 모두 추출됩니다.

• 문서 — README, ARCHITECTURE, CONTRIBUTING, CLAUDE.md, CHANGELOG

• CI/CD — GitHub Actions, GitLab CI, Jenkins, Travis, Azure Pipelines

• 진입점 — main.*, index.*, app.*, server.*, __main__.py

• 컴포넌트별 요약 — 모노레포 인식. 최상위 디렉터리만 보는 것이 아니라 중첩된 설정 파일(packages/web/package.json, services/api/Cargo.toml)을 찾아 하위 프로젝트 경계를 감지합니다.

재실행을 위해 설계됨. 재시딩은 기존 시드 기억에 추가하는 대신 깔끔하게 교체합니다. 프로젝트가 발전하면 재시딩하고, 기억은 현재 상태를 반영합니다. 모든 시드 기억은 식별을 위해 _seed 태그가 지정됩니다.

열 차별화. 모든 시드 기억이 동일하지는 않습니다. 프로젝트 개요와 문서는 컴포넌트 파일 목록(0.5)보다 더 높은 온도(0.85-0.9)로 시작합니다. Claude는 중요한 내용을 먼저 표시합니다.

LongMemEval

우리는 전체 LongMemEval 벤치마크(Wu et al., ICLR 2025)를 실행했습니다. 이는 채팅 어시스턴트의 장기 대화형 메모리 평가를 위한 현재 표준입니다. 6개 범주에 걸친 500개의 인간 큐레이션 질문으로, 각각 약 40개 세션의 대화 기록(약 115k 토큰)에 포함되어 있습니다. 이 벤치마크는 LoCoMo가 테스트하지 않는 것들을 테스트합니다: 어시스턴트가 말한 것을 회상할 수 있는지(사용자뿐만 아니라), 정보가 시간에 따라 변경될 때 추적하는지, 모르는 것을 아는지, 몇 주 간격으로 발생한 세션을 추론할 수 있는지.

논문의 최고 보고 검색은 이 데이터셋에서 78.4% Recall@10을 기록했습니다. Zikkaron은 검색 루프에 LLM 없이 96.7%에 도달합니다.

범주별 검색 세부 결과:

지식 업데이트는 열 기반 감쇠가 자연스럽게 동일한 사실의 이전 버전 위에 최신 정보를 밀어 올리기 때문에 완벽한 MRR을 기록했습니다. 이것은 벤치마크를 위해 설계된 것이 아닙니다. 열역학 모델이 작동하는 방식일 뿐입니다.

시간적 추론은 가장 어려운 범주이며 MRR이 0.902로 가장 낮지만, 여전히 올바른 기억이 일반적으로 상위 두 결과에 있음을 의미합니다. "몇 주 전에 X에 참석했나요?"와 같은 질문은 세션 타임스탬프와 일치해야 하며, 우리의 임베딩 기반 검색은 메모리 콘텐츠에 직접 포함된 시간적 메타데이터를 통해 이를 처리합니다.

전체 QA 평가(Claude를 리더와 판정자로 모두 사용)는 75.6%의 전체 정확도에 도달했으며, 지식 업데이트(85.9%)와 어시스턴트 회상(94.6%)에서 뛰어난 성능을 보였습니다. 다중 세션 추론(54.9%)이 주요 격차이며, 이는 검색 문제가 아니라 리더 합성 문제입니다. 우리는 다중 세션 질문에 대해 95.8%의 시간 동안 올바른 세션을 검색합니다. 리더는 그들 사이의 정보를 연결하는 데 더 많은 작업을 해야 합니다.

벤치마크 구성: LongMemEval_S 변형, 라운드 수준 메모리 분해, 질문당 새 데이터베이스, 500개 질문 종단 간 평가.

내부 과학

Zikkaron은 데이터베이스가 행을 저장하는 방식으로 기억을 저장하지 않습니다. 뇌가 경험을 처리하는 방식과 더 유사하게 취급합니다.

기억에는 온도가 있습니다. 모든 기억은 뜨겁게 시작합니다. 계속 접근하면 뜨겁게 유지됩니다. 그렇지 않으면 식습니다. 임계값 아래로 내려가면 압축됩니다: 먼저 요지로, 그다음 태그로, 결국 완전히 사라집니다. 이것은 버그가 아닙니다. 뇌가 무엇을 보관할 가치가 있는지 결정하는 데 사용하는 것과 동일한 수학적 프레임워크인 rate-distortion 최적 망각입니다. 중요한 기억은 압축에 저항합니다. 놀라운 기억은 열 부스트를 받습니다. 지루하고 중복된 기억은 조용히 사라집니다.

저장에는 게이트키퍼가 있습니다. 모든 것이 기억될 가치가 있는 것은 아닙니다. Zikkaron은 이미 알고 있는 것에 대한 예측 모델을 유지하며, 기대를 위반하는 정보만 저장합니다. 같은 것을 두 번 말하면 쓰기 게이트가 두 번째 시도를 차단합니다. 이것은 예측 코딩입니다: 신피질이 감각 입력을 필터링하는 데 사용하는 것과 동일한 메커니즘입니다. 예측 오류만 통과합니다.

검색은 기억을 변경합니다. 새로운 맥락에서 기억을 회상할 때, 수동적으로 돌려주지 않습니다. 검색 맥락을 저장 맥락과 비교하고, 불일치가 충분하면 재통합합니다: 현재 사실을 반영하도록 기억을 업데이트합니다. 심각한 불일치는 이전 버전을 보관하고 새 버전을 만듭니다. 이것은 실제 신경과학입니다. Nader et al.은 2000년에 검색된 기억이 불안정해지고 다시 쓰여질 수 있음을 보여주었습니다. 코드베이스가 진화하고, Zikkaron의 기억도 그에 따라 진화합니다.

기억은 공간을 위해 경쟁합니다. 엔그램 슬롯 풀이 있으며, 각 슬롯은 사용 시 급증하고 시간이 지남에 따라 감쇠하는 흥분성 점수를 가집니다. 새 기억이 도착하면 가장 흥분된 슬롯으로 이동합니다. 같은 슬롯의 기억은 시간적으로 연결되어, 내용이 공통점이 없더라도 관련 경험의 체인을 만듭니다. 이것은 실제 뉴런이 CREB 의존적 흥분성을 통해 엔그램을 할당하는 방식을 모델링합니다.

백그라운드 통합은 수면처럼 실행됩니다. 유휴 상태일 때, 성상세포 데몬이 깨어나 최근 경험을 처리합니다. 엔티티와 관계를 추출하고, 지식 그래프를 구축하고, 거의 중복된 항목을 병합하고, 인과 체인을 발견하고, 무작위 기억 쌍을 비교하고 새로운 연결이 나타나는 "꿈 재생"을 실행합니다. 네 개의 도메인 특화 프로세스가 서로 다른 속도로 서로 다른 유형의 지식을 처리합니다: 코드 구조, 아키텍처 결정, 오류 패턴, 의존성.

인지 지도가 모든 것을 구성합니다. 후속 표현은 개념 공간의 2D 지도를 구축하여, 내용이 완전히 다르더라도 유사한 맥락에서 접근되는 기억이 함께 클러스터링됩니다. 디버깅 기억은 다른 디버깅 기억 근처에 클러스터링됩니다. 아키텍처 결정은 함께 클러스터링됩니다. 이 지도를 탐색하면 키워드 검색으로는 절대 표면화되지 않을 관련 지식을 찾을 수 있습니다.

전체 24개 도구

아키텍처

모든 것이 로컬에서 실행됩니다. WAL 모드, FTS5 전체 텍스트 검색, 근사 최근접 이웃 벡터 검색을 위한 sqlite-vec가 있는 단일 SQLite 데이터베이스.

5개 계층으로 구성된 26개 하위 시스템:

고급 설정

소스에서

git clone https://github.com/amanhij/Zikkaron.git
cd Zikkaron
pip install -e .

SSE 전송

stdio 대신 지속적 백그라운드 서버로 실행:

zikkaron --transport sse

그런 다음 Claude Code를 URL에 연결:

{
  "mcpServers": {
    "zikkaron": {
      "type": "sse",
      "url": "http://127.0.0.1:8742/sse"
    }
  }
}

기본 포트는 8742입니다. --port로 재정의할 수 있습니다. 데이터베이스 기본값은 ~/.zikkaron/memory.db이며, --db-path로 재정의할 수 있습니다.

구성

모든 설정은 ZIKKARON_ 환경 변수 접두사를 사용합니다:

전체 목록은 zikkaron/config.py에 있습니다.

테스트

python -m pytest zikkaron/tests/ -x -q

34개 테스트 파일에 걸쳐 모든 하위 시스템을 포괄하는 998개의 테스트.

참고 문헌

Ramsauer 외. "Hopfield Networks is All You Need" (ICLR 2021, arXiv:2008.02217)

Nader, Schafe, LeDoux. "Fear memories require protein synthesis in the amygdala for reconsolidation after retrieval" (Nature 406, 2000)

Osan, Tort, Bhatt, Amaral. "Three outcomes of reconsolidation" (PLoS ONE, 2011)

McClelland, McNaughton, O'Reilly. "Why there are complementary learning systems in the hippocampus and neocortex" (Psychological Review 102, 1995)

Sun 외. "Organizing memories for generalization in complementary learning systems" (Nature Neuroscience 26, 2023)

Stachenfeld, Botvinick, Gershman. "The hippocampus as a predictive map" (Nature Neuroscience 20, 2017)

Whittington 외. "The Tolman-Eichenbaum Machine" (Cell 183, 2020)

Spirtes, Glymour, Scheines. Causation, Prediction, and Search (MIT Press, 2000)

Kanerva. Sparse Distributed Memory (MIT Press, 1988)

Frady, Kleyko, Sommer. "Variable Binding for Sparse Distributed Representations" (IEEE TNNLS, 2022)

Toth 외. "Optimal forgetting via rate-distortion theory" (PLoS Computational Biology, 2020)

Josselyn, Frankland. "Memory allocation: mechanisms and function" (Annual Review Neuroscience 41, 2018)

Rashid 외. "Competition between engrams influences fear memory formation and recall" (Science 353, 2016)

Zhou 외. "MetaRAG: Metacognitive Retrieval-Augmented Generation" (ACM Web, 2024)

라이선스

MIT