cavemem: 코딩 어시스턴트를 위한 에이전트 간 지속적 메모리

🪨 Caveman Ecosystem ·
caveman talk less ·
cavemem remember more (현재 위치) ·
cavekit build better ·
cavegemma weights remember

코딩 어시스턴트(Coding assistants)를 위한 에이전트 간 지속적 메모리(Cross-agent persistent memory). 세션 경계에서 훅(Hooks)이 실행되며, caveman 문법을 사용하여 관찰 내용(observations)을 압축하고(산문 토큰 약 75% 감소, 코드와 경로는 바이트 단위로 보존), 로컬 SQLite에 기록합니다. 에이전트는 세 가지 MCP 도구를 통해 자신의 이력을 쿼리합니다. 네트워크 없음. 클라우드 없음.

지원 대상: Claude Code · Cursor · Gemini CLI · OpenCode · Codex

세션 간 지속적 메모리. 훅이 발생한 일을 포착하고, 저장소(store)가 이를 유지합니다.
저장 시 압축. 결정론적(Deterministic)인 caveman 문법을 사용하며, 인간이 읽을 수 있도록 왕복(round-trip)이 보장된 확장을 지원합니다.
점진적 MCP 검색. search, timeline, get_observations — 에이전트가 데이터를 가져오기 전에 먼저 필터링합니다.
하이브리드 검색. SQLite FTS5 키워드 + 로컬 벡터 인덱스(local vector index)를 결합하고, 조정 가능한 랭커(ranker)를 사용합니다.
기본적으로 로컬 방식. 네트워크 호출이 없습니다. 설정을 통해 선택적으로 원격 임베딩(embedding) 제공자를 사용할 수 있습니다.
웹 뷰어. http://localhost:37777에서 읽기 전용 UI를 통해 세션을 인간이 읽을 수 있는 형태로 브라우징할 수 있습니다.
크로스 IDE 설치 프로그램. Claude Code, Gemini CLI, OpenCode, Codex, Cursor — 각각 하나의 명령어로 설치 가능합니다.
개인정보 보호 인식. <private>...</private> 태그는 쓰기 경계에서 제거됩니다. 경로 글로브(Path globs)를 통해 디렉토리 전체를 제외할 수 있습니다.

npm install -g cavemem
cavemem install # Claude Code
cavemem install --ide cursor # cursor | gemini-cli | opencode | codex
...

시작해야 하는 데몬(daemon)은 없습니다. 훅은 동기적으로 기록됩니다. 첫 번째 훅이 실행될 때 임베딩(embeddings)을 구축하기 위해 로컬 워커(worker)가 백그라운드에서 자동으로 생성되며, 유휴 상태가 되면 스스로 종료됩니다. cavemem config set embedding.autoStart false 명령으로 비활성화할 수 있습니다.

세션 이벤트 → <private> 내용 삭제 → 압축 → SQLite + FTS5
↑
요청 시 MCP 쿼리 수행

실제 압축이 어떻게 이루어지는지:

실제 압축이 어떻게 이루어지는지:

입력(Input): "The auth middleware throws a 401 when the session token expires; we should add a refresh path."
저장됨(Stored): "auth mw throws 401 @ session token expires. add refresh path."
조회됨(Viewed): "The auth middleware throws a 401 when session token expires. Add refresh path."

코드 블록(Code blocks), URL, 경로(paths), 식별자(identifiers), 버전 번호(version numbers)는 절대 수정되지 않습니다. 훅 핸들러(Hook handlers)는 150ms 이내에 완료됩니다. 전체 본문(Full bodies)은 get_observations를 통해 요청 시에만 가져옵니다.

