Escribir memorias

Una memoria es una nota breve en Markdown que tu equipo escribe para que el asistente la lea más adelante. Las memorias viven en una ruta del espacio de trabajo y solo aparecen cuando el asistente trabaja dentro de esa ruta. Son el tipo de contenido más común en Pathrule y el más fácil para empezar.

Esta página explica cuándo escribir una memoria, cómo estructurarla y cómo funcionan el alcance y las versiones.

Cuándo escribir una memoria

Recurre a una memoria cuando tengas un conocimiento que no se deduce del código y que probablemente vuelva a surgir.

• Decisiones. "En este repositorio usamos Postgres sobre Supabase para todo. No agregues un ORM. Usa directamente el cliente supabase-js."
• Trampas habituales. "Si cambias el enum orders.status, debes ejecutar la migración de datos antes que la migración de esquema. El orden es el inverso al del resto del esquema."
• Postmortems. "El 2026-04-12 publicamos un handler de webhooks que cobró dos veces a los clientes porque no verificamos la clave de idempotencia de Stripe. Ahora pásala siempre."
• Convenciones. "Las pruebas viven junto al archivo que prueban, no en un directorio paralelo __tests__."
• Conocimiento tribal. "Solo una persona recuerda por qué existe este flag. Sigue siendo necesario por una peculiaridad del runtime en upstream."

No uses memorias para lo que el código ya dice con claridad, para lo que cambia cada semana ni para lo que es puramente preferencia personal.

Estructura

Cada memoria tiene un título y un cuerpo en Markdown. Mantén ambos breves.

• Título: corto, declarativo, que quepa en una barra lateral. "Solo Postgres. Sin ORM." es mejor que "Notas sobre patrones de acceso a la base de datos".
• Cuerpo: la menor cantidad de Markdown que transmita la idea. Las viñetas suelen ser más claras que los párrafos. Incluye un ejemplo si ayuda.

No hay una plantilla obligatoria, pero un buen punto de partida es:

The constraint or fact in one sentence.

Why:
- The reason this matters or the incident that prompted it.

How to apply:
- The concrete thing the assistant should do when the topic comes up.

Alcance por ruta

La ruta es la mitad de la memoria. Decide dónde aparece.

• Una memoria en /apps/api/payments aparece en cualquier trabajo dentro de apps/api/payments.
• Una memoria en /apps/api aparece en todo el directorio api.
• Una memoria en / aparece en todo el espacio de trabajo.

Elige la ruta más específica que siga cubriendo los casos que te interesan. Una memoria sobre pagos a nivel de espacio de trabajo es solo ruido; es mucho mejor una memoria sobre pagos en la carpeta de pagos.

Versiones y ediciones simultáneas

Cada guardado se compara con la versión desde la que empezaste. Si alguien más guardó entretanto, tu guardado se rechaza en lugar de sobrescribir el suyo. Así tu equipo evita que dos personas, o una persona y un agente, se sobrescriban sin darse cuenta.

• En Pathrule para VS Code, una memoria es una pestaña de Markdown. Un guardado que sobrescribiría un cambio más reciente de un compañero ofrece Reload, Copy My Version & Reload (primero copia tu texto al portapapeles) o Keep Mine (Overwrite).
• Por MCP, el asistente puede enviar la versión que leyó por última vez. Si no coincide, recibe un conflicto con la versión actual, vuelve a leer y fusiona los cambios en lugar de sobrescribirlos.

Borrar también es reversible. En VS Code, un borrado ofrece Undo de inmediato, y en un espacio de trabajo de Pathrule Cloud una memoria eliminada permanece en el archivo del espacio de trabajo hasta que se elimina de forma permanente; ahí un propietario o administrador puede restaurarla desde la configuración de la consola web (Workspace, Archive) o eliminarla definitivamente. En la práctica los conflictos son poco frecuentes porque las memorias suelen ser breves y concretas, pero la red de seguridad siempre está activa.

Quién las escribe

• Las personas, desde Pathrule para VS Code (New Memory… o Save Selection as Memory) o con la CLI.
• El asistente, mediante la herramienta MCP pathrule_write_memory cuando le pides que guarde algo. Durante la configuración propone memorias, reglas y skills para el proyecto y solo escribe las que apruebas.

