AI 에이전트의 기억을 지우지 마세요 — hippocampus-mcp라는 개인용 메모리 기반을 만들었습니다

대화 로그는 창을 닫는 순간 증발한다

Claude Code나 Codex CLI, ChatGPT를 매일 사용하다 보면 이런 경험이 쌓여갑니다.

• 지난주에 디버깅했던 PostgreSQL의 데드락, 원인과 회피책을 에이전트와 함께 찾아냈는데 벌써 기억이 나지 않는다
• "이 라이브러리의 이 함정, 전에 빠진 적이 있었지"라고 생각해도 어느 세션이었는지 찾아낼 수 없다
• 에이전트에게 "지난번에 이걸로 실패했으니까 다른 방법으로 해줘"라고 매번 똑같은 주의사항을 다시 입력해야 한다

과거의 추론, 의사결정, 디버깅 기록은 컨텍스트 윈도우 (Context Window)를 닫는 순간 사라집니다. 다음 세션의 에이전트는 어제의 당신이 무엇을 배웠는지 전혀 모릅니다. 매일 아침, 기억상실증에 걸린 동료와 업무를 재개하는 것과 같습니다.

hippocampus-mcp는 이 "증발"을 막기 위해 만든 개인용 메모리 기반입니다. 여러 플랫폼의 대화 로그를 직접 운영하는 PostgreSQL + pgvector에 가져오고, 이를 임의의 에이전트 세션에서 MCP 검색 도구로서 불러올 수 있게 합니다.

동일한 문제 의식을 가진 프로젝트는 다른 곳에도 있습니다. Anthropic 공식 Memory MCP 서버나 mem0와 같은 호스팅형 서비스가 그 대표적입니다. hippocampus의 입장은 조금 다르며, 데이터를 자신의 서버에서 완전히 유지하면서, 여러 에이전트 간에 규칙이나 지견을 공유하는 ghost layer를 갖는 것을 중시합니다.

이 기사는 핸즈온 도입 기사가 아니라, 설계 사상 ── 특히 이 시스템의 차별점인 ghost layer ── 를 중심으로 소개합니다.

이름에 대하여 — 왜 "해마"인가

해마 (hippocampus)는 수면 중에 단기적인 경험을 장기 기억으로 정착시키는 뇌의 구조입니다. 이 시스템은 그 루프를 의도적으로 모방하고 있습니다.

주간: 세션이 JSONL로서 축적됨 (단기 기억) -
야간: cron으로 실행되는 ingest가 그것들을 임베딩 (embedding) 하여 영속화함 (기억의 정착) -
익일: 다음 세션이 그것을 회상할 수 있음 (장기 기억으로부터의 검색) -

"낮에 쌓고, 밤에 굳히고, 다음 날 불러온다" ── 이 consolidation 루프 자체가 설계의 뼈대가 됩니다.

전체상 — 3개의 작동 부품과, 유일한 공유 상태

구조는 심플합니다. 작동하는 부품은 3개뿐이며, 공유 상태는 데이터베이스 1개뿐입니다.

ingest CLI가 Postgres에 기록한다 -
MCP server가 Postgres에서 읽는다 -
embed boundary (후술)가 양측을 위해 텍스트를 벡터로 변환한다

ingest와 serving은 직접 대화하지 않습니다. 유일한 접점은 데이터베이스입니다. 이러한 느슨한 결합 (loose coupling)은 한쪽이 다운되어도 다른 한쪽이 망가지지 않는 운영상의 안심을 줍니다.

데이터는 3개의 Postgres 스키마로 나뉩니다.

— 대화 코퍼스 본체. 스레드 단위의 personal conversations, 턴 단위의 messages, 긴 대화 도중에 묻힌 화제도 포착할 수 있게 하는 conversation_segments. 모두에 halfvec(1024)의 dense 벡터 열이 붙어, 스레드 전체·메시지·세그먼트의 각 입도(granularity)로 의미 검색을 할 수 있다. -
— ghost layer. 다음 장에서 상세히 설명. agent -
— 임의의 외부 참조 미디어 (서적, 전사 데이터 등). 기본적으로는 생성되지 않으며, 테이블이 존재하지 않으면 서버는 "없는 것"으로 취급한다. library

