<div align="center"> <img src="https://raw.githubusercontent.com/oleksiijko/pmb/main/docs/assets/logo.png" width="100" alt="PMB logo">

PMB

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

SQLite가 진실의 근원지입니다. 클라우드도, API 키도, 재설명할 필요도 없습니다.

Website

PyPI

Docs

Python

License

MCP

GitHub MCP Registry

로컬 우선 메모리를 시각화했습니다. 작업하는 동안 자동으로 포착되는 3,800개 이상의 엔티티와 41,000개 이상의 연결 관계.

Website · Docs · 빠른 시작 · 데모 · PMB란 · 작동 방식 · FAQ

사용자의 AI 에이전트는 세션 사이에 모든 것을 잊어버립니다. 그래서 같은 결정, 교훈, 제약 사항을 반복해서 재설명해야 합니다. PMB는 이를 단일 로컬 작업 공간에 기억하고, MCP(Model Context Protocol)를 통해 다시 공급합니다. 클라우드도, API 키도, 읽기 경로에서 LLM 호출도 필요 없습니다. 그리고 단순히 '+X%'라고 주장하는 대신, 메모리가 실제로 도움이 되는 시점을 알려줍니다.

⭐ PMB가 재설명을 막아준다면 이 레포지토리에 별을 눌러주세요.

</div>

PMB는 Claude Code, Cursor, Codex 및 기타 MCP 인식 에이전트들에게 실제 메모리를 제공합니다. 즉, 지난주에 내린 결정, 가르친 교훈, 개인 정보, 프로젝트 구조, PDF 파일 등입니다. 이러한 데이터들은 사용자가 소유하는 로컬 작업 공간에 존재하며, 그곳에는 내구성이 뛰어난 진실의 근원지인 SQLite와 재구성 가능한 검색 인덱스가 함께 있어 모든 재시작, 모델 업그레이드, 에이전트 전환에도 살아남습니다.

API 키가 필요 없습니다. 구독도 필요 없고, 읽기 경로(read path)에서 LLM 호출이 발생하지 않습니다. 오직 로컬 파일만 사용합니다.

빠른 시작 (Quickstart)

pip install pmb-ai                 # 1. 설치
pmb setup                          # 2. 에이전트 감지 및 MCP 엔트리 연결
pmb warmup                         # 3. 모델 사전 로드 (첫 번째 리콜은 즉시 작동)
...

여기까지입니다. 이제 에이전트가 기억합니다. 계정, 키, 아무것도 기기를 벗어나지 않습니다.

명령어 이름: CLI는 **pmb**입니다. pip를 통해 별칭(alias)인 **pmb-ai**도 얻을 수 있습니다. npm(npx pmb-ai setup)을 사용할 경우 명령어는 pmb-ai이며, 이 명령은 먼저 Python 패키지를 설치한 다음 설정(setup)을 실행합니다. 도구 자체는 같으니, 설치 환경에 따라 둘 중 어느 것을 사용해도 됩니다.

링크: pmbai.dev (사이트) ·
docs.pmbai.dev (문서) ·
Getting started ·
Deleting memories.

데모 (Demo)

기억 유무에 따른 체감 비교 - 동일한 프롬프트로 테스트:

<sub>▶ 재생을 클릭하여 2분간의 설정을 확인하세요</sub>

You:    지난 화요일 발생했던 LoadGuard 가격 책정 버그 수정해줘

Agent:  prepare(message="fix LoadGuard pricing bug")
...

에이전트는 묻지 않았습니다. 추측하지도 않았습니다. 메모리를 6 ms 만에 읽어와 이미 정보를 알고 있는 것처럼 나타났습니다.

왜 PMB인가?

