PMB (Personal Memory Brain)

---

O PMB dá ao Claude Code, Cursor, Codex e outros agentes com suporte a MCP uma memória real: decisões que você tomou na semana passada, lições que você ensinou, fatos pessoais, estrutura do projeto, PDFs. Elas sobrevivem a cada reinício, a cada atualização de modelo, a cada troca de agente — porque vivem em um workspace local que é seu, com SQLite como fonte durável da verdade e índices de busca reconstruíveis ao lado.

Sem chaves de API. Sem assinatura. Sem chamada de LLM no caminho de leitura. Apenas arquivos locais.

Início rápido

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

É isso — seu agente agora lembra. Sem conta, sem chaves, nada sai da sua máquina.

Nome do comando: a CLI é pmb. Via pip você também tem o alias pmb-ai; via npm (npx pmb-ai setup) o comando é pmb-ai e ele instala o pacote Python primeiro, depois executa a configuração. Mesma ferramenta — use a que sua instalação forneceu.

Links: pmbai.dev (site) · docs.pmbai.dev (docs) · Começando · Excluindo memórias.

---

Demo

Como é a sensação — mesmo prompt, com e sem memória:

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.

O agente não perguntou. Não adivinhou. Ele leu a memória em 6 ms e apareceu já informado.

---

Por que PMB

• Local-first, zero configuração. O SQLite guarda a memória durável; índices de busca reconstruíveis permanecem locais. Sem conta, chaves de API, telemetria ou nuvem para confiar.
• Realmente é usado. No Claude Code / Codex, hooks injetam a memória certa antes de o modelo pensar — você nunca precisa lembrar de chamar uma ferramenta.
• Multilíngue, sem configuração. O embedder cobre mais de 50 idiomas; uma consulta em russo encontra um fato em inglês. Sem configuração por idioma.
• Nativo de MCP. Um pmb connect conecta Claude Code, Cursor, Codex, Windsurf, Zed, VS Code e outros.
• Caminho de leitura rápido. Recuperação em ~35 ms quente; gravações retornam em menos de um milissegundo — sem chamada de LLM para lembrar.
• Impacto honesto. O painel mostra quais lições realmente mudaram resultados, em vez de alegar "+X%".
• Seus dados, abertos. pmb export exporta tudo para Markdown/JSON. Apache 2.0.

---

Veja sua memória

pmb dashboard abre uma interface web local em vidro líquido em http://127.0.0.1:8765 sobre tudo que o PMB capturou — escrita automaticamente, apenas trabalhando. Ela vincula-se apenas a 127.0.0.1, então nada sai da sua máquina.

Nove abas: Mapa (grafo de entidades, ao vivo), Linha do tempo (grafo git por projeto), Visão geral, Entidades, Arcos (fios narrativos), Lições (taxa de seguimento por regra, detecção de lições mortas), Duplicatas (mesclagem inline), Desempenho (latência por ferramenta), Recuperação (depuração do ranqueador).

---

Backups locais verificados

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>

Snapshots usam backup online do SQLite para incluir dados WAL confirmados e registrar checksums de arquivos. A restauração verifica o snapshot antes de alterar a memória e salva uma cópia verificada do estado anterior. Use pmb snapshot list --json em scripts. Veja backup e recuperação para escopo e limitações.

O que você pode armazenar

# 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

O PMB é agnóstico de conteúdo. Se for texto que o agente vai precisar depois, o PMB lembra e recupera.

O que o agente recebe de volta

Uma única chamada MCP — prepare(message) — retorna as coisas certas no nível certo de detalhe, em 4–16 ms:

Campo	O que é
project_context	Visão geral completa do projeto se a mensagem mencionar um projeto: fatos-chave, lições (REGRAS a seguir), decisões, metas abertas, entidades relacionadas, o arco narrativo do projeto
lessons	Regras processuais que correspondem à consulta, cada uma com um surface_id para o agente confirmar que seguiu a regra depois
recent_activity	Últimas 24 h de decisões / edições / conclusões para continuidade da sessão
open_goals	Metas em andamento para o agente saber o que você está buscando
active_arcs	Arcos narrativos em que o projeto está vivendo atualmente

Para todo o resto, há recall(query) (busca híbrida, 35 ms quente) e outras 27 ferramentas em docs/reference/COMMANDS.md.

---

Como funciona

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

