PMB AI

PMB

Local-first memory for your AI coding agent.

SQLite is the source of truth. No cloud, no API keys, no re-explaining.

*Local-first memory, visualized. 3,800+ entities and 41,000+ connections, captured automatically as you work.*

Website · Docs · Quickstart · Demo · Why PMB · How it works · FAQ

Your AI agent forgets everything between sessions. So you re-explain the same decisions, lessons and constraints over and over. PMB remembers them in one local workspace and feeds them back through MCP - no cloud, no API keys, no LLM call on the read path. And it tells you when memory is actually helping, instead of claiming "+X%".

⭐ Star the repo if PMB saves you a re-explanation.

---

PMB gives Claude Code, Cursor, Codex and the other MCP-aware agents a real memory: decisions you made last week, lessons you taught them, personal facts, project structure, PDFs. They survive every restart, every model upgrade, every agent switch - because they live in a local workspace you own, with SQLite as the durable source of truth and rebuildable search indexes beside it.

No API keys. No subscription. No LLM call on the read path. Just local files.

Quickstart

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

That's it - your agent now remembers. No account, no keys, nothing leaves your machine.

Command name: the CLI is `pmb`. Via pip you also get the alias

`pmb-ai`; via npm (npx pmb-ai setup) the command is pmb-ai and it

installs the Python package first, then runs setup. Same tool - use whichever

your install gave you.

Links: pmbai.dev (site) ·

docs.pmbai.dev (docs) ·

Getting started ·

Deleting memories.

---

Demo

*What it feels like - same prompt, with and without memory:*

▶ Click to play the 2-minute setup

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.

The agent didn't ask. It didn't guess. It read its memory in 6 ms and showed up already informed.

---

Why PMB

• Local-first, zero-config. SQLite holds the durable memory; rebuildable search indexes stay local. No account, API keys, telemetry, or cloud to trust.
• It actually gets used. On Claude Code / Codex, hooks inject the right memory *before* the model thinks - you never have to remember to call a tool.
• Multilingual, no setup. The embedder covers 50+ languages; a Russian query finds an English fact. No per-language config.
• MCP-native. One pmb connect wires Claude Code, Cursor, Codex, Windsurf, Zed, VS Code, and more.
• Fast read path. Recall in ~35 ms warm; writes return in under a millisecond - no LLM call to remember.
• Honest impact. The dashboard shows which lessons actually changed outcomes, instead of claiming "+X%".
• Your data, in the open. pmb export dumps everything to Markdown/JSON. Apache 2.0.

---

See your memory

pmb dashboard opens a local, liquid-glass web UI on http://127.0.0.1:8765 over everything PMB captured - written automatically, just by working. It binds to 127.0.0.1 only, so nothing leaves your machine.

*Map - every entity and connection in your project, as a live graph.*

*Timeline - your memory as a journal, newest first.*

Nine tabs: Map (entity graph, live), Timeline (git-graph by project), Overview, Entities, Arcs (narrative threads), Lessons (per-rule follow-rate, dead-lesson detection), Duplicates (inline merge), Performance (per-tool latency), Recall (debug ranker).

---

Verified local backups

pmb snapshot create --note "before maintenance"

pmb snapshot list pmb snapshot verify

Stop PMB servers, agent connections, and dashboards before restoring.

pmb snapshot restore

Snapshots use SQLite online backup to include committed WAL data and record file checksums. Restore checks the snapshot before changing memory and saves a verified copy of the previous state. Use pmb snapshot list --json in scripts. See backup and recovery for scope and limitations.

What you can store

# 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 is content-agnostic. If it's text the agent will care about later, PMB remembers and retrieves it.

What the agent gets back

A single MCP call - prepare(message) - returns the right things at the right level of detail, in 4-16 ms:

For everything else there's recall(query) (hybrid search, 35 ms warm) and 27 other tools in docs/reference/COMMANDS.md.

---

How it works

flowchart LR

A[Your agent] -->|MCP stdio| B[PMB MCP server] B --> C[Engine] C -->|read 35 ms| R[Hybrid recall BM25 + vector + graph + rerank] C -->|write under 1 ms| W[Async embed queue 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

• Storage - every durable event lives in SQLite, the source of truth. Rebuildable vector indexes live in LanceDB beside it. The whole workspace stays on your disk and can be copied or exported anytime.
• Recall - BM25 (lexical) + dense vector (semantic) + entity graph + optional cross-encoder rerank, fused via Reciprocal-Rank-Fusion.
• Writes - async. The MCP tool returns in under a millisecond; the embed + LanceDB insert happen on a background thread.
• Dedup - four layers: exact text match -> cosine >= 0.92 auto-merge -> cosine 0.80-0.92 borderline (LLM verify later) -> manual review in the dashboard. Old values are archived, never deleted; full history via keyed_fact_as_of(t).
• Multilingual - no language packs. The default embedder (paraphrase-multilingual-MiniLM-L12-v2) covers 50+ languages, so *где я живу* finds a keyed-fact stored as *user.city = Warsaw*. Intent detection rides English semantic anchors that transfer cross-lingually, and the cold lexical path self-compiles from your own traffic. Recall stays strong across ~11 languages (top-3 ~= 0.9 on a 101-query eval; top-1 = 1.00 for en/fr/pt/ru). See docs/contributing/adding-a-language.md.

---

Install

The Quickstart above is all most people need. Other ways:

# 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

Wire one or more agents (all stdio - the server runs as a child of your agent; no network, no port, no token):

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

Point several agents at one memory:

pmb connect claude-code --workspace personal

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

Sharing one memory across machines or a team? That's an optional HTTP mode

with bearer-token auth - see docs/guide/TEAM.md. Not needed for local use.

Running the tests? Use the venv's Python: .venv/bin/python -m pytest

(or .venv\Scripts\python.exe -m pytest on Windows). Bare pytest outside

the venv just reports missing numpy/fastmcp/typer.

---

CLI cheat sh