PMB (Personal Memory Brain) | Local first memory layer

---

PMB を使うと、Claude Code、Cursor、Codex などの MCP 対応エージェントが、先週決めたこと、教えた教訓、個人的な情報、プロジェクトの構成、PDF などを本当に記憶できます。これらは再起動しても、モデルをアップグレードしても、エージェントを切り替えても消えません。SQLite を永続的な信頼できる唯一の情報源とし、再構築可能な検索インデックスも併せて保存する、自分で管理できるローカルワークスペースに記録されるためです。

API キー不要。サブスクリプション不要。読み取り時の LLM 呼び出し不要。ローカルファイルだけです。

クイックスタート

pip install pmb-ai                 # 1. install
pmb setup                          # 2. detect your agent + wire the MCP entry
pmb warmup                         # 3. preload the model (first recall is instant)
# 4. restart your agent, then just talk to it - memory is automatic
pmb stats                          # 5. see what's stored
pmb recall "auth decision"         # 6. search memory from the terminal
pmb doctor                         # 7. confirm everything is wired

これで完了です。エージェントが記憶できるようになりました。アカウントもキーも不要で、マシンの外にデータが出ることもありません。

コマンド名： CLI コマンドは pmb です。pip ではエイリアスの pmb-ai も利用できます。npm（npx pmb-ai setup）ではコマンドが pmb-ai となり、 先に Python パッケージをインストールしてからセットアップを実行します。同じツールなので、 インストール方法に応じて使いやすい方をお使いください。

リンク： pmbai.dev（サイト） · docs.pmbai.dev（ドキュメント） · はじめに · メモリの削除。

---

デモ

使い心地をご覧ください。同じプロンプトをメモリあり・なしで比較します。

You:    fix that LoadGuard pricing bug we hit last Tuesday

Agent:  prepare(message="fix LoadGuard pricing bug")
        ↓ (6 ms)
        → project_context: 12 events about LoadGuard,
          4 lessons (incl. "never lower NEGOTIATE/SKIP under 25%"),
          3 decisions, 2 open goals
        → active_arcs: "LoadGuard verdict-policy refactor (started Tue)"
        → lessons: 1 directly matches "pricing"
        → recent_activity: 8 commits this week

        Looking at src/engine/verdict-policy.ts (you opened it Tuesday
        14:32, last changed Wednesday). The pricing bug is on line 142
        where the bundle fallback tightened below the rate-floor. Per the
        lesson you saved, we never drop the threshold under 25% - restoring
        the guard there.

エージェントは尋ねませんでした。推測もしませんでした。6 ms でメモリを読み取り、必要な情報をすでに把握した状態で応答しました。

---

PMB を選ぶ理由

• ローカルファーストで、設定不要です。 永続メモリーには SQLite を使用し、再構築可能な検索インデックスもローカルに保存します。アカウント、API キー、テレメトリー、信頼を預けるクラウドは不要です。
• 実際に使われます。 Claude Code / Codex では、フックがモデルの思考前に適切なメモリーを注入するため、ツールの呼び出しを覚えておく必要はありません。
• 多言語対応で、設定不要です。 埋め込みモデルは 50 以上の言語に対応しているため、ロシア語のクエリから英語の事実を見つけられます。言語ごとの設定は不要です。
• MCP ネイティブです。 pmb connect ひとつで、Claude Code、Cursor、Codex、Windsurf、Zed、VS Code などを接続できます。
• 読み取りが高速です。 ウォーム状態なら約 35 ms で想起でき、書き込みは 1 ミリ秒未満で完了します。記憶するために LLM を呼び出す必要はありません。
• 効果を誠実に示します。 ダッシュボードでは「+X%」と主張するのではなく、どの教訓が実際に結果を変えたかを確認できます。
• データはオープンに。 pmb export ですべてのデータを Markdown/JSON に出力できます。Apache 2.0 です。

---

メモリーを確認する

pmb dashboard を実行すると、http://127.0.0.1:8765 でローカルのリキッドグラス Web UI が開きます。PMB が作業中に自動で記録した内容をすべて確認できます。127.0.0.1 のみにバインドされるため、マシンの外にデータが送信されることはありません。

