PMB (Personal Memory Brain)

---

PMB les da a Claude Code, Cursor, Codex y otros agentes compatibles con MCP una memoria real: decisiones que tomaste la semana pasada, lecciones que les enseñaste, datos personales, estructura del proyecto, PDFs. Sobreviven a cada reinicio, cada actualización de modelo, cada cambio de agente, porque viven en un espacio de trabajo local que te pertenece, con SQLite como fuente de verdad duradera e índices de búsqueda reconstruibles a su lado.

Sin claves API. Sin suscripción. Sin llamada LLM en la ruta de lectura. Solo archivos locales.

Inicio 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

Eso es todo: tu agente ahora recuerda. Sin cuenta, sin claves, nada sale de tu máquina.

Nombre del comando: la CLI es pmb. A través de pip también obtienes el alias pmb-ai; a través de npm (npx pmb-ai setup) el comando es pmb-ai y instala el paquete de Python primero, luego ejecuta la configuración. Misma herramienta: usa la que tu instalación te haya dado.

Enlaces: pmbai.dev (sitio) · docs.pmbai.dev (documentación) · Cómo empezar · Eliminar memorias.

---

Demo

Cómo se siente: el mismo prompt, con y sin memoria:

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.

El agente no preguntó. No adivinó. Leyó su memoria en 6 ms y apareció ya informado.

---

Por qué PMB

• Local-first, cero configuración. SQLite guarda la memoria duradera; los índices de búsqueda reconstruibles permanecen locales. Sin cuenta, claves API, telemetría ni nube en la que confiar.
• Realmente se usa. En Claude Code / Codex, los hooks inyectan la memoria correcta antes de que el modelo piense: nunca tienes que acordarte de llamar a una herramienta.
• Multilingüe, sin configuración. El embedder cubre más de 50 idiomas; una consulta en ruso encuentra un dato en inglés. Sin configuración por idioma.
• Nativo de MCP. Un pmb connect conecta Claude Code, Cursor, Codex, Windsurf, Zed, VS Code y más.
• Ruta de lectura rápida. Recuperación en ~35 ms en caliente; las escrituras devuelven en menos de un milisegundo: sin llamada LLM para recordar.
• Impacto honesto. El panel muestra qué lecciones realmente cambiaron resultados, en lugar de afirmar "+X%".
• Tus datos, abiertos. pmb export exporta todo a Markdown/JSON. Apache 2.0.

---

Ve tu memoria

pmb dashboard abre una interfaz web local de cristal líquido en http://127.0.0.1:8765 sobre todo lo que PMB capturó, escrito automáticamente, solo con trabajar. Se vincula solo a 127.0.0.1, así que nada sale de tu máquina.

Nueve pestañas: Mapa (gráfico de entidades, en vivo), Línea de tiempo (gráfico git por proyecto), Resumen, Entidades, Arcos (hilos narrativos), Lecciones (tasa de seguimiento por regla, detección de lecciones muertas), Duplicados (fusión en línea), Rendimiento (latencia por herramienta), Recuperación (depurador del clasificador).

---

Qué puedes almacenar

# 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 es agnóstico al contenido. Si es texto que al agente le importará más tarde, PMB lo recuerda y lo recupera.

Qué recibe el agente

Una sola llamada MCP, prepare(message), devuelve lo correcto al nivel de detalle correcto, en 4-16 ms:

Campo	Qué es
project_context	Resumen completo del proyecto si el mensaje menciona un proyecto: datos clave, lecciones (REGLAS a seguir), decisiones, objetivos abiertos, entidades relacionadas, el arco narrativo del proyecto
lessons	Reglas procedimentales que coinciden con la consulta, cada una con un surface_id para que el agente pueda confirmar que siguió la regla después
recent_activity	Últimas 24 h de decisiones / ediciones / finalizaciones para continuidad de sesión
open_goals	Objetivos en curso para que el agente sepa qué estás persiguiendo
active_arcs	Arcos narrativos en los que el proyecto vive actualmente

Para todo lo demás está recall(query) (búsqueda híbrida, 35 ms en caliente) y otras 27 herramientas en docs/reference/COMMANDS.md.

---

Cómo 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

• Almacenamiento: cada evento duradero vive en SQLite, la fuente de verdad. Los índices vectoriales reconstruibles viven en LanceDB a su lado. Todo el espacio de trabajo permanece en tu disco y se puede copiar o exportar en cualquier momento.
• Recuperación: BM25 (léxico) + vector denso (semántico) + gráfico de entidades + reordenamiento opcional con cross-encoder, fusionados mediante Reciprocal-Rank-Fusion.
• Escrituras: asíncronas. La herramienta MCP devuelve en menos de un milisegundo; el embed y la inserción en LanceDB ocurren en un hilo en segundo plano.
• Deduplicación: cuatro capas: coincidencia exacta de texto -> coseno >= 0.92 fusión automática -> coseno 0.80-0.92 límite (verificación LLM después) -> revisión manual en el panel. Los valores antiguos se archivan, nunca se eliminan; historial completo mediante keyed_fact_as_of(t).
• Multilingüe, sin paquetes de idioma. El embedder predeterminado (paraphrase-multilingual-MiniLM-L12-v2) cubre más de 50 idiomas, así que где я живу encuentra un dato clave almacenado como user.city = Warsaw. La detección de intención usa anclas semánticas en inglés que se transfieren entre idiomas, y la ruta léxica en frío se autocompila con tu propio tráfico. La recuperación se mantiene fuerte en ~11 idiomas (top-3 ~= 0.9 en una evaluación de 101 consultas; top-1 = 1.00 para en/fr/pt/ru). Consulta docs/contributing/adding-a-language.md.

