oleksiijko/pmb

PMB – Local‑first memory for AI coding agents

What it is – PMB (pronounced “p‑m‑b”) is a Python package that gives code‑writing LLM agents (Claude Code, Cursor, Codex, Gemini, etc.) a persistent, searchable memory that lives entirely on your machine. The memory is stored in a SQLite database (the source of truth) with optional vector indexes in LanceDB, and is exposed to agents through the Model‑Context‑Protocol (MCP).

Why it matters – Today many AI‑assisted coding tools forget everything once the process restarts, forcing you to repeat decisions, lessons, and project context. PM B captures those facts automatically, indexes them, and injects the relevant pieces back into the agent before the model generates a response, all without any cloud calls or API keys.

---

Key features (as described in the README)

Feature	What you get
Local‑first storage	All events, facts, and embeddings are written to a SQLite file in ~/.pmb/<workspace>/. No network traffic is required for reads; writes are sub‑millisecond.
Hybrid recall	Queries are answered by a fusion of BM25 lexical search, dense vector similarity, and graph‑based diffusion (Reciprocal‑Rank‑Fusion). Typical warm‑path latency: ~35 ms (p50) and ~110 ms (p95).
MCP‑native integration	A tiny MCP server runs as a child of the agent. The standard prepare(message) call returns a structured payload (project_context, lessons, recent_activity, open_goals, active_arcs).
Automatic ingestion	pmb index project . scans your codebase, extracts symbols, imports, and file intents. pmb index pdf … extracts and chunks PDFs. pmb track … records commit intent and module purpose.
Ambient (auto‑write) memory	Hooks observe the agent’s tool usage (edits, tests, commits) and write lightweight journal entries when the agent forgets to call a record_* tool.
Dashboard UI	A local web UI (pmb dashboard) visualises the memory as an entity graph, timeline, lessons impact, duplicates, and performance stats.
Multilingual embedding	Uses paraphrase‑multilingual‑MiniLM‑L12‑v2 (covers 50+ languages) so queries in Russian, French, etc., retrieve English facts.
Zero‑config, zero‑cost	No cloud account, no API keys, no subscription. All data stays on your disk; you can export to Markdown/JSON.
Privacy & export	Secrets are redacted on write; the whole workspace can be copied, synced to Dropbox, or version‑controlled.
Extensible config	105 tunable knobs; 25 are exposed by default (pmb config list). Advanced flags are hidden behind --pro.

---

How it works (high‑level flow)

1. Setup – pip install pmb-ai && pmb setup detects the target agent and installs MCP hooks.
2. Ingestion – Files, PDFs, git commits, and explicit record_* calls are written to SQLite; embeddings are queued and inserted into LanceDB asynchronously.
3. Recall – When the agent sends prepare(message), PMB runs a hybrid search (BM25 + vector + graph diffusion) and returns the most relevant entities, lessons, recent actions, etc.
4. Ambient write – After each tool use the hooks log the action; a “stop” hook scores lesson follow‑through and can synthesize missing record_* entries.
5. Dashboard – The UI shows a live graph of entities and arcs, a timeline of events, and diagnostics (which lessons actually changed outcomes, latency per tool, duplicate detection).

---

Quick start (from the 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

All commands are also available via the pmb-ai alias (npm) or as a Python module.

---

Typical use cases

• Long‑running codebases – Keep decisions, architectural rules, and bug‑fix rationales across many sessions without re‑explaining.
• Cross‑agent continuity – Switch from Claude Code to Cursor; the same SQLite workspace supplies memory to both.
• Research‑heavy projects – Index PDFs and retrieve relevant passages instantly while coding.
• Team‑level shared context – Optional HTTP mode lets multiple developers point their agents at a common workspace (auth‑protected).
• Lesson impact analysis – The dashboard tells you which “rules” the agent actually followed, helping you prune dead or noisy lessons.

---

Limitations & considerations (as stated or implied)

• Read‑path is offline only – No LLM is called when recalling; quality depends on the embedder and hybrid ranking.
• Embedding model size – The default multilingual MiniLM model (~450 MB) must be loaded once (pmb warmup).
• Optional LLM‑based features – Some optional commands (pmb consolidate, auto‑write synthesis) can invoke a local Ollama/Claude/OpenAI model, but they are disabled by default.
• Local resource usage – SQLite + LanceDB indexes occupy disk space; large codebases or many PDFs will grow the workspace.
• Agent‑specific hooks – Full benefit requires the agent to support MCP hooks; the README lists the supported hosts (Claude Code, Cursor, Codex, etc.).

---

License & community

• Apache 2.0 – Free to use, modify, and redistribute.
• MCP registration – Listed in the Model‑Context‑Protocol registry, enabling discoverability by other MCP‑aware tools.
• Documentation & CI – Online docs at docs.pmbai.dev, CI badge shows tests pass on each push.

---

Bottom line

PMB is a genuine, open‑source project that tackles a concrete pain point for AI‑assisted developers: the lack of persistent, low‑latency memory. By storing everything locally in SQLite, providing fast hybrid search, and automatically wiring into popular coding agents via MCP, it lets you keep project context, lessons, and decisions across sessions without any cloud dependency.