oleksiijko/pmb

Local-first persistent memory for AI coding agents (Claude Code, Cursor, Codex) over MCP. Decisions, lessons and facts live in one SQLite file on your disk. Offline, multilingual.

PMB – AI 코딩 에이전트를 위한 로컬 우선 메모리

개요 – PMB(발음은 "p-m-b")는 코드 작성 LLM 에이전트(Claude Code, Cursor, Codex, Gemini 등)에 완전히 사용자의 머신에 상주하는 영구적이고 검색 가능한 메모리를 제공하는 Python 패키지입니다. 메모리는 SQLite 데이터베이스(신뢰할 수 있는 소스)에 저장되며 LanceDB에 선택적 벡터 인덱스를 가지고, **Model-Context-Protocol (MCP)**을 통해 에이전트에 노출됩니다.

중요한 이유 – 오늘날 많은 AI 지원 코딩 도구는 프로세스가 재시작되면 모든 것을 잊어버려서 결정, 교훈 및 프로젝트 컨텍스트를 반복해야 합니다. PMB는 이러한 사실을 자동으로 캡처하여 인덱싱하고, 모델이 응답을 생성하기 전에 관련 부분을 에이전트에 다시 주입합니다. 이 모든 것이 클라우드 호출이나 API 키 없이 이루어집니다.

주요 기능 (README에 설명된 대로)

기능	얻을 수 있는 것
로컬 우선 스토리지	모든 이벤트, 사실 및 임베딩은 `~/.pmb/<workspace>/`의 SQLite 파일에 기록됩니다. 읽기에는 네트워크 트래픽이 필요하지 않으며, 쓰기는 밀리초 미만입니다.
하이브리드 리콜	쿼리는 BM25 어휘 검색, 조밀한 벡터 유사도 및 그래프 기반 확산(Reciprocal-Rank-Fusion)의 융합으로 답변됩니다. 일반적인 웜 경로 레이턴시: ~35ms(p50) 및 ~110ms(p95).
MCP 네이티브 통합	작은 MCP 서버가 에이전트의 자식으로 실행됩니다. 표준 `prepare(message)` 호출은 구조화된 페이로드(`project_context`, `lessons`, `recent_activity`, `open_goals`, `active_arcs`)를 반환합니다.
자동 수집	`pmb index project .`는 코드베이스를 스캔하고, 심볼, 임포트 및 파일 의도를 추출합니다. `pmb index pdf …`는 PDF를 추출하고 청크로 나눕니다. `pmb track …`은 커밋 의도와 모듈 목적을 기록합니다.
앰비언트(자동 쓰기) 메모리	훅은 에이전트의 도구 사용(편집, 테스트, 커밋)을 관찰하고, 에이전트가 `record_*` 도구 호출을 잊었을 때 가벼운 저널 항목을 작성합니다.
대시보드 UI	로컬 웹 UI(`pmb dashboard`)는 메모리를 엔티티 그래프, 타임라인, 교훈 영향, 중복 및 성능 통계로 시각화합니다.
다국어 임베딩	`paraphrase-multilingual-MiniLM-L12-v2`(50개 이상 언어 지원)를 사용하므로 러시아어, 프랑스어 등의 쿼리로 영어 사실을 검색할 수 있습니다.
제로 구성, 제로 비용	클라우드 계정, API 키, 구독이 필요 없습니다. 모든 데이터는 디스크에 유지되며, Markdown/JSON으로 내보낼 수 있습니다.
프라이버시 및 내보내기	비밀 정보는 쓰기 시 편집됩니다. 전체 워크스페이스를 복사하거나 Dropbox에 동기화하거나 버전 관리할 수 있습니다.
확장 가능한 구성	105개의 조정 가능한 노브; 기본적으로 25개가 노출됩니다(`pmb config list`). 고급 플래그는 `--pro` 뒤에 숨겨져 있습니다.

작동 방식 (고수준 흐름)