---

Instalación

El Inicio rápido de arriba es todo lo que la mayoría necesita. Otras 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

Conecta uno o más agentes (todos stdio: el servidor se ejecuta como hijo de tu agente; sin red, sin puerto, sin token):

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

Apunta varios agentes a una sola memoria:

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

¿Compartir una memoria entre máquinas o un equipo? Eso es un modo HTTP opcional con autenticación por bearer-token: consulta docs/guide/TEAM.md. No es necesario para uso local.

¿Ejecutando las pruebas? Usa el Python del venv: .venv/bin/python -m pytest (o .venv\Scripts\python.exe -m pytest en Windows). pytest desnudo fuera del venv solo informa que faltan numpy/fastmcp/typer.

---

Hoja de referencia de la 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

Paso a paso por agente: docs/guide/usage.md. Referencia completa: docs/reference/COMMANDS.md.

---

Hooks: memoria que no espera a que le pregunten

La parte difícil de la memoria del agente no es almacenar, es lograr que el agente use lo almacenado. Las instrucciones suaves en un archivo de reglas se omiten. Así que PMB conecta hooks a nivel de protocolo (pmb hooks install claude-code), cada uno eliminando una dependencia de que el modelo recuerde actuar:

• UserPromptSubmit -> auto-recuperación. Cada mensaje se clasifica (regex, multilingüe, sub-ms) y la memoria coincidente (lecciones, decisiones pasadas, resultados de recuperación, resumen del proyecto) se inyecta antes de que el modelo piense. Los mensajes triviales no inyectan nada.
• PostToolUse -> observación ambiental. Cada herramienta que ejecuta el agente se agrega a un diario de acciones ligero (un solo INSERT en SQLite, sin modelo). Las lecturas y ls se filtran; las ediciones, pruebas y confirmaciones se conservan.
• SessionStart -> restauración de sesión. Después de una compactación de contexto, el agente reconstruye "dónde te quedaste" a partir de lo que la sesión registró, en lugar de volver a preguntarte.
• Stop -> seguimiento + escritura ambiental automática. (a) Verifica qué lecciones mostradas realmente aparecieron en lo que el agente hizo y las marca como seguidas, de manera determinista. (b) Si el agente NO llamó a una herramienta record_*, sintetiza una entrada de actividad a partir de las acciones observadas, para que el trabajo real se capture incluso cuando el agente permanece en silencio.

Vista previa de cualquiera sin un agente: pmb auto-context "...", pmb session-restore -m 180, pmb lesson-followcheck --dry-run, pmb autowrite --dry-run.

Memoria ambiental: el lado de la escritura

La auto-recuperación arregló el lado de la lectura; la memoria ambiental hace lo mismo para el lado de la escritura: el diario de memoria registra el trabajo del agente incluso cuando olvida record_batch:

• Coordinada. Si el agente ya llamó a una herramienta record_* en este turno, la ambiental permanece en silencio; solo llena el vacío.
• Calificada por resultados, no por actividad. Un turno se registra solo si los resultados superan un umbral de calidad (pruebas pasadas, una falla corregida, un despliegue ejecutado), no solo por cantidad de archivos.
• Honesta y reversible. Cada entrada ambiental está etiquetada como source=autowrite, se muestra como automática en el panel y se puede eliminar con pmb forget-auto. Activada por defecto; desactívela con pmb config set autowrite.enabled false.
• Funciona en todos los hosts. Claude Code (hooks), Codex (pmb codex-notify), hosts solo MCP como Cursor/Zed/VS Code (observador git, pmb ambient-watch .). Verifica el tuyo con pmb hooks capabilities.

La síntesis se basa en plantillas por defecto (instantánea, sin modelo). Opta por un resumen con modelo local/API/CLI con pmb config set autowrite.synthesizer llm:ollama o llm:openai (tiene un tiempo de espera y vuelve a la plantilla).

Bucle de auto-mejora

Cada lección mostrada lleva un surface_id. El seguimiento se registra de ambas formas: el agente confirma mediante mark_lesson_followed(surface_id, True), y el hook Stop lo infiere de la actividad registrada. La pestaña Lecciones muestra entonces, por regla: con qué frecuencia se mostró, con qué frecuencia se siguió, ★ USEFUL (seguida >= 2 veces), ? UNVERIFIED (mostrada pero sin confirmar), y 💀 DEAD solo cuando una regla se ignora repetidamente (>= 2). Ves qué reglas ayudan y podas las que no.

