Projectmem

🎉 ¡v0.3.2 ya está disponible! — Soporte para Windows en el observador de archivos, y un doctor que detecta cuando una corrección se deshace. Ver qué cambió →

No hacemos que la IA sea más inteligente. Hacemos que tenga experiencia.

Memoria para agentes de codificación — la capa de memoria y juicio local-first para agentes de codificación con IA. Un servidor MCP para cada proyecto. Ahorra hasta un 50%+ de tokens de IA. Deja de repetir el error de ayer.

Sitio web • Guía • Demo • Registro de cambios • Documento técnico

_{pjm visualize — cada caso que tu proyecto resolvió, lo que falló en el camino y lo que ahorró. Generado localmente desde .projectmem/events.jsonl.}

🚀 Empieza aquí — cinco minutos, una vez

Cinco minutos si sigues esta guía. ¿Prefieres que te lo muestren — cada comando, la salida exacta que imprime y los paneles al final? Sigue la guía de configuración completa.

¿Nuevo en projectmem, o actualizando desde 0.1.x / 0.2.x? Desde 0.3.0 un solo servidor MCP sirve a todos los proyectos, así que esta es la última vez que configuras algo.

1. Instala o actualiza

pip install -U projectmem

2. Encuentra los proyectos que ya tienes

pjm doctor

Busca dónde vive el código — ~/Developer, ~/code, ~/projects, tus carpetas en la nube y cada unidad en Windows — y lista los proyectos con memoria que aún no están registrados. Cualquier cosa que haya omitido, añádela a mano:

pjm project register "/Users/you/Developer/repos/ossdrop"

3. Regístralos

pjm doctor --fix

4. Apunta tu IA a todos ellos con una sola configuración

"mcpServers": {
  "projectmem": {
    "command": "/absolute/path/to/python",
    "args": ["-m", "projectmem.mcp_server"]
  }
}

Sin --root, sin cwd — eso es lo que hace que sirva a todo. Instrucciones por cliente (Claude Desktop, Claude Code, Cursor, Antigravity, Codex) están en Integración MCP; pjm init imprime este bloque con tu propia ruta de Python completada. Luego reinicia el cliente por completo — los servidores MCP solo se cargan en un arranque en frío.

5. Verifica tu trabajo

pjm doctor

Añade --online si también quieres que te avise cuando haya una versión más nueva de projectmem — projectmem no hace llamadas de red de otro modo, y --auto convierte eso en una verificación diaria si lo prefieres.

Ejecútalo de nuevo después de editar la configuración. Marca cualquier cliente que siga anclado a un solo repositorio — la razón más común por la que un proyecto nuevo es invisible para tu agente.

¿Todo en verde? Has terminado. De aquí en adelante es un comando por repositorio:

pjm init

Tu agente lee lo que el proyecto ya aprendió en lugar de redescubrirlo, y anota lo que encuentra. Menos tokens, sin callejones sin salida repetidos, memoria que sobrevive a la sesión.

¿Qué es la memoria para agentes de codificación?

La memoria para agentes de codificación es un registro persistente de lo que sucedió mientras se construía un proyecto — los problemas encontrados, los enfoques probados, las correcciones que funcionaron y las decisiones tomadas — almacenado para que un agente de codificación con IA pueda leerlo al inicio de una nueva sesión. Sin ella, cada sesión comienza desde cero.

projectmem es una capa de memoria de agente de código abierto construida para esa tarea. Es local-first: la memoria vive en un directorio .projectmem/ simple dentro de tu repositorio, sin nube, sin cuenta y sin telemetría — la única llamada de red que puede hacer es una verificación de actualizaciones que tú mismo activas. Un servidor MCP nativo expone 17 herramientas a Claude Code, Claude Desktop, Cursor, Antigravity y Codex, para que tu agente lea la memoria y registre su trabajo por sí solo.

A diferencia de las herramientas de memoria de historial de chat, projectmem almacena eventos tipados — problemas, intentos, correcciones, decisiones, notas — que es lo que hace posible lo que ninguna otra herramienta hace: una advertencia previa al commit que se activa antes de que repitas un enfoque que ya falló.

pip install projectmem
cd your-project && pjm init

🎬 Mira la demo

Tutorial completo grabado en pantalla — míralo en YouTube

📚 Documentación

El problema

Cada nueva sesión de IA comienza desde cero. Claude, Cursor, Aider — todos olvidan las decisiones de ayer, repiten intentos de depuración fallidos y queman millones de tokens reconstruyendo contexto a partir de archivos fuente sin procesar.

El modelo no es el problema. La arquitectura lo es. Los modelos sin estado necesitan una corteza de memoria.

La solución

projectmem es la capa de memoria y juicio local-first que se sitúa sobre tus herramientas de IA. Captura cada intento fallido, decisión y detalle — luego inyecta esa experiencia de nuevo en las sesiones futuras de IA. Git rastrea qué cambió. projectmem rastrea por qué cambió, qué se probó y qué falló.

Instalación

