PMB

Local-first memory for your AI coding agent.

One file on your disk. Twenty-nine MCP tools. No cloud.

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

Quickstart · Dashboard · Why pmb-ai? · Demo · How it works · FAQ

Persistent memory for AI coding agents - local, offline, no API keys. For developers on Claude Code / Cursor / Codex who are tired of re-explaining context every session. PMB remembers your decisions, lessons, and project facts in one SQLite file on your disk and feeds them back through MCP.

⭐ 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 about you. Project structure. PDFs. They survive every restart, every model upgrade, every agent switch - because they live in one SQLite file on your disk.

No API keys. No subscription. No LLM call on the read path. Just 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. Installed via pip you also get the alias pmb-ai; installed via npm (npx pmb-ai) the command is pmb-ai. Same tool - use whichever your install gave you. From npm, npx pmb-ai setup runs the full cycle: it installs the Python package, then runs setup.

Docs: oleksiijko.github.io/pmb · Getting started · Deleting memories · all documentation.

See your memory

pmb dashboard opens a local, liquid-glass UI 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.

Watch: 2-minute setup

https://github.com/user-attachments/assets/c0f454c5-84b3-42d6-b1dc-f694978cd802

Prefer text? The Quickstart above is the same flow in seven commands.

Why pmb-ai?

• Local-first, zero-config. One SQLite file on your disk. No account, no API keys, no telemetry, no 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.
• Your data, in the open. pmb export dumps everything to Markdown/JSON. Apache 2.0.

What it feels like

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 you mentioned
        is on line 142 where the bundle fallback was tightening below
        the rate-floor. Per the lesson you saved, we should never
        drop the threshold under 25% - let me restore the guard there.

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

What you can put in there

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

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

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

# Whatever your agent decides to log as it works
# (decisions, lessons, completed tasks, goals)

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

Storage - every event lives in SQLite. Vectors live in LanceDB next to it. Both are files on your disk; copy them anywhere with cp.

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 actual embed + LanceDB insert happens 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 get archived, never deleted; full history is queryable via keyed_fact_as_of(t).

Multilingual - no language packs. The default embedder (paraphrase-multilingual-MiniLM-L12-v2) covers 50+ languages, so a Russian query like где я живу finds an English keyed-fact stored as user.city = Warsaw with no translation. Intent detection and keyed extraction ride English semantic anchors that transfer cross-lingually through the embedder - one mechanism for every language the model knows, instead of a hand-written pack per language. The cold lexical path then self-compiles from your own traffic (anchor→lexicon distillation), so a language you actually use gets faster over time with zero configuration. Recall stays strong across ~11 languages (overall top-3 ≈ 0.9 on a 101-query eval; top-1 = 1.00 for en/fr/pt/ru, CJK weaker on exact top-1). See docs/contributing/adding-a-language.md.

Install

pip install pmb-ai

Or from source:

git clone https://github.com/oleksiijko/pmb.git && cd pmb
python -m venv .venv && source .venv/bin/activate
pip install -e .

Prime the model once so the first recall is fast (the multilingual embedding model is ~450 MB; without this the very first query pays a one-time cold-start load):

pmb warmup

Running the tests? Use the venv's Python, not your system Python - .venv/bin/python -m pytest (or .venv\Scripts\python.exe -m pytest on Windows). Running bare pytest outside th