タブは 9 つあります。Map（エンティティグラフ、ライブ表示）、Timeline（プロジェクトごとの Git グラフ）、Overview、Entities、Arcs（物語のスレッド）、Lessons（ルールごとの遵守率、古い教訓の検出）、Duplicates（インラインでの統合）、Performance（ツールごとのレイテンシー）、Recall（ランカーのデバッグ）。

---

検証済みのローカルバックアップ

pmb snapshot create --note "before maintenance"
pmb snapshot list
pmb snapshot verify <snapshot-id>
# Stop PMB servers, agent connections, and dashboards before restoring.
pmb snapshot restore <snapshot-id>

スナップショットでは SQLite のオンラインバックアップを使用して、コミット済みの WAL データを含め、ファイルのチェックサムを記録します。復元時にはメモリーを変更する前にスナップショットを検証し、以前の状態の検証済みコピーを保存します。スクリプトでは pmb snapshot list --json を使用してください。対象範囲と制限事項については、バックアップと復旧を参照してください。

保存できる内容

# Personal facts that change (time-travel: old values archived, never lost)
record_keyed_fact("user", "city", "Warsaw")

# Project structure - symbols, imports, .gitignore-aware
pmb index project .

# Why each file exists + the intent behind every commit (Haiku-summarised, local)
pmb track modules                # one-line purpose per indexed file
pmb track changes                # new commits: what changed and WHY

# PDFs (research papers, manuals, contracts)
pmb index pdf paper.pdf
pmb index pdf ~/docs --recurse

# Whatever your agent logs as it works: decisions, lessons, completed tasks, goals

PMB はコンテンツの種類を問いません。エージェントが後で必要とするテキストであれば、PMB が記憶して検索します。

エージェントが受け取る内容

MCP の呼び出しを 1 回行うだけで、prepare(message) は適切な情報を適切な詳しさで 4～16 ms 以内に返します。

フィールド	内容
project_context	メッセージでプロジェクトに言及している場合は、プロジェクトの概要全体を返します。主要な事実、教訓（従うべき RULES）、決定事項、未完了の目標、関連エンティティ、プロジェクトの物語の流れが含まれます
lessons	クエリに一致する手順上のルールを返します。それぞれに surface_id が付いており、エージェントは後からルールに従ったことを確認できます
recent_activity	セッションの連続性を保つため、過去 24 時間の決定、編集、完了事項を返します
open_goals	進行中の目標を返すため、エージェントは取り組んでいる内容を把握できます
active_arcs	プロジェクトが現在進行中の物語の流れを返します

その他の用途には、recall(query)（ハイブリッド検索、ウォーム状態で 35 ms）と、docs/reference/COMMANDS.md に記載されているその他 27 個のツールがあります。

---

仕組み

flowchart LR
    A[Your agent] -->|MCP stdio| B[PMB MCP server]
    B --> C[Engine]
    C -->|read 35 ms| R[Hybrid recall<br/>BM25 + vector + graph + rerank]
    C -->|write under 1 ms| W[Async embed queue<br/>SQLite first, vectors later]
    R --> D[(SQLite)]
    R --> E[(LanceDB)]
    W --> D
    W --> E
    style A fill:#dbeafe,color:#1e3a8a
    style B fill:#ede9fe,color:#5b21b6
    style C fill:#dcfce7,color:#14532d

• ストレージ - 永続化されるイベントはすべて、信頼できる唯一の情報源である SQLite に保存されます。再構築可能なベクトルインデックスは、その隣にある LanceDB に保存されます。ワークスペース全体はディスク上に保持され、いつでもコピーまたはエクスポートできます。
• 想起 - BM25（字句）＋高密度ベクトル（意味）＋エンティティグラフ＋任意のクロスエンコーダーによる再ランキングを、Reciprocal-Rank-Fusion で融合します。
• 書き込み - 非同期です。MCP ツールは 1 ミリ秒未満で応答し、埋め込み生成と LanceDB への挿入はバックグラウンドスレッドで実行されます。
• 重複排除 - 4 層で行います。完全一致のテキスト照合 -> コサイン類似度 >= 0.92 は自動統合 -> コサイン類似度 0.80-0.92 は境界域（後で LLM が検証） -> ダッシュボードで手動確認。古い値は削除せずアーカイブされます。keyed_fact_as_of(t) で履歴全体を確認できます。
• 多言語対応 - 言語パックは不要です。 デフォルトの埋め込みモデル（paraphrase-multilingual-MiniLM-L12-v2）は 50 以上の言語をカバーするため、где я живу で user.city = Warsaw として保存されたキー付きファクトを見つけられます。インテント検出には言語を越えて転移する英語の意味アンカーを使用し、コールド時の字句検索経路は独自のトラフィックから自動生成されます。約 11 言語にわたって高い想起性能を維持します（101 件のクエリ評価で top-3 ~= 0.9、en/fr/pt/ru では top-1 = 1.00）。docs/contributing/adding-a-language.md をご覧ください。