어느 워크스페이스에서도 불러올 수 있게 됩니다. 이것이 cross-project agent memory 입니다.

에이전트 스스로가 「학습」을 기록한다

ghost layer의 가장 특징적인 사용법은, LLM 스스로가 메모리를 기록하는 운용 방식입니다.

claude-harness (Claude Code의 메모리 관리 확장)와 결합하면, 에이전트는 세션 중에 발견한 반복되는 실패 패턴이나 실수하기 쉬운 포인트를 그 자리에서 memory file로서 기록할 수 있습니다. 그것이 nightly dub을 통해 ghost layer로 승격되어, 다음 날 세션 시작 시 자동으로 회상됩니다.

[세션 중 실패 경험]
↓
[에이전트가 memory file을 기록]
...

이는 「경험으로부터 학습하는 AI 에이전트」를 외부의 fine-tuning이나 특별한 학습 파이프라인 없이, 파일 시스템과 PostgreSQL만으로 구현합니다.

실제로 기록되는 메모리 파일은 다음과 같은 형태입니다:

---
name: "sops -d 를 stdout으로 출력해서는 안 된다"
scope: shared
...

LLM 스스로가 이 파일을 쓰고, allowlist에 추가하며, 다음 날 아침 dub 됩니다. 다음 세션부터는 ghost layer가 이 규칙을 문맥에 따라 주입합니다 ── 자기 개선 루프 (self-improvement loop) 의 완성입니다.

왜 「opt-in dual-signal」인가

에이전트의 메모리에는 특정 프로젝트 고유의 민감한 정보가 섞이기 쉽습니다. 이를 무조건 모든 프로젝트로 유출하는 것은 사고의 원인이 됩니다. 따라서 promotion (공유 저장소로의 승격)은 default-deny로 설정되어 있습니다. 승격에는 독립된 두 가지 시그널이 모두 충족되어야 합니다.

• 메모리 파일의 frontmatter에 scope: shared가 붙어 있음
• 인간이 수동으로 편집하는 allowlist 파일에 해당 메모리가 열거되어 있음

이 두 가지를 모두 만족해야만 비로소 야간 dub이 해당 메모리를 저장소로 복사합니다. 여기에 더해 content scanner가 세 번째 벽으로서 승격 대상의 내용을 검사합니다. 「마킹 누락」도 「allowlist 추가 누락」도, 한쪽만으로는 아무 일도 일어나지 않는 ── 이중 안전장치입니다.

자기 기록 루프와 결합하면, 「LLM이 작성한 메모리가 인간의 리뷰 없이 모든 프로젝트로 확산되는」 사태를 구조적으로 방지할 수 있습니다. LLM은 쓸 수 있지만, 승격시킬지 여부는 인간이 결정합니다.

읽기는 최소 권한 + 감사 로그

ghost layer의 읽기는 전용 최소 권한 Postgres 역할 (role) 을 경유합니다. 그리고 모든 읽기 작업은 단 하나도 빠짐없이 append-only 방식의 감사 로그 (ghost_read_log) 에 기록됩니다. 「무엇이・언제・어느 세션에서 호출되었는지」를 나중에 추적할 수 있도록 설계되었습니다.

search_ghost_memory의 랭킹은 저장된 시그널 점수 (activation / endorsement / correction), 최신성 (recency), 그리고 embed backend가 있는 경우 의미적 유사도를 혼합합니다. 유용하게 사용된 메모리는 activation이 올라가며, 시간이 지남에 따라 상위로 부상합니다 ── 사용할수록 효과가 커지는 설계입니다.

기술적인 관전 포인트 — 「단 하나의 불변 조건」을 물리화하기

설계에서 가장 마음에 드는 부분입니다.

