PMB (Personal Memory Brain) | Local first memory layer

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 youwhen 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 alocal 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.

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 ispmb. Viapipyou also get the aliaspmb-ai; vianpm(npx pmb-ai setup) the command ispmb-aiand it installs the Python package first, then runs setup. Same tool - use whichever your install gave you.

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

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 in6 msand showed up already informed.

- 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 memorybeforethe 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.Onepmb connectwires 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 exportdumps everything to Markdown/JSON. Apache 2.0.

pmb dashboardopens a local, liquid-glass web UI onhttp://127.0.0.1:8765over everything PMB captured - written automatically, just by working. It binds to127.0.0.1only, 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).

# 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.

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

# 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

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

Running the tests?Use the venv's Python:.venv/bin/python -m pytest(or.venv\Scripts\python.exe -m pyteston Windows). Barepytestoutside the venv just reports missingnumpy/fastmcp/typer.

# 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

Hooks - memory that doesn't wait to be asked

The hard part of agent memory isn't storing - it's getting the agent tousewhat's stored. Soft instructions in a rules file get skipped. So PMB wires hooks at the protocol level (pmb hooks install claude-code), each removing a dependency on the model remembering to act:

- UserPromptSubmit -> auto-recall.Every message is classified (regex, multilingual, sub-ms) and the matching memory - lessons, past decisions, recall hits, project overview - is injectedbeforethe model thinks. Trivial messages inject nothing.
- PostToolUse -> ambient observe.Every tool the agent runs is appended to a lightweight action journal (a single SQLite INSERT, no model). Reads andlsare filtered out; edits, tests and commits are kept.
- SessionStart -> session-restore.After a context compaction the agent rebuilds "where you left off" from what the session recorded, instead of re-asking you.
- Stop -> follow-through + ambient auto-write.(a) It checks which surfaced lessons actually showed up in what the agent did and marks them followed,deterministically. (b) If the agent did NOT call arecord_tool, it synthesizes one activity entry from the observed actions - so real work is captured even when the agent stays silent.

Auto-recall fixed thereadside; ambient memory does the same for thewriteside - the memory journals the agent's work even when it forgetsrecord_batch:

- Coordinated.If the agent already called arecord_tool this turn, ambient stays silent; it only fills the gap.
- Outcome-scored, not churn.A turn is journaled only if results clear a quality bar (tests passed, a failure fixed, a deploy ran), not by file count alone.
- Honest + reversible.Every ambient entry is taggedsource=autowrite, shown as auto in the dashboard, and removable withpmb forget-auto.On by default; disable withpmb config set autowrite.enabled false.
- Works on every host.Claude Code (hooks), Codex (pmb codex-notify), MCP-only hosts like Cursor/Zed/VS Code (git observer,pmb ambient-watch .). Check yours withpmb hooks capabilities.

Synthesis is template-based by default (instant, no model). Opt into a local/API/CLI model summary withpmb config set autowrite.synthesizer llm:ollamaorllm:openai(it has a timeout and falls back to the template).

Every surfaced lesson carries asurface_id. Follow-through is recorded both ways: the agent confirms viamark_lesson_followed(surface_id, True), and theStop hookinfers it from recorded activity. TheLessons tabthen shows, per rule: how often it was shown, how often it was followed,★ USEFUL(followed >= 2x),? UNVERIFIED(surfaced but unconfirmed), and💀 DEADonly when a rule is repeatedlyignored(>= 2). You see which rules help and prune the ones that don't.

Settings - 25 you care about, 80 you don't

PMB has 105 tunables. The 25 that affect day-to-day quality aredefault-tier(pmb config list). The rest are internal weights and experimental flags, hidden behind--proso the surface stays scannable. Every pro key still reads withpmb config getand writes withpmb config set- hidden fromlist, not gated.

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

- 100 % offline by default. No network calls from the engine, zero telemetry - there is no PMB server to call home to.
- Workspace = a directory under~/.pmb/<name>/. Copy it to Dropbox, push it to git, share it on a USB drive. Your call.
- Secrets are auto-redacted at write time (OpenAI / Anthropic / AWS / Stripe / GitHub keys; configurable).
- Apache 2.0 licensed. Forks welcome.

Does PMB call an LLM?On read: never. On write: never by default. Optional:pmb consolidatecan run a local Ollama, Claude CLI, Anthropic, or OpenAI pass to write short reflections - opt-in.

What about cost?$0. There is no PMB service.

Does the agent need to know about PMB?Afterpmb connect, the rules are appended toCLAUDE.md/AGENTS.mdautomatically. The default profile exposes 10 core MCP tools (including theprepare()read-first pattern); wider profiles exist for ingestion and admin.

Will it slow my agent down?Tools return in single-digit milliseconds for everything exceptrecall(35-110 ms warm), which is below human perception.

Can two agents share one memory?Yes - point them at the same workspace. SQLite WAL + a 10 s busy-timeout handle concurrent writes.

Wipe a fact?pmb forget <ulid>archives it (excluded from recall, restorable). Hard-delete:pmb forget <ulid> --hard.

Windows?Yes - tested on Windows 11, macOS 14, Ubuntu 22.04. Cyrillic paths and console encoding are handled.

PDFs / code / Markdown?pmb index pdf paper.pdf,pmb index project .,pmb import markdown ~/notes/,pmb import chatgpt path.json.

Cold start is slow.First recall loads the embedding model (~3 s). Runpmb warmuponce, or let the prewarm thread handle it in the background.

Issues and PRs welcome. There's one full-time maintainer; please open a discussion before a large change so we can align on direction.