¿Primera vez aquí? → La guía de configuración completa recorre todo el camino de principio a fin: instalación, conexión de Claude Desktop, Claude Code, Cursor, Codex o Antigravity, verificación con pjm doctor y lectura de tu memoria a través de los paneles — con la salida real de terminal en cada paso.

Tres comandos para un proyecto que recuerda:

pip install projectmem
cd your-project
pjm init

Eso es todo. pjm init instala tres ganchos de git (advertencias previas al commit, clasificación posterior al commit, seguimiento posterior al merge), inicia automáticamente un observador de archivos en tiempo real, hereda memoria entre proyectos si está disponible y crea .projectmem/. La captura está activa desde el primer minuto.

El comando canónico es projectmem. Se instala un alias pjm para mayor velocidad.

✨ Nuevo en 0.3.2 — Windows, correctamente

pjm watch --daemon fallaba en Windows con AttributeError: module 'os' has no attribute 'fork'. Ahora genera un trabajador separado en lugar de bifurcar, por lo que la observación en segundo plano funciona en todas las plataformas.

Corregir eso descubrió un segundo error oculto detrás. La actividad se verificaba con os.kill(pid, 0) — un modismo POSIX que no se traslada, porque en Windows os.kill se enruta a TerminateProcess y la señal 0 no es una verificación en absoluto. El observador no podía verse ni detenerse allí, y cada pjm watch --daemon filtraba otro proceso. Ambos están corregidos.