Desde la terminal, una memoria es un solo comando. Sin --body, la CLI abre tu editor para el cuerpo; también puedes pasar --body o enviar el texto por pipe. pathrule memory list y pathrule memory read "Exact title" --print te permiten leer las memorias.

pathrule memory add --path /apps/api/payments --title "Always pass the Stripe idempotency key"

Ambas fuentes terminan en el mismo lugar. El asistente lee lo que escribió una persona y una persona lee lo que escribió el asistente. Cada registro guarda quién lo creó, quién lo editó por última vez y su origen, datos que muestra la acción Info en VS Code, así que es fácil identificar las memorias escritas por la IA.

Cómo la calidad de las memorias sigue siendo revisable

Pathrule mantiene cada memoria acotada e inspeccionable mediante varios controles independientes:

• La documentación general se ofrece durante la configuración en lugar de importarse automáticamente. Los archivos de instrucciones activos, su cadena de importación, las reglas de las herramientas y los registros de decisiones aportan evidencia más sólida de que son conocimiento vigente.
• Se le pide al agente que proponga el conocimiento duradero antes de guardarlo. Todo lo que guarde queda atribuido, versionado y visible en el espacio de trabajo como cualquier otro elemento, así que puedes abrirlo, editarlo o eliminarlo.
• El alcance por ruta limita dónde puede aparecer una entrada, y una entrada fuera de la ruta actual igualmente tiene que superar el umbral de relevancia.
• El uso medido puede reordenar las entradas que califican, pero no puede hacer que una memoria no relacionada supere ese umbral.
• Un agente que detecta que una memoria ya no coincide con el código puede marcarla como tarea de actualización, que luego un asistente retoma y corrige bajo tu control. Consulta Sugerencias y autoauditoría. Las ediciones tienen versiones y el borrado es reversible.
• Una memoria nueva cuyo título coincide con otra existente en la misma ruta se rechaza por defecto en lugar de guardarse como segunda copia, para que la misma decisión no se entregue dos veces ni las copias terminen divergiendo. Puedes forzarlo de forma deliberada (--allow-duplicate en la CLI) después de revisar la entrada existente.

El modelo de trabajo resultante es un conjunto pequeño de decisiones y trampas habituales, acotadas y revisables, no un gran archivo copiado al espacio de trabajo. Consulta Cómo demuestra Pathrule sus afirmaciones más exigentes para ver el contrato técnico completo.

Leer frente a citar

Las memorias más relevantes llegan con el cuerpo completo, para que el asistente actúe directamente sobre ellas. Las candidatas menos seguras llegan como títulos con ids; el asistente lee una completa con pathrule_read_memory antes de basarse en ella. Así el material incierto queda fuera de la carga predeterminada sin convertir las coincidencias fuertes en viajes de ida y vuelta adicionales.

En VS Code, Browse Knowledge Here… muestra lo que recibe una sesión de IA en una ruta, incluido lo que hereda de las rutas superiores.

Antipatrones

• Una sola memoria enorme con "todas mis notas". Divídela por tema y alcance. Una memoria pequeña y vinculada a una ruta siempre es mejor que una larga y global.
• Memorias que repiten lo que ya dice el código. El asistente puede leer el código. Reserva las memorias para el porqué y para las trampas.
• Memorias desactualizadas. Actualízalas o elimínalas cuando cambie la decisión de fondo. Un asistente puede marcar una memoria desactualizada como tarea de actualización, pero el ojo humano es más rápido.

Creación en modo local y en Cloud

Los ejemplos de add en la terminal de esta página son para un espacio de trabajo de Cloud. En modo local, crea y edita entradas en Local Console, VS Code o a través del MCP local; los comandos de conocimiento de la CLI permiten listarlas, leerlas y buscarlas.

Qué leer a continuación

• Escribir reglas para restricciones con prioridad.
• Escribir skills para procedimientos reutilizables.
• Conceptos clave para conocer el árbol del espacio de trabajo al que se asocian.