로컬 우선(Local-first), 설정 불필요(zero-config). SQLite가 영구 메모리를 저장하며, 재구축 가능한 검색 인덱스는 로컬에 유지됩니다. 계정, API 키, 원격 측정 데이터(telemetry) 또는 클라우드에 의존할 필요가 없습니다.
실제로 사용됩니다. Claude Code / Codex에서 훅(hooks)이 모델이 추론하기 전에 올바른 메모리를 주입합니다. 도구를 호출하는 것을 기억할 필요가 전혀 없습니다.
다국어 지원, 설정 불필요. 임베더(embedder)는 50개 이상의 언어를 커버하며, 러시아어 질의가 영어 사실을 찾아냅니다. 언어별 구성이 필요하지 않습니다.
MCP 네이티브. 하나의 pmb connect 명령어로 Claude Code, Cursor, Codex, Windsurf, Zed, VS Code 등과 연결됩니다.
빠른 읽기 경로(read path). 따뜻한 상태(warm)에서 검색은 약 35ms에 이루어지며, 쓰기는 밀리초(millisecond) 미만으로 반환됩니다. 기억하기 위해 LLM 호출이 필요하지 않습니다.
정직한 영향도 측정. 대시보드는 "+X%"라고 주장하는 대신, 실제로 어떤 학습이 결과 변화를 가져왔는지 보여줍니다.
당신의 데이터는 공개적으로. pmb export로 모든 것을 Markdown/JSON으로 덤프할 수 있습니다. Apache 2.0 라이선스입니다.

메모리 확인하기 (See your memory)

pmb dashboard를 실행하면, PMB가 포착한 모든 것—작업하는 과정에서 자동으로 작성된 내용—을 보여주는 로컬의 액체 유리(liquid-glass) 웹 UI가 http://127.0.0.1:8765에서 열립니다. 이 주소는 127.0.0.1에만 바인딩되므로, 아무것도 기기를 벗어나지 않습니다.

지도(Map) - 프로젝트 내 모든 개체와 연결을 실시간 그래프로 보여줍니다.

타임라인(Timeline) - 최신순으로 기록되는 일지 형태의 당신의 메모리입니다.

</div

아홉 개의 탭: Map(개체 그래프, 실시간), Timeline(프로젝트별 git-graph), Overview, Entities, Arcs(서사적 흐름), Lessons(규칙별 준수율, 사장된 학습 감지), Duplicates(인라인 병합), Performance(도구별 지연 시간), Recall(디버그 랭커).

검증된 로컬 백업 (Verified local backups)

pmb snapshot create --note "before maintenance"
pmb snapshot list
pmb snapshot verify <snapshot-id>
...

스냅샷은 커밋된 WAL 데이터와 레코드 파일 체크섬을 포함하기 위해 SQLite 온라인 백업을 사용합니다. 복원(Restore) 시 메모리를 변경하기 전에 스냅샷을 확인하고 이전 상태의 검증된 사본을 저장합니다. 스크립트에서는 pmb snapshot list --json을 사용하십시오.

범위와 제한 사항은 백업 및 복구를 참조하십시오.

저장할 수 있는 것 (What you can store)

# 변경되는 개인 정보 (시간 여행: 이전 값 보관, 절대 손실되지 않음)
record_keyed_fact("user", "city", "Warsaw")

...

PMB는 콘텐츠에 구애받지 않습니다(content-agnostic). 에이전트가 나중에 관심을 가질 텍스트라면 무엇이든 PMB가 기억하고 검색합니다.

에이전트가 얻게 되는 것 (What the agent gets back)

단일 MCP 호출인 prepare(message)는 4~16ms 이내에 적절한 수준의 상세도를 가진 필요한 정보를 반환합니다:

필드	내용
`project_context`	메시지가 프로젝트를 언급하는 경우 전체 프로젝트 개요: 핵심 사실, 교훈(따라야 할 규칙), 결정 사항, 열린 목표, 관련 엔티티, 프로젝트의 서사적 흐름
...
그 외 모든 것에는 `recall(query)` (하이브리드 검색, 35ms 준비 시간)와 docs/reference/COMMANDS.md에 있는 27개의 다른 도구들이 있습니다.

작동 방식 (How it works)

flowchart LR
    A[당신의 에이전트] -->|MCP stdio| B[PMB MCP 서버]
    B --> C[엔진]
...