---

インストール

ほとんどの方は、上記のクイックスタートだけで十分です。そのほかの方法：

# From source
git clone https://github.com/oleksiijko/pmb.git && cd pmb
python -m venv .venv && source .venv/bin/activate
pip install -e .
pmb warmup                       # prime the ~450 MB embedder once

1 つ以上のエージェントを接続します（すべて stdio です。サーバーはエージェントの子プロセスとして実行されるため、ネットワーク、ポート、トークンは不要です）。

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

複数のエージェントを 1 つのメモリーに接続します。

pmb connect claude-code --workspace personal
pmb connect cursor      --workspace personal   # both read/write the same workspace

複数のマシンやチームで 1 つのメモリーを共有しますか？その場合は、ベアラートークン認証付きの任意の 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 チートシート

# Memory
pmb stats                                   show counts and storage info
pmb recall "query"                          search with full debug
pmb dashboard                               web UI on port 8765 (graph, settings, errors)

# Ingest
pmb index pdf paper.pdf                     extract + chunk + embed
pmb index pdf ~/docs --recurse              entire directory
pmb index project .                         scan codebase
pmb track changes                           summarise commit intent (why)
pmb track modules                           one-line purpose per module
pmb import chatgpt ~/Downloads/export.json  bring existing history

# Continuity & efficiency (opt-in)
pmb resume save                             write .pmb/resume.md (commit it)
pmb resume install                          refresh resume.md at every turn end
pmb health lessons-impact                   which lessons actually help outcomes
pmb memory ledger                           Memory Delta handles this session

# Maintenance
pmb regraph                                 rebuild entity graph
pmb consolidate                             run sleep pass (optional)
pmb compact                                 archive old events
pmb dedupe                                  resolve borderline duplicates

# Hooks (force-feed PMB at the protocol level - no model cooperation)
pmb hooks install claude-code               wire all lifecycle hooks
pmb hooks list                              show what's installed
pmb hooks capabilities                      ambient mechanism each agent supports
pmb hooks uninstall claude-code             remove them
pmb auto-context "fix bug in PMB"           preview per-turn injection
pmb session-restore -m 180                  preview post-compaction restore
pmb lesson-followcheck --dry-run            preview follow-through scoring

# Ambient memory (the write side - memory journals the agent's work)
pmb autowrite --dry-run                     preview ambient auto-write for this turn
pmb ambient-watch .                         ambient auto-write for MCP-only hosts (git observer)
pmb forget-auto                             drop memory the ambient layer wrote itself

# Config
pmb config list                             default tier (25 keys you care about)
pmb config list --pro                       every key, including 80 advanced knobs
pmb config set recall.ppr_enabled true      toggle a feature
pmb connect --rules-only                    refresh CLAUDE.md only

エージェントごとの手順：docs/guide/usage.md。完全なリファレンス： docs/reference/COMMANDS.md。

---

フック - 指示を待たないメモリー

エージェントのメモリーにおける難題は、情報を保存することではなく、保存した情報をエージェントに使わせることです。ルールファイルに書いた指示は見落とされがちです。そのため PMB は、プロトコルレベルでフック（pmb hooks install claude-code）を設定し、モデルが行動を覚えていることに依存する状況を、フックごとに解消します。

• UserPromptSubmit -> 自動想起。 各メッセージを分類し（正規表現、多言語対応、1 ミリ秒未満）、該当するメモリー（教訓、過去の決定、想起結果、プロジェクト概要）を、モデルが考える前に挿入します。些細なメッセージには何も挿入しません。
• PostToolUse -> 常時観測。 エージェントが実行する各ツールの操作を、軽量なアクションジャーナルに追記します（SQLite への単一の INSERT で、モデルは使用しません）。読み取りと ls は除外し、編集、テスト、コミットは記録します。
• SessionStart -> セッション復元。 コンテキストが圧縮された後、エージェントはユーザーに再度尋ねる代わりに、セッションで記録された内容から「どこまで進んでいたか」を再構築します。
• Stop -> フォローアップ＋常時自動書き込み。 （a）提示された教訓がエージェントの実際の行動に反映されたかを確認し、決定論的に実践済みとして記録します。（b）エージェントが record_* ツールを呼び出さなかった場合、観測された操作からアクティビティエントリを 1 件生成します。これにより、エージェントが何も記録しなくても実際の作業が保存されます。