설정 – pip install pmb-ai && pmb setup은 대상 에이전트를 감지하고 MCP 훅을 설치합니다.
수집 – 파일, PDF, git 커밋 및 명시적인 record_* 호출이 SQLite에 기록됩니다. 임베딩은 대기열에 들어가 LanceDB에 비동기적으로 삽입됩니다.
리콜 – 에이전트가 prepare(message)를 보내면, PMB는 하이브리드 검색(BM25 + 벡터 + 그래프 확산)을 실행하고 가장 관련성이 높은 엔티티, 교훈, 최근 작업 등을 반환합니다.
앰비언트 쓰기 – 각 도구 사용 후 훅은 작업을 로그에 기록합니다. "stop" 훅은 교훈 후속 조치를 평가하고 누락된 record_* 항목을 합성할 수 있습니다.
대시보드 – UI는 엔티티 및 아크의 라이브 그래프, 이벤트 타임라인 및 진단(실제로 결과를 변경한 교훈, 도구당 레이턴시, 중복 감지)을 보여줍니다.

빠른 시작 (README에서)

pip install pmb-ai          # install the package
pmb setup                    # wire the chosen agent (Claude Code, Cursor, …)
pmb warmup                   # preload the ~450 MB embedder
# restart the agent – memory is now active
pmb stats                    # see counts of stored items
pmb recall "auth decision"   # ad-hoc terminal search
pmb dashboard                # open the local UI at http://127.0.0.1:8765

모든 명령은 pmb-ai 별칭(npm)을 통해 또는 Python 모듈로도 사용할 수 있습니다.

일반적인 사용 사례

장기 실행되는 코드베이스 – 재설명 없이 여러 세션에 걸쳐 결정, 아키텍처 규칙 및 버그 수정 근거를 유지합니다.
크로스 에이전트 연속성 – Claude Code에서 Cursor로 전환하더라도 동일한 SQLite 워크스페이스가 두 에이전트에 메모리를 제공합니다.
연구 중심 프로젝트 – PDF를 인덱싱하고 코딩하는 동안 즉시 관련 구절을 검색합니다.
팀 수준의 공유 컨텍스트 – 선택적 HTTP 모드를 사용하면 여러 개발자가 자신의 에이전트를 공통 워크스페이스로 지정할 수 있습니다(인증 보호).
교훈 영향 분석 – 대시보드는 에이전트가 실제로 어떤 "규칙"을 따랐는지 알려주어 쓸모없거나 시끄러운 교훈을 정리하는 데 도움을 줍니다.

제한 사항 및 고려 사항 (명시되거나 암시된 대로)

읽기 경로는 오프라인 전용 – 리콜 시 LLM이 호출되지 않습니다. 품질은 임베더 및 하이브리드 순위 지정에 따라 다릅니다.
임베딩 모델 크기 – 기본 다국어 MiniLM 모델(~450 MB)을 한 번 로드해야 합니다(pmb warmup).
선택적 LLM 기반 기능 – 일부 선택적 명령(pmb consolidate, 자동 쓰기 합성)은 로컬 Ollama/Claude/OpenAI 모델을 호출할 수 있지만 기본적으로 비활성화되어 있습니다.
로컬 리소스 사용 – SQLite + LanceDB 인덱스는 디스크 공간을 차지합니다. 대규모 코드베이스나 많은 PDF는 워크스페이스를 증가시킵니다.
에이전트별 훅 – 모든 이점을 얻으려면 에이전트가 MCP 훅을 지원해야 합니다. README에 지원되는 호스트(Claude Code, Cursor, Codex 등)가 나열되어 있습니다.

라이선스 및 커뮤니티

Apache 2.0 – 자유롭게 사용, 수정 및 재배포할 수 있습니다.
MCP 등록 – Model-Context-Protocol 레지스트리에 등록되어 다른 MCP 인식 도구에서 검색할 수 있습니다.
문서 및 CI – docs.pmbai.dev에 온라인 문서가 있으며, CI 배지는 각 푸시마다 테스트가 통과함을 보여줍니다.

결론

PMB는 AI 지원 개발자를 위한 구체적인 문제인 영구적이고 짧은 레이턴시의 메모리 부재를 해결하는 진정한 오픈소스 프로젝트입니다. 모든 것을 로컬 SQLite에 저장하고, 빠른 하이브리드 검색을 제공하며, MCP를 통해 인기 있는 코딩 에이전트에 자동으로 연결함으로써, 클라우드 종속성 없이 세션 간에 프로젝트 컨텍스트, 교훈 및 결정을 유지할 수 있습니다.