이 시스템에서는 Postgres에 닿는 dense 벡터는 반드시 L2 정규화(L2 normalization)가 완료된 엄격한 1024차원이어야 합니다. 왜냐하면 모든 dense 열이 halfvec_ip_ops의 HNSW 인덱스 (단위 벡터 상의 내적 = 코사인 유사도)를 사용하기 때문입니다. 이 조건이 어긋나면 검색 기능이 조용히 망가집니다.

이 불변 조건을 코드 전체에 흩어진 「관례」로서 지키게 하는 것이 아니라, 단 하나의 초크포인트 (chokepoint) 에 집약했습니다. 그것이 바로 EmbedClient라는 embed boundary입니다. encode() / encode_batch()의 모든 리턴 경로에서 정규화와 차원을 assert(단언)합니다.

서버의 쿼리도, ingest(수집)도, ghost 검색도 ── 벡터를 만드는 모든 생산자 (producers) 가 이 하나의 클라이언트를 경유합니다. 그렇기에 halfvec_ip_ops라는 스키마상의 전제가 코드베이스 어딘가에서 조용히 드리프트(drift)하는 일이 구조적으로 발생할 수 없습니다. N개의 호출 지점을 리뷰하는 대신, 하나의 경계(boundary)를 리뷰하면 됩니다.

이러한 집약의 이점은 미래에도 유효합니다. embed의 차원 수 변경이나 backend(백엔드) 교체가 필요해졌을 때, 수정은 EmbedClient 한 곳에서 완결됩니다.

embed backend는 명시적으로 선택했을 때만 활성화됩니다. 조용한 모델 다운로드도, 조용한 폴백(fallback)도 없습니다. backend를 하나도 설정하지 않은 설치 환경에는 embed backend가 없으며, 의미 검색(semantic search) 도구는 단순히 제공되지 않는다 ── 라는 깔끔한 절단입니다.

Capability gating — 존재하는 것만 노출하기

MCP 서버는 backing(백킹)이 존재하는 도구만 등록합니다. 기동 시 _gate_tools()가 데이터베이스와 설정을 프로브(probe)하여, backing이 되는 스키마, 역할(role), embed backend가 누락된 도구를 목록에서 제외합니다.

• personal 계열 도구는 personal 스키마를 요구함
• search_library는 library 스키마를 요구함
• search_ghost_memory는 ghost reader 역할과 함수를 요구함
• 의미 검색 도구는 embed backend 설정을 요구함

이 프로브는 일시적인 장애 시에는 fail open 합니다 (DB가 잠시 다운되더라도 도구 목록이 깜빡거리며 사라지지 않음). 반면 구조적으로 누락된 backing의 도구는 숨깁니다. personal-only의 깨끗한 설치 환경이, 첫 호출 시 실패할 ghost / library 도구를 처음부터 광고하지 않는 동작입니다. stdio든 SSE든 동일한 gating이 작동합니다.

프라이버시 태도 — 두 가지 "아키텍처상의" 성질

자세한 내용은 PRIVACY.md에 맡기겠지만, 아키텍처로서 언급해야 할 성질이 두 가지 있습니다.

• 추출된 내용은 "데이터"이지 "명령"이 아니다. 각 도구는 검색 결과를 명시적으로 "신뢰할 수 없는 참조 자료로 취급하라"는 봉투에 담아 전달합니다. 오래된 대화 텍스트에 포함된 지시 사항에 소비 측의 LLM이 따라버리는 것(prompt injection)을 방지하기 위함입니다.
• 자격 증명(credential)의 스크러빙(scrubbing)은 ingest 시의 best-effort(최선 노력)이다. 수집 시에 스크러빙하고, 추출 시에도 두 번째 새니타이즈(sanitization)를 거치지만, 보장하는 것은 아닙니다. 로그 중의 시크릿(secret)을 줄일 수는 있어도, 제로로 만들 수는 없다 ── 이 한계를 솔직하게 명시하고 있습니다.

그리고 대원칙으로서, 당신의 대화 텍스트 전문과 그 벡터는 당신의 PostgreSQL 안에 있습니다. Anthropic 기반의 스코어링/요약이나 원격 embed 엔드포인트 등, 그것을 필요로 하는 기능을 명시적으로 활성화하지 않는 한, 아무것도 머신 외부로 나가지 않습니다.