エージェントを使わずにプレビューできます：pmb auto-context "..."、pmb session-restore -m 180、pmb lesson-followcheck --dry-run、pmb autowrite --dry-run。

アンビエントメモリ - 書き込み側

自動想起によって 読み取り 側が解決されました。アンビエントメモリは 書き込み 側でも同じことを行います。record_batch を忘れても、メモリがエージェントの作業を記録します。

• 連携します。 エージェントがこのターンですでに record_* ツールを呼び出していれば、アンビエントメモリは何もせず、記録漏れだけを補います。
• 変更量ではなく、成果を評価します。 結果が品質基準を満たした場合（テストの成功、失敗の修正、デプロイの実行など）にのみターンを記録し、変更したファイル数だけでは判断しません。
• 透明性があり、取り消し可能です。 アンビエントメモリの各エントリには source=autowrite のタグが付与され、ダッシュボードでは自動記録として表示されます。また、pmb forget-auto で削除できます。デフォルトで有効です。無効にするには pmb config set autowrite.enabled false を実行します。
• あらゆるホストで動作します。 Claude Code（フック）、Codex（pmb codex-notify）、Cursor/Zed/VS Code のような MCP のみのホスト（git オブザーバー、pmb ambient-watch .）に対応しています。pmb hooks capabilities でご利用の環境を確認できます。

デフォルトではテンプレートベースで要約します（即時に実行され、モデルは不要です）。ローカル/API/CLI モデルによる要約を使うには、pmb config set autowrite.synthesizer llm:ollama または llm:openai を設定します（タイムアウトが発生した場合はテンプレートにフォールバックします）。

自己改善ループ

表示されたレッスンにはそれぞれ surface_id が付与されます。フォローアップは両方の方法で記録されます。エージェントは mark_lesson_followed(surface_id, True) で確認し、Stop フックは記録されたアクティビティから推測します。するとレッスンタブにルールごとに、表示された回数、フォローされた回数、★ USEFUL（2回以上フォロー）、? UNVERIFIED（表示されたが未確認）、そしてルールが繰り返し無視された場合（2回以上）に限り 💀 DEAD が表示されます。どのルールが役立つかを確認し、役立たないルールを整理できます。

---

設定 - 気にするべき25項目、気にしなくてよい80項目

PMB には105個の調整可能な設定があります。日々の品質に影響する25項目はデフォルト階層です（pmb config list）。残りは内部の重みや実験的なフラグであり、一覧を見やすく保つため --pro の背後に隠されています。pro の各キーは引き続き pmb config get で読み取り、pmb config set で書き込みできます。一覧から隠されているだけで、利用制限はありません。

キー	デフォルト	説明
recall.top_k	5	想起で返す結果の数
recall.bm25_weight	0.7	BM25 とベクトル検索の比率（1.0 = BM25 のみ）
recall.ppr_enabled	true	意図に応じたマルチホップのグラフ拡散
recall.keyed_fact_boost	0.35	個人に関するクエリで、個人属性の事実をどれだけ優先するか
recall.rerank	false	常時有効のクロスエンコーダー（LoCoMo の結果が悪化するため、オフのままにしてください）
embedding.model	paraphrase-multilingual-MiniLM-L12-v2	ベクトルモデル
graph.extractor	regex	regex / spacy / llm:claude / llm:openai / llm:ollama / llm:codex
mcp.record_batch_async	true	応答を待たずに書き込み（戻り値の遅延は1ミリ秒未満）
agent.apply_lessons	true	エージェントが行動前にレッスンを提示
dedup.enable	true	4つの重複排除レイヤーすべて
decay.factor_per_day	0.985	重要度の半減期
chat.model	haiku	pmb-chat のデフォルトモデル

---

数値