Storage: 모든 영구적인 이벤트는 진실의 원천인 SQLite에 저장됩니다. 재구축 가능한 벡터 인덱스는 그 옆의 LanceDB에 존재합니다. 전체 작업 공간은 디스크에 유지되며 언제든지 복사하거나 내보낼 수 있습니다.
Recall: BM25(어휘적) + 밀집 벡터(의미론적) + 개체 그래프 + 선택적 크로스 인코더 재순위화(rerank), 이를 Reciprocal-Rank-Fusion을 통해 융합합니다.
Writes: 비동기적입니다. MCP 도구는 밀리초(millisecond) 미만으로 응답하며, 임베딩 및 LanceDB 삽입은 백그라운드 스레드에서 처리됩니다.
Dedup: 네 가지 계층으로 구성됩니다: 정확한 텍스트 일치 -> 코사인 유사도 >= 0.92 자동 병합 -> 코사인 유사도 0.80-0.92 경계값 (LLM이 나중에 검증) -> 대시보드에서의 수동 검토. 오래된 값은 삭제되지 않고 아카이브되며, keyed_fact_as_of(t)를 통해 전체 기록을 확인할 수 있습니다.
Multilingual: 언어 팩이 필요 없습니다. 기본 임베더(paraphrase-multilingual-MiniLM-L12-v2)는 50개 이상의 언어를 지원하므로, где я живу(내가 사는 곳)라는 질의가 user.city = Warsaw로 저장된 키 값(keyed-fact)을 찾습니다. 의도 감지(Intent detection)는 여러 언어에 걸쳐 전이되는 영어 의미론적 앵커를 이용하며, 콜드 어휘 경로(cold lexical path)는 사용자의 트래픽으로부터 자체 컴파일됩니다. 검색 성능은 약 11개 언어에서 강력하게 유지됩니다 (101개 질의 평가에서 top-3 ~= 0.9; en/fr/pt/ru에서 top-1 = 1.00). docs/contributing/adding-a-language.md를 참조하십시오.

설치(Install)

위에 있는 빠른 시작(Quickstart)만으로 대부분의 사람이 필요합니다. 다른 방법들:

# 소스에서 클론
git clone https://github.com/oleksiijko/pmb.git && cd pmb
python -m venv .venv && source .venv/bin/activate
...

하나 이상의 에이전트(모두 stdio 방식 - 서버는 사용자의 에이전트의 자식으로 실행됨; 네트워크, 포트, 토큰 없음)를 연결합니다:

pmb connect claude-code   # 또한: codex · cursor · windsurf · gemini · vscode · zed · opencode · continue

여러 에이전트를 하나의 메모리에 연결합니다:

pmb connect claude-code --workspace personal
pmb connect cursor      --workspace personal   # 둘 다 동일한 작업 공간을 읽기/쓰기

여러 기기나 팀 전체에서 하나의 메모리를 공유하는 것이 필요한가요? 이는 bearer-token 인증을 사용하는 선택적 HTTP 모드입니다. docs/guide/TEAM.md를 참조하세요. 로컬 사용에는 필요하지 않습니다.

테스트 실행 방법은 무엇인가요? venv의 Python을 사용하세요: .venv/bin/python -m pytest (Windows에서는 .venv\Scripts\python.exe -m pytest). venv 외부에서 pytest만 사용하는 경우, 단순히 numpy/fastmcp/typer가 누락되었음을 보고할 뿐입니다.

CLI 치트 시트

# 메모리
pmb stats                                   카운트 및 저장소 정보 표시
pmb recall "쿼리"                          전체 디버그 검색
...

에이전트별 단계별 사용법: docs/guide/usage.md. 전체 참조: docs/reference/COMMANDS.md.

후크 (Hooks) - 질문을 기다리지 않는 메모리

에이전트 메모리의 어려운 부분은 저장하는 것이 아니라, 에이전트가 저장된 것을 사용하도록 만드는 것입니다. 규칙 파일의 소프트한 지침은 건너뛰어집니다. 따라서 PMB는 프로토콜 수준에서 후크를 연결합니다 (pmb hooks install claude-code). 각 후크는 모델이 행동하는 것을 기억해야 하는 의존성을 제거합니다.