셋업(Setup)의 핵심

기본적으로 모든 것이 자신의 머신 위에서 동작합니다. 데이터베이스는 동봉된 docker-compose postgres를 사용하며, hippocampus init이 번거로운 작업을 처리합니다 (DB 패스워드 생성, .env를 mode 0600으로 쓰기, compose 기동, 마이그레이션, MCP 등록 스니펫 출력까지).

먼저 리포지토리를 클론하고 패키지를 설치합니다.

git clone https://github.com/hrmtz/hippocampus && cd hippocampus
# 1. 패키지 설치
pip install .

그 다음 첫 셋업을 실행합니다. DB 백엔드(기본값은 "local")와 embed 백엔드를 여기서 선택합니다.

# 2. 첫 셋업 (DB는 "local"이 기본값, embed backend를 선택)
hippocampus init

의미 검색 (Semantic Search)을 사용하는 경우에는 동봉된 BGE-M3 서버를 실행합니다 (init 단계에서 bge-http를 선택한 경우에만 필요).

# 3. 의미 검색용으로 동봉된 BGE-M3 서버 실행 (init에서 bge-http를 선택한 경우)
docker compose --profile bge up -d

마지막으로 동작 확인을 마친 후, 대화 로그를 가져옵니다 (ingest).

# 4. 검증 후 Claude Code 세션 가져오기
hippocampus doctor
hippocampus ingest claude-code

가져올 수 있는 소스는 4가지입니다 ── Claude Code (~/.claude/projects/를 자동 감지하여 차이점만 가져오기), ChatGPT / claude.ai의 공식 내보내기(export) ZIP, Codex CLI 이력. 모든 소스는 동일한 파이프라인(parse → credential scrub → embed → upsert → verify)을 거치며, 마지막 verify 단계에서 벡터가 붙지 않은 행이 단 하나라도 있다면 강력하게 경고하며 실패합니다. "검색은 되는데 벡터가 없는" 식의 어중간한 상태를 남기지 않도록 설계되었습니다.

MCP 서버 등록은 settings.json에 스니펫을 추가하기만 하면 됩니다. 시크릿(secret)은 스니펫에 포함되지 않습니다 (서버가 작업 디렉토리의 .env를 읽습니다).

{
"mcpServers": {
"hippocampus": {
...

그 후 새로운 세션에서 다음과 같이 호출할 수 있습니다.

search_personal_memory("저 postgres 데드락 건")
list_recent_conversations(days=2)
search_ghost_memory(current_project="my-repo") # ghost layer가 활성화된 경우

포지셔닝 — "제품"이 아닌 "인프라"

마지막으로 솔직한 말씀을 드립니다. 이것은 기술 지원이 제공되는 제품이 아니라, 유용한 인프라로서 공개하는 것입니다. 제작자 본인이 매일 사용하는 드라이버(driver)로서의 기억 시스템을 설치 가능한 형태로 추출한 것입니다. Issue / PR은 환영하며 최선을 다해(best-effort) 대응하겠지만, SLA(서비스 수준 협약)나 로드맵에 따른 커밋은 없으며, 마이너 버전 간에 API가 변경될 수도 있습니다.

그럼에도 불구하고 ── "어제의 에이전트가 배운 것을 오늘의 에이전트가 기억해낼 수 있다"는 경험은, 한 번 맛보면 되돌아갈 수 없습니다. 대화 로그가 증발하는 것에 짜증을 느껴본 적이 있는 사람이라면, 이 메커니즘은 금방 손에 익을 것입니다.

링크

• 리포지토리: https://github.com/hrmtz/hippocampus
• ARCHITECTURE.md — 코드에 기반한 전체 구조
• INSTALL.md — 상세 셋업
• PRIVACY.md — 무엇이 저장되고, 언제 무엇이 외부로 나가는가
• GHOST_LAYER_USER.md — ghost layer 사용자 가이드

Discussion