想起 p50 / p95（ウォーム）	35 ms / 110 ms
prepare(message)（ウォーム）	4-16 ms
record_batch_async	< 1 ms
MCP コールドブート	3.7 s
LoCoMo recall@10（n=10）	94.5 %
多言語メガストレス top-10（900 q）	99.2 %

# Reproduce locally
python scripts/benchmarks/benchmark_locomo.py --n-conversations 10
python scripts/benchmarks/mega_stress_test.py

---

プライバシー

• デフォルトでは100 %オフラインです。エンジンからのネットワーク呼び出しやテレメトリは一切ありません。PMB サーバーへの接続もありません。
• ワークスペースは ~/.pmb/<name>/ 以下のディレクトリです。Dropbox にコピーしたり、git にプッシュしたり、USB ドライブで共有したりできます。使い方は自由です。
• シークレットは書き込み時に自動的にマスキングされます（OpenAI / Anthropic / AWS / Stripe / GitHub のキー。設定で変更可能）。
• Apache 2.0 ライセンスです。フォークも歓迎します。

---

FAQ

PMB は LLM を呼び出しますか？ 読み取り時は呼び出しません。書き込み時もデフォルトでは呼び出しません。オプションとして、 pmb consolidate を実行すると、ローカルの Ollama、Claude CLI、Anthropic、または OpenAI を使って短い 振り返りを書き込めます。利用は任意です。

費用はかかりますか？ 0 ドルです。PMB のサービスはありません。

エージェントは PMB について知っている必要がありますか？ pmb connect の実行後、ルールが CLAUDE.md / AGENTS.md に自動的に追記されます。デフォルトのプロファイルでは、 中核となる MCP ツール 10 個（読み取りを優先する prepare() パターンを含む）が公開されます。 データ取り込みや管理用の、より広範なプロファイルもあります。

エージェントの動作は遅くなりますか？ recall（ウォーム状態で 35～110 ms）を除くすべてのツールは、 1 桁ミリ秒で応答するため、人間には遅さを感じられない程度です。

2 つのエージェントで同じメモリを共有できますか？ はい。同じワークスペースを指定してください。 SQLite WAL と 10 秒のビジータイムアウトが、同時書き込みに対応します。

事実を消去するには？ pmb forget <ulid> でアーカイブします（想起対象から除外され、復元可能です）。 完全に削除するには、pmb delete <ulid> --hard を実行します。

Windows に対応していますか？ はい。Windows 11、macOS 14、Ubuntu 22.04 でテスト済みです。キリル文字を含むパスや コンソールのエンコーディングにも対応しています。

PDF／コード／Markdown に対応していますか？ pmb index pdf paper.pdf、pmb index project .、 pmb import markdown ~/notes/、pmb import chatgpt path.json を使えます。

コールドスタートが遅いです。 最初の想起時に埋め込みモデルを読み込みます（約 3 秒）。一度 pmb warmup を実行するか、バックグラウンドでプリウォームスレッドに処理させてください。

ロードマップはありますか？ docs/ROADMAP.md をご覧ください。litestream によるバックアップ、オプションの クラウド同期（バケットは各自で用意）、tree-sitter によるプロジェクトのインデックス作成、画像の OCR などがあります。

---

コントリビュート

Issue と PR を歓迎します。フルタイムのメンテナーは 1 人です。大きな変更を行う場合は、方向性を合わせられるよう、 事前にディスカッションを開始してください。

git clone https://github.com/oleksiijko/pmb.git && cd pmb
python -m venv .venv && source .venv/bin/activate
pip install -c requirements-dev.lock -e ".[dev,crypto]"
python scripts/prewarm_models.py
pytest                  # full suite, ~4 minutes
pytest -k recall        # fast subset, ~12 s

開発コマンド

bash scripts/test.sh                 # whole suite (CI-equivalent)
bash scripts/test.sh tests/recall    # a subset (any pytest args pass through)
bash scripts/codeql_local.sh         # run CI's CodeQL security-extended locally
bash scripts/install-dev-hooks.sh    # pre-commit hook: ruff + CodeQL before each commit

scripts/codeql_local.sh は初回実行時に CodeQL バンドルを自動インストールし、CI で使用するものと まったく同じスイートを実行します。そのため、プッシュ後ではなくローカルでセキュリティ上の問題を検出できます。 git commit --no-verify を使うと pre-commit フックを回避できます（または SKIP_CODEQL=1 で スキャンのみをスキップできます）。

ライセンス：Apache 2.0。