UserPromptSubmit -> auto-recall. 모든 메시지는 분류되며 (정규표현식(regex), 다국어(multilingual), 서브-MS(sub-ms)), 일치하는 메모리—교훈, 과거 결정, 회상 기록, 프로젝트 개요—가 모델이 추론하기 전에 주입됩니다. 사소한 메시지는 아무것도 주입하지 않습니다.
PostToolUse -> ambient observe. 에이전트가 실행하는 모든 도구는 경량 액션 저널(action journal)에 추가됩니다 (단일 SQLite INSERT, 모델 사용 안 함). 읽기(Reads)와 목록 보기(ls)는 필터링되며, 편집(edits), 테스트(tests), 커밋(commits)은 유지됩니다.
SessionStart -> session-restore. 컨텍스트 압축(context compaction) 후, 에이전트는 사용자에게 다시 묻지 않고 세션에 기록된 내용을 바탕으로 '어디까지 했는지'를 재구축합니다.
Stop -> follow-through + ambient auto-write. (a) 실제로 나타난 교훈 중 에이전트가 수행한 작업에서 확인된 것을 점진적으로(deterministically) 체크하고, 이를 완료된 것으로 표시합니다. (b) 만약 에이전트가 record_* 도구를 호출하지 않았다면, 관찰된 행동들로부터 하나의 활동 항목을 합성하여 기록합니다. 따라서 에이전트가 침묵하더라도 실제 작업 내용이 포착됩니다.

에이전트 없이 미리보기: pmb auto-context "...", pmb session-restore -m 180, pmb lesson-followcheck --dry-run, pmb autowrite --dry-run.

주변 메모리(Ambient memory) - 쓰기 측면

Auto-recall은 읽기 측면을 개선했고, 주변 메모리는 쓰기 측면에 대해 동일한 작업을 수행합니다. 즉, 에이전트가 record_batch를 잊어버릴 때에도 에이전트의 작업 내용을 기록하는 저널링(journaling) 역할을 합니다.

협응성(Coordinated). 에이전트가 이미 이번 턴에 record_* 도구를 호출했다면, ambient는 침묵을 지키고; 오직 빈틈만 채웁니다.
변경량이 아닌 결과 기반(Outcome-scored, not churn). 턴은 단순히 파일 수로 기록되는 것이 아니라, 결과가 품질 기준(테스트 통과, 실패 수정, 배포 실행 등)을 충족했을 때만 저널링됩니다.
투명하고 되돌릴 수 있음(Honest + reversible). 모든 ambient 항목은 source=autowrite 태그가 지정되며, 대시보드에서는 auto로 표시되고, pmb forget-auto를 통해 제거할 수 있습니다. 기본적으로 활성화되어 있으며, pmb config set autowrite.enabled false로 비활성화할 수 있습니다.
모든 호스트에서 작동합니다. Claude Code(hooks), Codex(pmb codex-notify), Cursor/Zed/VS Code와 같은 MCP 전용 호스트(git observer, pmb ambient-watch .)에서도 작동합니다. 사용 가능한 기능은 pmb hooks capabilities로 확인하세요.

PMB - AI 코딩 에이전트를 위한 로컬 우선 메모리 시스템

요약

핵심 포인트

PMB

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

SQLite가 진실의 근원지입니다. 클라우드도, API 키도, 재설명할 필요도 없습니다.

빠른 시작 (Quickstart)

데모 (Demo)

왜 PMB인가?

메모리 확인하기 (See your memory)

검증된 로컬 백업 (Verified local backups)

저장할 수 있는 것 (What you can store)

에이전트가 얻게 되는 것 (What the agent gets back)

작동 방식 (How it works)

설치(Install)

CLI 치트 시트

후크 (Hooks) - 질문을 기다리지 않는 메모리

주변 메모리(Ambient memory) - 쓰기 측면

댓글

PMB

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

SQLite가 진실의 근원지입니다. 클라우드도, API 키도, 재설명할 필요도 없습니다.

빠른 시작 (Quickstart)

데모 (Demo)

왜 PMB인가?

메모리 확인하기 (See your memory)

검증된 로컬 백업 (Verified local backups)

저장할 수 있는 것 (What you can store)

에이전트가 얻게 되는 것 (What the agent gets back)

작동 방식 (How it works)

설치(Install)

CLI 치트 시트

후크 (Hooks) - 질문을 기다리지 않는 메모리

주변 메모리(Ambient memory) - 쓰기 측면