---

Configuración: 25 que te importan, 80 que no

PMB tiene 105 parámetros ajustables. Los 25 que afectan la calidad diaria son de nivel predeterminado (pmb config list). El resto son pesos internos y banderas experimentales, ocultos detrás de --pro para que la superficie siga siendo escaneable. Cada clave pro aún se lee con pmb config get y se escribe con pmb config set: oculta de list, no restringida.

Clave	Predeterminado	Qué hace
recall.top_k	5	Cuántos resultados devuelve la recuperación
recall.bm25_weight	0.7	Mezcla BM25 vs vector (1.0 = BM25 puro)
recall.ppr_enabled	true	Difusión de gráfico multi-salto, controlada por intención
recall.keyed_fact_boost	0.35	Qué tanto ganan los datos de atributos personales en consultas personales
recall.rerank	false	Cross-encoder siempre activo (regresa LoCoMo, mantenlo apagado)
embedding.model	paraphrase-multilingual-MiniLM-L12-v2	El modelo vectorial
graph.extractor	regex	regex / spacy / llm:claude / llm:openai / llm:ollama / llm:codex
mcp.record_batch_async	true	Escrituras de disparar y olvidar (retorno sub-ms)
agent.apply_lessons	true	El agente muestra lecciones antes de actuar
dedup.enable	true	Las cuatro capas de deduplicación
decay.factor_per_day	0.985	Vida media de importancia
chat.model	haiku	Modelo predeterminado para pmb-chat

---

Números

Recuerdo p50 / p95 en caliente	35 ms / 110 ms
prepare(message) en caliente	4-16 ms
record_batch_async	< 1 ms
Arranque en frío de MCP	3.7 s
LoCoMo recall@10 (n=10)	94.5 %
Mega-estrés multilingüe top-10 (900 preguntas)	99.2 %

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

---

Privacidad

• 100 % sin conexión por defecto. Sin llamadas de red desde el motor, cero telemetría: no hay servidor PMB al que llamar a casa.
• El espacio de trabajo es un directorio bajo ~/.pmb/<name>/. Cópialo a Dropbox, súbelo a git, compártelo en una unidad USB. Tú decides.
• Los secretos se redactan automáticamente al escribir (claves de OpenAI / Anthropic / AWS / Stripe / GitHub; configurable).
• Licencia Apache 2.0. Las bifurcaciones son bienvenidas.

---

Preguntas frecuentes

¿PMB llama a un LLM? Al leer: nunca. Al escribir: nunca por defecto. Opcional: pmb consolidate puede ejecutar un paso con Ollama local, CLI de Claude, Anthropic u OpenAI para escribir breves reflexiones: opcional.

¿Y el costo? $0. No hay servicio PMB.

¿El agente necesita saber sobre PMB? Después de pmb connect, las reglas se añaden a CLAUDE.md / AGENTS.md automáticamente. El perfil predeterminado expone 10 herramientas MCP principales (incluido el patrón de lectura primero de prepare()); existen perfiles más amplios para ingesta y administración.

¿Ralentizará a mi agente? Las herramientas responden en milisegundos de un solo dígito para todo excepto recall (35-110 ms en caliente), que está por debajo de la percepción humana.

¿Pueden dos agentes compartir una memoria? Sí: apúntalos al mismo espacio de trabajo. SQLite WAL + un tiempo de espera de 10 s manejan escrituras concurrentes.

¿Borrar un dato? pmb forget <ulid> lo archiva (excluido del recuerdo, restaurable). Borrado definitivo: pmb forget <ulid> --hard.

¿Windows? Sí: probado en Windows 11, macOS 14, Ubuntu 22.04. Rutas cirílicas y codificación de consola están gestionadas.

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

El arranque en frío es lento. El primer recuerdo carga el modelo de incrustación (~3 s). Ejecuta pmb warmup una vez, o deja que el hilo de precalentamiento lo maneje en segundo plano.

¿Hoja de ruta? Ver docs/ROADMAP.md: copia de seguridad con litestream, sincronización en la nube opcional (bucket propio), indexación de proyectos con tree-sitter, OCR de imágenes.

---

Contribuciones

Se aceptan issues y PRs. Hay un único mantenedor a tiempo completo; abre una discusión antes de un cambio grande para alinearnos en la dirección.

git clone https://github.com/oleksiijko/pmb.git && cd pmb
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest                  # full suite, ~4 minutes
pytest -k recall        # fast subset, ~12 s

Comandos de desarrollo

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 automáticamente el paquete CodeQL en la primera ejecución y ejecuta la misma suite exacta que usa CI, para que los hallazgos de seguridad se detecten localmente en lugar de en un push. El hook de pre-commit se omite con git commit --no-verify (o salta solo el escaneo con SKIP_CODEQL=1).

Licencia: Apache 2.0.