• Armazenamento — todo evento durável vive no SQLite, a fonte da verdade. Índices vetoriais reconstruíveis vivem no LanceDB ao lado. Todo o workspace permanece no seu disco e pode ser copiado ou exportado a qualquer momento.
• Recuperação — BM25 (lexical) + vetor denso (semântico) + grafo de entidades + reranqueamento opcional por cross-encoder, fundidos via Reciprocal-Rank-Fusion.
• Gravações — assíncronas. A ferramenta MCP retorna em menos de um milissegundo; o embed e a inserção no LanceDB acontecem em uma thread em segundo plano.
• Deduplicação — quatro camadas: correspondência exata de texto -> cosseno >= 0,92 mesclagem automática -> cosseno 0,80–0,92 limítrofe (verificação por LLM depois) -> revisão manual no painel. Valores antigos são arquivados, nunca excluídos; histórico completo via keyed_fact_as_of(t).
• Multilíngue — sem pacotes de idioma. O embedder padrão (paraphrase-multilingual-MiniLM-L12-v2) cobre mais de 50 idiomas, então где я живу encontra um fato-chave armazenado como user.city = Warsaw. A detecção de intenção usa âncoras semânticas em inglês que transferem entre idiomas, e o caminho lexical frio se autocompila do seu próprio tráfego. A recuperação permanece forte em ~11 idiomas (top-3 ~= 0,9 em uma avaliação de 101 consultas; top-1 = 1,00 para en/fr/pt/ru). Veja docs/contributing/adding-a-language.md.

---

Instalação

O Início rápido acima é tudo que a maioria precisa. Outras formas:

# 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

Conecte um ou mais agentes (todos stdio — o servidor roda como filho do seu agente; sem rede, sem porta, sem token):

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

Aponte vários agentes para uma única memória:

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

Compartilhando uma memória entre máquinas ou equipe? Esse é um modo HTTP opcional com autenticação por bearer-token — veja docs/guide/TEAM.md. Não é necessário para uso local.

Rodando os testes? Use o Python do venv: .venv/bin/python -m pytest (ou .venv\Scripts\python.exe -m pytest no Windows). pytest puro fora do venv apenas relata numpy/fastmcp/typer ausentes.

---

Folha de referência da 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

Passo a passo por agente: docs/guide/usage.md. Referência completa: docs/reference/COMMANDS.md.

---

Hooks — memória que não espera ser solicitada

A parte difícil da memória do agente não é armazenar — é fazer o agente usar o que está armazenado. Instruções suaves em um arquivo de regras são ignoradas. Então o PMB conecta hooks no nível do protocolo (pmb hooks install claude-code), cada um removendo uma dependência de o modelo lembrar de agir:

• UserPromptSubmit -> recuperação automática. Cada mensagem é classificada (regex, multilíngue, sub-ms) e a memória correspondente — lições, decisões passadas, resultados de recuperação, visão geral do projeto — é injetada antes de o modelo pensar. Mensagens triviais não injetam nada.
• PostToolUse -> observação ambiente. Cada ferramenta que o agente executa é anexada a um diário de ações leve (um único INSERT no SQLite, sem modelo). Leituras e ls são filtradas; edições, testes e commits são mantidos.
• SessionStart -> restauração de sessão. Após uma compactação de contexto, o agente reconstrói "de onde você parou" a partir do que a sessão registrou, em vez de perguntar novamente.
• Stop -> acompanhamento + gravação automática ambiente. (a) Ele verifica quais lições exibidas realmente apareceram no que o agente fez e as marca como seguidas, deterministicamente. (b) Se o agente NÃO chamou uma ferramenta record_*, ele sintetiza uma entrada de atividade a partir das ações observadas — então o trabalho real é capturado mesmo quando o agente permanece em silêncio.

Visualize qualquer um sem um agente: pmb auto-context "...", pmb session-restore -m 180, pmb lesson-followcheck --dry-run, pmb autowrite --dry-run.

Memória ambiente — o lado da gravação

A recuperação automática corrigiu o lado da leitura; a memória ambiente faz o mesmo para o lado da gravação — o diário de memória registra o trabalho do agente mesmo quando ele esquece record_batch:

• Coordenada. Se o agente já chamou uma ferramenta record_* nesta rodada, a memória ambiente permanece em silêncio; ela apenas preenche a lacuna.
• Pontuada por resultado, não por volume. Uma rodada é registrada apenas se os resultados passarem em um padrão de qualidade (testes passaram, uma falha foi corrigida, um deploy rodou), não apenas pela contagem de arquivos.
• Honesta e reversível. Cada entrada ambiente é marcada como source=autowrite, exibida como automática no painel e removível com pmb forget-auto. Ativada por padrão; desative com pmb config set autowrite.enabled false.
• Funciona em todos os hosts. Claude Code (hooks), Codex (pmb codex-notify), hosts apenas com MCP como Cursor/Zed/VS Code (observador git, pmb ambient-watch .). Verifique o seu com pmb hooks capabilities.

A síntese é baseada em modelos por padrão (instantânea, sem modelo). Opte por um resumo com modelo local/API/CLI com pmb config set autowrite.synthesizer llm:ollama ou llm:openai (com timeout e fallback para o modelo).

Loop de autoaperfeiçoamento