명령(Command)	설명
cavemem install [--ide <name>]	IDE를 위한 훅(hooks) + MCP 등록
cavemem uninstall [--ide <name>]	훅(hooks) + MCP 제거
cavemem status	통합 대시보드: 연결 상태(wiring), DB 카운트, 임베딩 백필(embedding backfill), 워커 PID
cavemem config show|get|set|open	설정 보기/편집 — 스키마는 자체 문서화(self-documenting)됨
cavemem start|stop|restart	워커 데몬(worker daemon) 제어 (보통 불필요 — 자동 시작됨)
cavemem viewer	브라우저에서 메모리 뷰어(memory viewer) 열기
cavemem doctor	설치 상태 확인
cavemem search <query> [--limit N] [--no-semantic]	메모리 검색 (BM25 + 코사인 재순위화 (cosine re-rank))
cavemem compress <file>	caveman 문법으로 파일 압축
cavemem reindex	FTS5 + 벡터 인덱스(vector index) 재구축
cavemem export <out.jsonl>	관찰 내용(observations)을 JSONL로 덤프
cavemem mcp	MCP 서버 (stdio) 시작

점진적 공개(Progressive disclosure): search와 timeline은 압축된 결과를 반환하며, get_observations는 전체 본문을 가져옵니다.

도구(Tool)	반환값 (Returns)
search(query, limit?)	[{id, score, snippet, session_id, ts}] — BM25 + 선택적 코사인 재순위화 (cosine re-rank)
timeline(session_id, around_id?, limit?)	[{id, kind, ts}]
get_observations(ids[], expand?)	전체 본문, 기본적으로 확장(expanded)된 상태로 반환
list_sessions(limit?)	[{id, ide, cwd, started_at, ended_at}]

~/.cavemem/settings.json

키 (Key)	기본값 (Default)	설명
dataDir	"~/.cavemem"	SQLite 위치
compression.intensity	"full"	lite / full / ultra
compression.expandForModel	false	모델에게 확장된 텍스트를 반환할지 여부
embedding.provider	"local"	local / ollama / openai
workerPort	37777	로컬 뷰어 포트
search.alpha	0.5	BM25 / 벡터 (vector) 혼합 비율
search.defaultLimit	10	기본 결과 개수
privacy.excludePatterns	[]	절대 캡처하지 않을 경로

<private>...</private> 내부의 콘텐츠는 기록 전 제거됩니다. excludePatterns와 일치하는 경로는 절대 읽히지 않습니다. 워커 (worker)는 127.0.0.1에만 바인딩됩니다.

네 가지 도구. 하나의 철학: 에이전트가 더 적은 것으로 더 많은 것을 수행하도록 (agent do more with less).

리포지토리 (Repo)	역할	한 줄 요약
caveman	출력 압축 기술 (Output compression skill)	적은 것으로도 충분한데 왜 많은 토큰을 사용하는가 — Claude Code, Cursor, Gemini, Codex 전반에서 출력 토큰 약 75% 절감
cavemem (현재 위치)	에이전트 간 지속적 메모리 (Cross-agent persistent memory)	에이전트가 기억할 수 있는데 왜 잊어야 하는가 — 압축된 SQLite + MCP, 기본적으로 로컬 환경 지원
cavekit	명세 기반 자율 빌드 루프 (Spec-driven autonomous build loop)	에이전트가 알 수 있는데 왜 추측해야 하는가 — 자연어 → 키트 (kits) → 병렬 빌드 → 검증
cavegemma	caveman 쌍 데이터로 파인튜닝된 Gemma 4 31B	매 턴 프롬프트를 넣어야 하는데 왜 가중치 (weight)가 기억하지 못하는가 — HF 상의 LoRA + 병합된 bf16, 시스템 프롬프트 불필요

이들은 상호 보완적입니다: cavekit이 빌드를 오케스트레이션하고, caveman이 에이전트가 말하는 것을 압축하며, cavemem이 에이전트가 기억하는 것을 압축하고, cavegemma는 이 압축 기술을 모델 가중치에 내장합니다. 하나만 설치하거나, 일부를 설치하거나, 모두 설치할 수 있으며 — 각각은 독립적으로 작동합니다.

Revu— FSRS 간격 반복 (spaced repetition) 기능을 갖춘 로컬 우선 macOS 학습 앱. revu.cards

MIT