El soporte de daemon en Windows fue contribuido por @medium-effort (#13).

pjm doctor también recibió dos cosas. Ahora te dice que cierres tu cliente de IA antes de editar su configuración — esos archivos también contienen las preferencias de la propia aplicación, por lo que un cliente en ejecución puede reescribir todo al salir y restaurar el --root que acabas de eliminar. Y recuerda lo que vio la última vez, por lo que una configuración que estaba limpia y vuelve a estar anclada se nombra como una reversión en lugar de parecer que el doctor falla. Solo archivos locales; nada sale de tu máquina.

✨ Nuevo en 0.3.1 — saber cuándo actualizar

Ambos paneles ahora muestran qué versión generó la página, con un enlace de verificar actualizaciones junto a él. La página no hace ninguna solicitud hasta que haces clic — el JSON público de PyPI se obtiene directamente desde tu navegador y no se envía nada sobre tu máquina. En la línea de comandos, pjm doctor --online verifica una vez y pjm doctor --auto recuerda verificar a diario; ambos están desactivados a menos que lo pidas.

✨ Nuevo en 0.3.0 — un servidor, muchos proyectos

Hasta ahora una configuración de MCP estaba vinculada a un repositorio: once proyectos significaban once entradas de servidor y once reinicios. 0.3.0 sirve a cada proyecto registrado desde un solo servidor. Pega la configuración una vez; cada repositorio que pjm init después es accesible desde él.

pjm project list          # what this server can reach
pjm project use ossdrop   # the default when a call names no project

log_issue(summary="stars come back empty", project="ossdrop")
→ Logged issue #0019 → ossdrop: stars come back empty

Cada escritura nombra el proyecto en el que aterrizó — en un servidor compartido, el fallo peligroso no es "nada funciona", es una escritura que tiene éxito contra el repositorio equivocado. Las configuraciones --root existentes siguen funcionando sin cambios, y un servidor anclado ahora se niega a escribir en cualquier otro lugar incluso si se le pide.

También en 0.3.0:

• Corregido: el servidor MCP estaba roto en instalaciones nuevas. mcp 2.0 renombró FastMCP y dejó la ruta de importación antigua generando un error — desde 2026-07-28 cada pip install projectmem nuevo obtenía un servidor que moría al importar. Detectado y corregido por @VIVAAN-DHAWAN.
• Seguridad: XSS almacenado en pjm visualize. Los resúmenes de eventos llegaban al DOM sin escapar, y los mensajes de commit de git se convierten en resúmenes de eventos — por lo que un commit manipulado en una rama que descargaste podía ejecutar script en tu panel. Cada sumidero está escapado ahora.
• Un panel reconstruido — una Tarjeta de Memoria compartible, archivos de caso con la cadena completa problema → intento → corrección, un mapa de árbol de esfuerzo, expedientes por archivo y una vista global que se abre donde lo dejaste.

La migración del registro es automática: la lista de rutas de 0.2.x se convierte en la primera lectura, con un .bak guardado junto a ella.

✨ Nuevo en 0.2.0 — la versión del espacio de trabajo

0.1.6 hizo que la memoria de un proyecto fuera algo que pudieras observar. 0.2.0 eleva eso a todo tu espacio de trabajo — y cierra la brecha entre lo que sucedió (memoria) y lo que tu código es (estructura).

• 🌐 Panel global — pjm dashboard es una página que abarca todos los proyectos que has pjm init-ed: total de problemas capturados, correcciones confirmadas, callejones sin salida evitados, tokens ahorrados, una calificación por proyecto y una lista de "requiere atención". Haz clic en cualquier tarjeta para abrir el panel propio de ese repositorio, generado al momento. Es una vista global, no un almacén global — el .projectmem/ de cada repositorio se agrega en tiempo de lectura y nunca sale de su carpeta. El valor predeterminado es sin servidor (una instantánea estática); añade --serve para un servidor en vivo pequeño y efímero donde el botón Actualizar vuelve a leer tus archivos — sin demonio en segundo plano, Ctrl+C lo detiene.
• 🧬 Estructura y relaciones — pjm map --build (se ejecuta automáticamente en pjm init) recorre tu código y, para Python, resuelve las importaciones en un grafo de dependencias real. Las vistas Graph y Flow del Mapa del Proyecto ahora renderizan archivos reales y las aristas de importación entre ellos. La caché (structure.json) se deriva del código, está en gitignore y nunca se confirma — el código solo se lee.
• 🔥 Calor de fallos sobre la estructura (la combinación) — la única vista que un graficador de código puro no puede dibujar y una herramienta de memoria pura tampoco: los archivos con intentos fallidos repetidos brillan en rojo, colocados directamente sobre el grafo de importaciones real. La estructura proviene del código, el calor proviene de tu memoria, y solo se encuentran en el renderizador.
• 🗂️ plan.md — un nuevo archivo de intención editable: ideas y planes, lo que pretendes hacer — deliberadamente no el registro de eventos. events.jsonl → summary.md registra lo que sucedió; plan.md registra lo que pretendes. La IA lo lee al inicio de la sesión y lo edita directamente; un plan nunca se convierte en un evento. pjm plan / pjm plan "idea" / MCP get_plan().

Todo sigue siendo 100% local — el panel global es un agregado en tiempo de lectura, nunca un honeypot central del historial de tu código.

Panel Global — cada proyecto pjm init-ed en una vista: calificaciones, problemas, ahorros y una lista de "requiere atención", agregados en tiempo de lectura. Cada tarjeta abre el panel propio de ese repositorio.

El conjunto de visualizaciones (incluido en 0.1.6)

La memoria de tu proyecto también es algo que puedes ver — y compartir.

• 🎬 Showoff — una pestaña del panel con tres escenas de historia animadas, todas renderizadas desde tu registro de eventos real: Story Replay (observa cómo se construye el historial de tu proyecto, nodo por nodo), Orbit (los archivos orbitan el proyecto, los eventos orbitan su archivo) y Universe (tu proyecto como una galaxia giratoria — cada estrella brillante es un problema, intento, corrección o decisión real; haz clic en uno para ver sus detalles completos).
• ⏺ Grabador integrado — pulsa REC (10–60 s) y Showoff descarga un clip .webm de la animación, renderizado 100% localmente con una insignia de "hecho con projectmem". Tu historia de depuración, lista para un tweet o una reunión diaria.
• 🗺️ Flow — la vista predeterminada del Mapa del Proyecto: un diagrama de flujo en capas que lee PROJECT → DIRECTORIES → FILES → WHAT HAPPENED → MEMORY. Los archivos con fallos repetidos brillan en rojo a lo largo de su ruta, cada archivo muestra sus chips de resultado, y todo fluye hacia el cilindro events.jsonl. Las vistas Tree y Graph están a un clic de distancia.
• 🧵 Time Spine — la vista predeterminada de la Línea de Tiempo: un eje en tiempo real que puedes desplazar, con problemas ramificándose a la izquierda (problemas, intentos fallidos) y conocimiento ramificándose a la derecha (correcciones, decisiones, notas). Pasa el cursor sobre cualquier tarjeta y todo su hilo de problemas se ilumina. La lista clásica permanece como "Details".

Showoff · Universe — cada estrella brillante es un evento real de la memoria de este proyecto

Mapa del Proyecto · Flow — lo que sucedió, archivo por archivo, fluyendo hacia la memoria de solo añadido

Línea de Tiempo · Time Spine — problemas a la izquierda, conocimiento a la derecha, tiempo real en el medio

Por Qué Te Encantará

• Advertencias Pre-Confirmación — pjm precheck te advierte antes de confirmar si estás a punto de repetir un enfoque fallido, modificar un archivo de alta rotación o tocar un problema sin resolver. Ninguna otra herramienta de IA hace esto — requiere la capa de memoria subyacente. La advertencia ahora enumera los callejones sin salida en sí ("Lo que ya falló aquí: ✗ intentó CSS contain:layout"), y pjm precheck --snooze 2h lo silencia cortésmente — la posposición en sí se registra, por lo que incluso el silencio se audita.
• Detección de Memoria Obsoleta (nuevo en 0.1.4) — otras herramientas de memoria decaen o eliminan silenciosamente memorias antiguas; projectmem nunca elimina. Cada decisión que cita un archivo se verifica cruzadamente con el historial de git de ese archivo — cuando el archivo ha avanzado, la memoria se marca ("predata 7 confirmaciones a auth.py — confirma o reemplaza") y un humano decide. Retírala limpiamente con pjm decision "new way" --supersedes <id>: el evento antiguo permanece en el registro, etiquetado, para siempre.
• Informe de Inicio de Sesión (nuevo en 0.1.4) — pjm brief responde "¿dónde estaba?" en una pantalla: advertencias activas, memorias posiblemente obsoletas, problemas abiertos, decisiones recientes, trampas de la pila y tu puntuación de prevención con un delta semana a semana.
• Memoria para agentes sin MCP (nuevo en 0.1.4) — pjm export --claude-md compila decisiones en vivo, trampas y una lista de "NO reintentar — estos ya fallaron" en un bloque marcado en CLAUDE.md (o .cursorrules). Copilot, Claude simple, cualquier agente que lea el archivo hereda el juicio de tu proyecto.
• Inyección de Contexto Inteligente — pjm wrap claude (o cursor/aider) inyecta un bloque de memoria con presupuesto de tokens en tu IA antes de que se abra la sesión. Tu IA comienza con experiencia, no en blanco.
• Puntuación ROI Demostrable — pjm score genera una calificación con letras (A+ → F) respaldada por números concretos — horas de depuración ahorradas, tokens prevenidos, dólares protegidos. Salida JSON compatible con CI y insignia shields.io para tu README.
• Memoria Entre Proyectos — Las lecciones aprendidas en un repositorio te siguen para siempre. Las trampas de bibliotecas, decisiones y patrones viven en ~/.projectmem/global/ y se heredan automáticamente en cada nuevo proyecto que coincida con tu pila.
• Vigilante de Archivos en Tiempo Real — El demonio en segundo plano detecta ediciones rápidas al mismo archivo (sesiones de depuración) entre confirmaciones. Consciente de la batería, consciente de gitignore, iniciado automáticamente por pjm init.
• Servidor MCP Nativo — Se conecta a Claude Desktop, Cursor, Antigravity, Codex y cualquier herramienta compatible con MCP. 15 herramientas nativas obligan a la IA a leer el contexto, verificar archivos para fallos conocidos, leer tu plan.md y registrar el trabajo automáticamente. Verificado de extremo a extremo contra los cuatro clientes.
• Panel Interactivo (ampliado en 0.1.6) — pjm visualize abre un panel local de seis pestañas: Overview, Story Map (mapa de calor de fallos con controles de colapso/enfoque), ROI Dashboard, Project Map (Flow / Tree / Graph, ahora sobre tu estructura de código real), Timeline (Time Spine / Details) y Showoff — escenas de historia animadas con un grabador de video integrado.
• Un servidor MCP para cada proyecto (nuevo en 0.3.0) — configura tu cliente una vez en lugar de una vez por repositorio. Las llamadas nombran su proyecto (project="ossdrop"), o recurren al activo; cada escritura informa en qué repositorio aterrizó, y un servidor --root fijado se niega a escribir fuera del suyo. Las configuraciones existentes de un solo proyecto no se tocan.
• Panel Global (nuevo en 0.2.0) — pjm dashboard es una vista entre proyectos sobre cada repositorio que has pjm init-ed: calificaciones, problemas, ahorros y desglose por proyecto. Una vista global, nunca un almacén global — la memoria de cada repositorio se agrega en tiempo de lectura y nunca sale de su carpeta. Sin servidor por defecto; --serve para un servidor en vivo efímero (Ctrl+C para detener).
• Estructura de Código + Juicio (nuevo en 0.2.0) — pjm map --build lee tu código en un grafo de importaciones real, y el Mapa del Proyecto superpone calor de fallos de tu registro de eventos encima: los archivos que siguen rompiéndose, brillando en rojo sobre la estructura que realmente los conecta. La caché de estructura se deriva del código y está en gitignore — nunca se confirma.
• Intención, separada de la memoria (nuevo en 0.2.0) — plan.md contiene ideas y planes (lo que pretendes hacer), mantenidos deliberadamente aparte del registro de eventos de solo añadido (lo que sucedió). pjm plan, o el MCP get_plan(); la IA lo edita directamente y un plan nunca se convierte en un evento.
• 100% Local — Sin nube, sin telemetría, sin cuentas. Tu código, tu memoria, tu máquina.

Cómo Se Compara

_{✅ sí · 🟡 parcial · ❌ no — instantánea de junio de 2026; capacidades de diseño, no resultados de benchmarks. claude-mem ejecuta un trabajador en segundo plano (puerto 37777) y habilita telemetría por defecto (v13.5+); agentmemory degrada y poda memorias antiguas mediante decaimiento, mem0 reescribe hechos al actualizar, los bloques de memoria de Letta se autoeditan en su lugar — projectmem nunca elimina: marca la obsolescencia y te deja decidir. Letta requiere un servidor en ejecución (Postgres o nube).}

_{† No hay base de datos y nada que tengas que mantener en ejecución: el servidor MCP es un subproceso stdio que tu cliente de IA genera, y todo lo demás son archivos planos. El único servidor en cualquier lugar es el opcional pjm dashboard --serve, un visor local efímero que inicias y detienes con Ctrl+C — nunca un servicio en segundo plano.}

🚧 Próximamente

• Importa tu memoria existente — pjm import (planificado para 0.3.3) migrará historial de mem0, agentmemory, Letta y registros de sesión de Claude a projectmem. Mapea solo al vocabulario central de eventos — problemas, intentos, correcciones, decisiones, notas — para que la señal entre y el desorden de otra herramienta se quede fuera. Tu historial de juicio se mueve contigo.

¿Quieres una fuente compatible? Abre un problema y cuéntanos desde qué estás migrando.

Cómo la IA Lee Tu Memoria (Eficiencia de Tokens)

La arquitectura se construye alrededor de una regla: la IA lee archivos pequeños y destilados. Las herramientas los generan a partir del registro bruto grande.

La IA nunca lee events.jsonl directamente. Ese archivo es para herramientas (pjm score, pjm context, pjm wrap). Las herramientas destilan el registro bruto en resúmenes compactos legibles por IA.

Un servidor, muchos proyectos

Desde 0.3.0, un único servidor MCP atiende a todos los proyectos que hayas registrado. Pega la configuración una sola vez y cada repositorio que pjm init después será accesible desde él: sin una segunda entrada, sin reiniciar.

pjm project list          # what this server can reach
pjm project use ossdrop   # the default when a call names no project
pjm project alias ossdrop od

Tu agente elige el proyecto en cada llamada:

log_issue(summary="stars come back empty", project="ossdrop")
→ Logged issue #0019 → ossdrop: stars come back empty

Cada escritura indica dónde aterrizó. Ese eco es el punto: en una configuración de un solo proyecto, un servidor mal configurado simplemente falla, pero un servidor compartido puede tener éxito contra el repositorio equivocado, lo que corrompe dos pistas de auditoría a la vez. Si el nombre en la respuesta no es el proyecto que querías, detente.

Cómo se enruta una llamada, de mayor a menor prioridad:

Las raíces del cliente superan al proyecto activo a propósito: la raíz es donde estás ahora, el proyecto activo es un modo que configuraste hace días. Cuando no coinciden, el desactualizado es la respuesta incorrecta.

Las configuraciones de un solo repositorio no se ven afectadas: pjm init --mcp-config-single sigue imprimiendo la configuración fijada, y una entrada existente de --root sigue funcionando exactamente como antes.

Integración MCP (Recomendada)

Para: Claude Desktop, Cursor, Antigravity, Codex — y cualquier herramienta con soporte MCP nativo. El servidor MCP obliga a la IA a leer la memoria y registrar cada acción automáticamente.

Desde 0.3.0 configuras esto una vez, no una vez por repositorio. El bloque siguiente no tiene --root: el servidor atiende a todos los proyectos que hayas registrado, y cada llamada resuelve el suyo. Pégalo, y cada repositorio que pjm init desde entonces será accesible: sin una segunda entrada, sin reiniciar.

"mcpServers": {
  "projectmem": {
    "command": "/opt/anaconda3/bin/python",
    "args": ["-m", "projectmem.mcp_server"]
  }
}

¿Actualizando con proyectos que ya tienes? El registro solo ha registrado proyectos en los que ejecutaste pjm init desde que existe (0.2.0), así que cualquier cosa más antigua falta — y el modo global enruta a través del registro. Un comando lo resuelve:

pjm doctor          # what's unregistered, what's stale, what's still pinned
pjm doctor --fix    # register what it found

Busca en los lugares donde el código realmente vive: ~/Developer, ~/code, ~/src, ~/projects y similares, además de cada unidad fija en Windows, donde los proyectos están en D:\ y E:\ tan a menudo como bajo tu carpeta de usuario. Para apuntarlo a un lugar específico:

pjm doctor --path ~/work --path /Volumes/ssd --fix
pjm project scan D:\ E:\ --depth 3     # the same walk, without the other checks

Nada se escanea hasta que lo ejecutas, y nada se escribe sin --fix. Después de una actualización, la CLI menciona pjm doctor una vez — una instalación con wheel no puede ejecutar código, así que el primer comando que escribes es el único lugar para decirlo.

Con un proyecto registrado, esa es toda la configuración: solo hay un lugar al que puede ir una llamada. Con varios, tu IA pasa project="<name>", o estableces un valor predeterminado con pjm project use <name>. pjm init imprime este bloque con tu propia ruta de Python ya completada.

¿Actualizando desde 0.2.x? Tu entrada existente de --root sigue funcionando exactamente como antes, y un servidor fijado ahora se niega a escribir fuera de su propio repositorio incluso si se le pide. Reemplázalo con el bloque anterior cuando quieras un solo servidor para todo.

El flujo de trabajo de 3 minutos (deja que tu IA haga la configuración)

1. Instala + inicializa. pip install projectmem, luego cd en tu proyecto y ejecuta pjm init — o simplemente pide a tu IA que lo ejecute.
2. Pide a tu IA que configure el servidor MCP de projectmem por ti — puede editar el archivo de configuración del cliente por sí misma. (Necesita permiso para hacerlo: usa el modo Auto / accept-edits, o aprueba la edición del archivo cuando se te pida. La configuración exacta por cliente está en las secciones siguientes si prefieres pegarla a mano).
3. Reinicia la herramienta de IA para que el servidor MCP se cargue, luego comienza tu sesión con este prompt:

Hi — I use projectmem as this project's memory. Before anything else,
call get_instructions(), then get_summary(), then get_project_map() to
load what we already know. As we work, log issues, attempts
(failed/worked), fixes, decisions, and notes with the projectmem tools,
and call precheck_file(path) before you edit a file. Ideas and plans go
in plan.md via get_plan() — never as events.

Estrictamente hablando, este prompt es opcional — con el servidor MCP instalado correctamente, la IA descubre la memoria por sí sola. Pero decirlo hace que la captura sea notablemente más consistente, así que lo recomendamos.

• Repite para cada proyecto: pjm init + el mismo prompt de inicio.
• ¿Volviendo después de cerrar la ventana? Abre con un recordatorio de una línea — "Recordatorio: usamos projectmem como memoria aquí." — y toda la configuración continúa donde la dejaste.

¿Prefieres conectarlo a mano? La configuración exacta y verificada para cada cliente sigue a continuación.

Claude Desktop

Lo más fácil: abre la configuración desde la interfaz:

• macOS: menú de Claude → Settings… → pestaña Developer → Servidores MCP locales → Editar configuración.
• Windows / Linux: se espera la misma ruta (Settings → Developer → Edit Config) — abre un issue si tu plataforma difiere y lo actualizaremos.

Si prefieres la ruta del archivo sin procesar: ~/Library/Application Support/Claude/claude_desktop_config.json en macOS, %APPDATA%\Claude\claude_desktop_config.json en Windows, ~/.config/Claude/claude_desktop_config.json en Linux (o $XDG_CONFIG_HOME/Claude/ si lo has movido). pjm init imprime la correcta para la máquina en la que lo ejecutas.

Pega este bloque:

"mcpServers": {
  "projectmem": {
    "command": "/opt/anaconda3/bin/python",
    "args": ["-m", "projectmem.mcp_server"]
  }
}

Dos cosas que debes saber sobre este bloque:

• Usa la ruta absoluta a python (por ejemplo, /opt/anaconda3/bin/python, o ejecuta which python para encontrar la tuya). Los subprocesos de Claude Desktop no heredan tu PATH de shell, así que un "python" simple a menudo falla.
• Ya no necesitas el campo cwd, y nunca pudiste confiar en él. La versión actual de Claude Desktop (con el sistema de espacio de trabajo Epitaxy / Cowork) ignora silenciosamente cwd — el servidor termina ejecutándose con cwd=/ y no puede encontrar .projectmem/. Por eso las versiones anteriores necesitaban --root. El registro lo reemplaza: el servidor encuentra proyectos por nombre, no por dónde está ejecutándose.

"mcpServers": {
  "projectmem": {
    "command": "/opt/anaconda3/bin/python",
    "args": [
      "-m", "projectmem.mcp_server",
      "--root", "/absolute/path/to/your/project"
    ]
  }
}

Luego cierra completamente Claude Desktop (Cmd+Q en Mac) y vuelve a abrirlo — los servidores MCP solo se inicializan en un arranque en frío.

Cursor

Dos formas de registrar el servidor MCP — elige la que se adapte a tu flujo de trabajo:

1. Global (recomendado): menú de Cursor → Settings… → barra lateral izquierda Herramientas y MCPs → Servidores MCP instalados → Añadir MCP personalizado. Pega el JSON a continuación.
2. Por proyecto: coloca el JSON en <project-root>/.cursor/mcp.json — solo activo cuando ese proyecto está abierto.

{
  "mcpServers": {
    "projectmem": {
      "command": "/opt/anaconda3/bin/python",
      "args": ["-m", "projectmem.mcp_server"]
    }
  }
}

Dos cosas que debes saber sobre este bloque (mismos problemas que Claude Desktop):

• Usa la ruta absoluta a python (ejecuta which python para encontrar la tuya). Los subprocesos de Cursor no heredan de manera confiable tu PATH de shell.
• No te molestes con el campo cwd. Cursor — como Claude Desktop — lo ignora silenciosamente: el servidor termina ejecutándose con cwd=~. Desde 0.3.0 eso ya no importa, porque los proyectos se encuentran por nombre en el registro en lugar de por dónde se ejecuta el servidor.

Registrado globalmente, una entrada cubre todos los proyectos. .cursor/mcp.json por proyecto sigue funcionando si prefieres que el servidor exista solo cuando ese repositorio está abierto — añade "--root", "/absolute/path/to/your/project" a args allí para fijarlo.

Luego cierra completamente Cursor (Cmd+Q en Mac) y vuelve a abrirlo. projectmem también auto-descubre .projectmem/ subiendo desde CWD (como git hace con .git/), y respeta PROJECTMEM_ROOT y un argumento CLI de --root <path>.

Antigravity

Antigravity (el IDE de IA de Google) habla MCP estándar.

Lo más fácil: abre la configuración desde la interfaz:

1. Abre la ventana del Agente (el panel de chat a la derecha).
2. Haz clic en el botón ⋯ Opciones adicionales en el encabezado del panel.
3. Elige Servidores MCP → Gestionar servidores MCP → Añadir nuevo (o Editar configuración).

El archivo sin procesar está en ~/.gemini/antigravity/mcp_config.json si prefieres editarlo directamente.

Pega este bloque:

{
  "mcpServers": {
    "projectmem": {
      "command": "python",
      "args": ["-m", "projectmem.mcp_server"]
    }
  }
}

Antigravity sí respeta el campo cwd, así que añadir "cwd": "/absolute/path/to/your/project" funciona — pero vincula el servidor a ese único repositorio. Déjalo fuera y la misma entrada atiende a todos los proyectos registrados.

Luego cierra completamente Antigravity (Cmd+Q en Mac) y vuelve a abrirlo — los servidores MCP solo se inicializan en un arranque en frío. Las 17 herramientas de projectmem se registran de manera idéntica a Claude Desktop / Cursor.

Codex

Codex almacena la configuración MCP como TOML (no JSON) en ~/.codex/config.toml. Hay un formulario de interfaz en Settings → MCP Servers → Add MCP Server, pero durante la verificación entre clientes, el botón Guardar del formulario no persistía de manera confiable — la ruta de edición de archivos es más rápida y confiable.

Lo más fácil: edita ~/.codex/config.toml directamente:

Añade este bloque (preserva cualquier configuración existente):

[mcp_servers.projectmem]
command = "/opt/anaconda3/bin/python"
args = ["-m", "projectmem.mcp_server"]
cwd = "/absolute/path/to/your/project"

Tres cosas que debes saber sobre este bloque:

• Usa la ruta absoluta a python (ejecuta which python para encontrar la tuya). Los subprocesos de Codex no heredan de manera confiable tu PATH de shell.
• Ya no necesitas --root o cwd. Las versiones anteriores pasaban --root como defensa en profundidad (el campo cwd parece funcionar en Codex, a diferencia de Claude Desktop y Cursor). Desde 0.3.0 el registro hace que ambos sean innecesarios — añade "--root", "/absolute/path/to/your/project" a args solo si quieres este servidor bloqueado a un solo repositorio.
• Establece tu esfuerzo de razonamiento en medium o superior. Con razonamiento bajo, Codex omite get_instructions del trío de inicio de sesión, lo que puede hacer que la IA se pierda las reglas del flujo de trabajo del Modo Configuración. Medio+ respeta el trío completo automáticamente.

Valida el TOML:

python -c "import tomllib; tomllib.load(open('/Users/<you>/.codex/config.toml','rb')); print('OK')"

Debería imprimir OK. Si no, el analizador te dice la línea problemática.

Luego cierra completamente Codex (Cmd+Q en Mac) y vuelve a abrirlo. La misma regla de arranque en frío que con cualquier otro cliente MCP. Los servidores MCP de Codex se generan de manera perezosa en la primera llamada de herramienta en una sesión de chat — si no ves el proceso en ps aux justo después de reabrir, envía cualquier mensaje a un chat de Codex y verifica de nuevo.

Nota sobre el esfuerzo de razonamiento: El selector de modo de Codex está en la parte inferior de la entrada de chat. Configúralo en medium (no low) para el comportamiento completo del trío de inicio de sesión. Una vez configurado, persiste por sesión.

Solicitudes de permiso en el primer uso

En el primer uso en cualquier cliente compatible con MCP (Claude Desktop, Cursor, Antigravity, Codex), tu IA pedirá permiso antes de cada llamada de herramienta de projectmem. Esto es un comportamiento de seguridad esperado — los clientes MCP requieren consentimiento explícito para cada nueva herramienta. Aprueba cada herramienta una vez y la solicitud no reaparecerá en esa sesión.

Otras herramientas MCP

Cualquier cliente compatible con MCP funciona — apunta tu herramienta a python -m projectmem.mcp_server y establece cwd a tu raíz de proyecto o confía en la auto-detección de subida de directorio padre.

Herramientas MCP expuestas

Las 17 herramientas que tu IA puede llamar. Cada herramienta de repositorio toma un argumento opcional de project — consulta Un servidor, muchos proyectos:

Lado de lectura (10 herramientas):

Lado de escritura (5 herramientas):

Referencia de CLI

Memoria principal

Capa de inteligencia

Proyectos (MCP global)

Visualización y utilidades

Usa --at "file.py:42" con cualquier comando de registro para adjuntar metadatos de ubicación precisos.

plan.md — intención, mantenida separada de la memoria

pjm init crea un .projectmem/plan.md: tus ideas y planes — lo que pretendes hacer, en Markdown plano (Ideas · Planes activos · Siguiente · Algún día · Enviado). Es el único archivo que deliberadamente no es el registro de eventos:

• events.jsonl → summary.md registra lo que sucedió (solo añade, nunca se reescribe).
• plan.md registra lo que pretendes — y tú (o la IA) lo editas directamente, como PROJECT_MAP.md.

Tu IA lo lee al inicio de la sesión mediante get_plan() y lo actualiza en el lugar: añadiendo ideas, marcando elementos, moviendo trabajo terminado a Enviado. Un plan nunca se registra como evento, por lo que la intención se mantiene limpia fuera del rastro de auditoría de tu memoria. pjm plan lo imprime; pjm plan "auto-batch the exporter" añade una idea. Se confirma (no ignorado por git) para que la intención se comparta con tu equipo.

Ejemplo: Advertencias Pre-Commit en Acción

$ git commit -m "switch auth to JWT"

projectmem: Pre-Commit Check
─────────────────────────────────────────────
  src/auth/middleware.py
    WARN  What already failed here (2 attempts):
           ✗ tried switching to JWT middleware (2d ago)
           ✗ patched session timeout to 60min (5d ago)
    WARN  HIGH CHURN: 5 changes in last 30 days
    WARN  1 possibly-stale memory cites this file
           decision [evt_9db5a3f8…] "auth uses session
           cookies, 30min timeout" — predates 7 commits
           Confirm it still holds, or retire it:
           pjm decision "..." --supersedes <id>
─────────────────────────────────────────────
3 warning(s). Review before committing.

~30 min re-debugging just saved.

¿Necesitas silencio para un sprint de refactorización? pjm precheck --snooze 2h — las advertencias se pausan, la pausa en sí se registra, y cada commit muestra una línea tenue para que el silencio nunca se confunda con una verificación limpia.

Privacidad y Seguridad

Por defecto, projectmem confirma los archivos destilados (summary.md, PROJECT_MAP.md, AI_INSTRUCTIONS.md, issues/) e ignora en git el registro bruto + archivos de ejecución (events.jsonl, watch.pid, watch.log). Esto significa que la IA de tu compañero hereda automáticamente el conocimiento de tu equipo — solo git clone y la IA ya sabe lo que tu equipo aprendió.

¿Quieres privacidad total? Añade una sola línea .projectmem/ a tu .gitignore. Nada sale de tu máquina.

Política de seguridad completa y modelo de amenazas: SECURITY.md · Guía de Privacidad y Seguridad

Principios de Diseño

• Local primero — Sin llamadas de red, sin nube, sin telemetría. Tus datos nunca salen de tu máquina.
• Alcance de proyecto — La memoria vive en el repositorio. Cuando el código se mueve, la memoria se mueve.
• Agnoóstico de herramientas de IA — Funciona nativamente vía MCP, o universalmente vía instrucciones Markdown. Cualquier herramienta de IA, cualquier flujo de trabajo.

Construido Con

projectmem se apoya en los hombros de estos excelentes proyectos de código abierto:

• Typer — el framework CLI que hace que pjm se sienta ergonómico
• Model Context Protocol — la especificación abierta de Anthropic que permite a los agentes de IA hablar con herramientas locales
• watchdog — monitoreo de eventos del sistema de archivos multiplataforma (el corazón de pjm watch)
• D3.js — las visualizaciones interactivas en pjm visualize

Investigación y Citación

projectmem se describe en un artículo de investigación legible por pares:

PROJECTMEM: A Local-First, Event-Sourced Memory and Judgment Layer for AI Coding Agents Ripon Chandra Malo, Tong Qiu — University of Utah arXiv:2606.12329 · cs.SE (cross-list cs.AI)

El artículo introduce el marco de Memoria como Gobernanza — memoria que no solo responde al agente sino que actúa sobre su siguiente acción — y reporta el diseño, la puerta de juicio determinista pre-commit, una comparación de capacidades contra 12 sistemas de memoria contemporáneos, y un estudio de dogfooding de dos meses con 207 eventos en 10 proyectos reales.

Si projectmem es útil en tu investigación o escritura, por favor cita:

@misc{malo2026projectmem,
  title         = {PROJECTMEM: A Local-First, Event-Sourced Memory and
                   Judgment Layer for AI Coding Agents},
  author        = {Malo, Ripon Chandra and Qiu, Tong},
  year          = {2026},
  eprint        = {2606.12329},
  archivePrefix = {arXiv},
  primaryClass  = {cs.SE},
  url           = {https://arxiv.org/abs/2606.12329}
}

Licencia

MIT — gratis para uso personal, comercial y empresarial para siempre.

Ayúdanos a Llegar a Más Desarrolladores

No necesitamos dinero. Te necesitamos a ti.

projectmem está construido por un desarrollador para la comunidad de código abierto. Cada estrella, cada compartido, y cada contribución ayuda al proyecto a sobrevivir y crecer.

• Da una estrella al repositorio — toma un clic, ayuda enormemente con el descubrimiento
• Comparte en X / LinkedIn — dile a otros desarrolladores que no tienen que seguir pagando a la IA para reaprender su código
• Abre un problema — error, solicitud de función, o solo comentarios
• Contribuye código — PRs bienvenidos, consulta la guía de contribución
• ¿Usas projectmem en el trabajo o en un producto comercial? Contacta a support@projectmem.dev para que sepamos quién está enviando con nosotros. Es gratis — solo nos encanta escucharlo.

Las estrellas y los compartidos importan más que el dinero — pero si realmente quieres: patrocina en GitHub →