Cada lição exibida carrega um surface_id. O acompanhamento é registrado de duas formas: o agente confirma via mark_lesson_followed(surface_id, True), e o hook Stop o infere da atividade registrada. A aba Lições então mostra, por regra: com que frequência foi exibida, com que frequência foi seguida, ★ USEFUL (seguida >= 2x), ? UNVERIFIED (exibida mas não confirmada) e 💀 DEAD apenas quando uma regra é repetidamente ignorada (>= 2). Você vê quais regras ajudam e poda as que não ajudam.

---

Configurações — 25 que importam, 80 que não importam

O PMB tem 105 ajustes. Os 25 que afetam a qualidade do dia a dia são de nível padrão (pmb config list). O restante são pesos internos e flags experimentais, ocultos atrás de --pro para que a superfície permaneça escaneável. Cada chave pro ainda é lida com pmb config get e gravada com pmb config set — oculta de list, não bloqueada.

Chave	Padrão	O que faz
recall.top_k	5	Quantos resultados o recall retorna
recall.bm25_weight	0.7	Mistura BM25 vs vetorial (1.0 = BM25 puro)
recall.ppr_enabled	true	Difusão de grafo multi-salto, controlada por intenção
recall.keyed_fact_boost	0.35	O quanto fatos de atributos pessoais pesam em consultas pessoais
recall.rerank	false	Cross-encoder sempre ativo (regride LoCoMo, mantenha desligado)
embedding.model	paraphrase-multilingual-MiniLM-L12-v2	O modelo vetorial
graph.extractor	regex	regex / spacy / llm:claude / llm:openai / llm:ollama / llm:codex
mcp.record_batch_async	true	Gravações fire-and-forget (retorno em sub-ms)
agent.apply_lessons	true	O agente apresenta lições antes de agir
dedup.enable	true	Todas as quatro camadas de deduplicação
decay.factor_per_day	0.985	Meia-vida de importância
chat.model	haiku	Modelo padrão para pmb-chat

---

Números

Recall p50 / p95 quente	35 ms / 110 ms
prepare(message) quente	4-16 ms
record_batch_async	< 1 ms
Inicialização a frio do MCP	3,7 s
LoCoMo recall@10 (n=10)	94,5 %
Mega-estresse multilíngue top-10 (900 q)	99,2 %

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

---

Privacidade

• 100 % offline por padrão. Sem chamadas de rede do mecanismo, zero telemetria - não existe servidor PMB para chamar.
• Workspace = um diretório sob ~/.pmb/<name>/. Copie para o Dropbox, envie para o git, compartilhe em um pendrive. Você decide.
• Segredos são automaticamente redigidos no momento da gravação (chaves OpenAI / Anthropic / AWS / Stripe / GitHub; configurável).
• Licenciado sob Apache 2.0. Forks são bem-vindos.

---

FAQ

O PMB chama um LLM? Na leitura: nunca. Na gravação: nunca por padrão. Opcional: pmb consolidate pode executar um Ollama local, Claude CLI, Anthropic ou OpenAI para escrever reflexões curtas - opt-in.

E quanto ao custo? $0. Não existe serviço PMB.

O agente precisa saber sobre o PMB? Após pmb connect, as regras são anexadas a CLAUDE.md / AGENTS.md automaticamente. O perfil padrão expõe 10 ferramentas MCP principais (incluindo o padrão de leitura-primeiro prepare()); perfis mais amplos existem para ingestão e administração.

Isso deixará meu agente mais lento? As ferramentas retornam em milissegundos de dígito único para tudo, exceto recall (35-110 ms quente), que está abaixo da percepção humana.

Dois agentes podem compartilhar uma memória? Sim - aponte-os para o mesmo workspace. SQLite WAL + um timeout de busy de 10 s lidam com gravações concorrentes.

Apagar um fato? pmb forget <ulid> o arquiva (excluído do recall, restaurável). Exclusão definitiva: pmb delete <ulid> --hard.

Windows? Sim - testado no Windows 11, macOS 14, Ubuntu 22.04. Caminhos cirílicos e codificação de console são tratados.

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

Inicialização a frio é lenta. O primeiro recall carrega o modelo de embeddings (~3 s). Execute pmb warmup uma vez, ou deixe a thread de preaquecimento lidar com isso em segundo plano.

Roadmap? Veja docs/ROADMAP.md: backup litestream, sincronização em nuvem opcional (bucket BYO), indexação de projetos com tree-sitter, OCR de imagens.

---

Contribuindo

Issues e PRs são bem-vindos. Há um mantenedor em tempo integral; por favor, abra uma discussão antes de uma mudança grande para alinharmos a direção.

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

Comandos de desenvolvimento

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 instala automaticamente o bundle CodeQL na primeira execução e executa exatamente a suíte que o CI usa, então achados de segurança são capturados localmente em vez de em um push. O hook de pre-commit é ignorado com git commit --no-verify (ou pule apenas a varredura com SKIP_CODEQL=1).

Licença: Apache 2.0.