Cuatro reglas para que la memoria del agente mantenga su honestidad
Almacenar más notas no solucionará el problema de memoria del agente de codificación. Cuatro reglas garantizan su fiabilidad: obsolescencia visible, redacción automática en caso de error, truncación evidente y cumplimiento de las restricciones establecidas.
Fuentes: Your Coding Agent Has a Memory Problem. Storing More Won’t Fix It.
Abre una segunda ventana de chat y tu agente de programación no sabe nada. No menos que antes, sino absolutamente nada. La decisión tomada hace cuarenta minutos sobre por qué se rechazó el enfoque basado en colas ha desaparecido. Asimismo, se ha eliminado la restricción de que el equipo de seguridad del cliente nunca aprobará una nueva base de datos, así como los tres caminos sin salida que ya exploraste para que nadie tenga que recorrerlos de nuevo. El contexto no sobrevive a un cambio de ventana.
De ahí la rutina: pega el contenido del chat anterior, escribe todo lo que recuerdes y explica de nuevo lo que no puedes recuperar. Eso lleva fácilmente de diez a quince minutos por cambio, y las solicitudes premium se desperdician en conclusiones que ya se han obtenido una vez.
Nada en las plataformas cierra esa brecha, ya que cada función de memoria está limitada a exactamente lo que se intenta dejar atrás. La solución de un desarrollador fue crear su propia capa de memoria: aproximadamente 2,600 líneas de código en Node, sin dependencias en tiempo de ejecución, que sirve a GitHub Copilot, Claude Code y Codex. Casi de inmediato se topó con el problema del que nadie advierte.
Almacenar más empeora las cosas
El verdadero fracaso de un sistema de memoria no es olvidar. Es recordar mal, y además con certeza.
Imagínese una nota que dice “la autenticación utiliza JWT”, escrita cuando eso era cierto y recuperada cuatro meses después de que la base de código pasara a utilizar sesiones del lado del servidor. Esa información no desaparece en la incertidumbre; se sigue utilizando, confiando en ella y basándose en ella, lo que termina generando un agente que comete errores de forma específica y segura, e incluso puede citar una fuente. Eso es claramente peor que un agente que diga “no sé cómo funciona la autenticación aquí”, porque ese agente pregunta, mientras que el otro que está seguro ya implementa la solución.
Por lo tanto, el almacenamiento no es donde reside la ingeniería inteligente, ya que se reduce a una carpeta y un esquema. La parte difícil es garantizar que el conocimiento guardado siga siendo preciso mientras el código subyacente cambia. El diseño se basó en cuatro garantías, cada una de las cuales requiere poco código y mucho autocontrol.
Quién escribe las notas
El autor es un modelo de lenguaje, y casi todas las decisiones de diseño se derivan de ello. No se puede confiar en sus entradas, aunque no sea por maldad de nadie: provienen de una conversación que podría haber incluido una clave API, una cadena de conexión o la dirección de correo electrónico de alguien. Su formato de salida no puede darse por sentado, y cada viaje de corrección consume una solicitud real.
El último punto aparece en un lugar inesperado: el validador informa de todos los problemas a la vez en lugar de detenerse en el primero.
export function validateNode(input) {
const e = [];
// ...every check pushes onto e instead of throwing...
if (e.length) throw new ValidationError(e);
return n;
}
Reaccionar rápidamente es el instinto, pero aquí está mal. Un modelo que corrige su propio resultado puede arreglar todo en un solo intento en lugar de encontrar errores uno por uno, lo que implica una solicitud adicional por cada uno. Es un cambio pequeño, pero permite diferenciar un intento de reintentar de cinco intentos.
Las notas existen en cuatro tipos, lo cual es importante a continuación: system, decision, convention y constraint.
Regla 1: hacer visible el grado de obsolescencia cuando se utilice la nota
No se puede evitar el problema entre JWT y sesiones. Una nota puede ser precisa el lunes y incorrecta para marzo, independientemente del diseño. Lo que sí se puede hacer es mostrar la antigüedad de la nota en el instante en que alguien está a punto de confiar en ella, ya que ese es el único momento en que alguien puede actuar.
Cada nota registra el HEAD del repositorio en el que fue capturada:
id: auth-service
type: system
title: Auth uses server sessions
scope: repo
confidence: observed
captured_sha: a1b2c3d # repo HEAD at capture
repos: [orders-api]
edges:
- rel: depends-on
dst: postgres-primary
Al recuperarla, eso se convierte en un recuento de commits:
captured 47 commits ago — verify before trusting
No hay ningún modelo involucrado, ni tarea programada ni escáner en segundo plano que evalúe la frescura. Un único git rev-list --count ..HEAD basta para ello, y es determinista además de lo suficientemente económico como para ejecutarse directamente.
Tres detalles menores resultaron ser más importantes que la idea principal.
Una historia reescrita es una respuesta diferente. Cuando ya no se puede acceder al commit, debido a una rebase o a una operación de eliminación, indicar cero commits sería una falsedad que daría una sensación de seguridad falsa. En su lugar, la herramienta indica “historia reescrita, verifique”. “Desconocido” y “fresco” son respuestas distintas, y deben mantenerse separadas.
Las notas solo se anotan en el repositorio que ellas mismas indican. El recuento de commits medido con respecto a un historial no relacionado es ruido disfrazado de señal. Una nota limitada a orders-api y recuperada mientras se trabaja en billing-api se deja sin cambios, sin que se indique que ha sido reescrita.
if (Array.isArray(node.repos) && node.repos.length &&
!node.repos.includes(here)) return null;
Hay un umbral. Por debajo de diez commits, la antigüedad no se menciona en absoluto, ya que una advertencia que se activa constantemente es solo decorativa y no constituye una verdadera advertencia. El umbral es configurable. Un segundo umbral, más alto, en 100 commits activa la orden doctor que enumera las notas que merecen una revisión detallada, de modo que puedas buscarlas tú mismo en lugar de que te indiquen una nota a la vez.
Regla 2: los fallos de redacción se cierran
La información del establecimiento se muestra en texto plano en un escritorio corporativo, y el modelo escribió su contenido a partir de conversaciones que podrían contener cualquier cosa. Por lo tanto, nada se guarda en el disco sin antes pasar por un escaneo. Catorce familias de patrones detectan elementos como claves de AWS, tokens de GitHub y Slack, claves privadas, JWTs, tokens de portador, cadenas de conexión a bases de datos, cookies de sesión, IPs de rango privado y nombres de hosts internos, además de direcciones de correo electrónico; cada uno de estos elementos se reemplaza por <redacted:kind> antes de ser guardado.
“Fail-closed” realiza una función específica, visible en las primeras líneas de la función:
export function redact(text, opts = {}) {
if (typeof text !== 'string') {
throw new TypeError('redact() requires a string; refusing to write unscanned content');
}
Si se le proporciona algo que no puede escanear, no omite el escaneo y continúa; en su lugar, aborta la operación de escritura. Una pasada de redacción debe fallar de tal manera que “no se escriba nada”, y nunca de forma que “esto se haya pasado por alto”. Tampoco existe una bandera de omisión, ya que esa bandera es algo que eventualmente se utilizaría en algún viernes por la tarde.
Hay dos opciones dentro de este sistema que merecen ser defendidas.
Las cadenas de conexión se mantienen completas. Un URI como postgres://user:hunter2@db.internal:5432/orders incluye sus credenciales directamente, por lo que se reemplaza todo el URI y no solo la contraseña. Un URI parcialmente redactado sigue proporcionando al lector el host, el puerto, el nombre de la base de datos y el nombre de usuario.
Los secretos en el formulario de tarea deben demostrar su validez. Una regla ingenua para password: <algo> también incluiría una oración como “la política de rotación de contraseñas es de 90 días”, por lo que la regla exige comillas o una secuencia larga sin comillas:
{
kind: 'assigned-secret',
re: /\b(?:api[_-]?key|secret|password|token|client[_-]?secret|
access[_-]?key)\b\s*[:=]\s*(?:"[^"\n]{6,}"|'[^'\n]{6,}'|[^\s"'`,;)]{12,})/gi,
}
La edición que distorsiona el texto prosaico común deja de funcionar y, entonces, ya no protege nada. Todo el módulo tiene exactamente una excepción: tu propia identidad de git sobrevive, ya que ya está registrada en cada commit que has enviado, y ocultarla solo haría que las notas fueran más difíciles de leer.
Regla 3: la truncación nunca es silenciosa
Una solicitud de nivel 2 en un nodo bien conectado puede devolver cincuenta notas y sobrepasar la ventana de contexto que protege el diseño. Por eso existe un límite de bytes, 8 KB por defecto, y se realiza un recorte una vez que se excede dicho límite. Nada de esto es sorprendente. Lo importante es lo que sucede después del recorte:
3 nodes omitted for budget: legacy-batch-job, vendor-sftp-quirk,
old-retry-policy
Every omitted id gets printed, with no exceptions. This rule carries the most conviction, because silent truncation is the failure that looks like success. Given eight of eleven notes and no sign that three are missing, an agent assumes it sees everything and replies as confidently as that implies. The missing three are probably the ones it needed: they were dropped as peripheral to the query, and a surprising constraint often sits at the edge.
Pruning goes deepest-first, then least-connected:
.sort((a, b) => b.depth - a.depth || a.degree - b.degree || ...)
Depth means distance from what was actually asked, and a low degree suggests a node nobody needed as a hub. Breaking final ties by id gives identical bytes for the same query every time, so the reindex determinism test checks something real.
Rule 4: constraints are never dropped
Not at any cap, in either tier, with no exceptions.
const removable = nodes.filter((n) => n.depth > 0 && n.type !== 'constraint');
Hay dos elementos que escapan de la reducción: la nota principal que solicitó y cada constraint. La lógica se basa en el costo, no en el gusto. Una restricción puede indicar que el cliente no aprobará una nueva base de datos, que un servicio no puede acceder a Internet público, o que el equipo de la plataforma ya rechazó Kafka. Es precisamente esta información la que impide a un agente enviar una docena de solicitudes hacia un enfoque condenado al fracaso desde el principio. Reducir una para ahorrar cuatrocientos bytes significa cambiar un costo bajo por uno elevado: los bytes son económicos, pero un desarrollo sin salida no lo es.
Esto genera un caso sobre el cual el código debe ser claro desde el inicio. Si la nota principal más las restricciones ya superan el presupuesto, este debe ceder:
Note: 9,412 bytes returned, over the 8,192 budget, because constraints
are never dropped.
Se ha informado del problema pero no se ha corregido, ya que la solución implicaría eliminar lo que es importante conservar.
La tienda está en formato Markdown y el índice es desechable
Una elección estructural permite cumplir con las cuatro reglas: las notas son archivos normales de Markdown con información preliminar en YAML, y index.db es un caché que se puede eliminar cuando se desee.
~/.agents/memory/
notes/<type>/<id>.md the source of truth
notes/archive/ superseded and decayed notes; never deleted
index.db disposable SQLite cache
ROUTING.md generated map of everything known
Un único comando index regenera la base de datos a partir de las notas, byte a byte. La base de datos existe porque recorrer un grafo en SQL es rápido, mientras que recorrer un directorio de archivos es lento. El motor es un CTE recursivo con un límite de profundidad y UNION en lugar de UNION ALL, por lo que un bucle de contradicts no puede recursirse hasta que SQLite se cierre. No existe una capa de grafo separada sobre SQLite; el CTE se encarga de esa tarea.
Nada de valor se mantiene únicamente en el índice. Si SQLite está dañado, se pierde el caché. Al eliminar la herramienta, queda una carpeta con archivos en formato markdown legible, útil cuando no se ha instalado nada. El conocimiento debería perdurar más allá de los índices que lo contengan, y un almacén binario propietario falla ya en el primer día.
Esto es también lo que permite su instalación en entornos restringidos, que era el objetivo original. Node incluye node:sqlite en su núcleo desde la versión 22.5, por lo que el índice no requiere ningún paquete, ningún servicio ni conexión a red. En un escritorio gestionado, proponer un script de Node y proponer una nueva base de datos conllevan conversaciones y resultados muy diferentes.
Qué se dejó intencionalmente fuera
Nada se captura automáticamente: tú lo activas, o lo hace la habilidad encargada de la transferencia. Esa es una limitación deliberada. Un proceso en segundo plano que supervise tu sesión y decida qué conservar es la función que todos solicitan, pero también la que con mayor probabilidad inundará la tienda de información poco fiable. Todas las reglas de honestidad mencionadas anteriormente se vuelven menos estrictas a medida que se acumulan notas de baja calidad. Diez notas buenas en una semana valen más que cuatrocientas, que es lo que se obtiene cuando un modelo actúa por sí solo.
La compartición de equipos, la sincronización entre múltiples máquinas y un servidor MCP también se han pospuesto. Un servidor MCP leería del mismo almacén, por lo que se trata de una adición y no de una reescritura.
Una afirmación sigue sin estar comprobada. La prueba relevante es una lectura en condiciones reales: un nuevo chat en un repositorio sin modificar durante un mes, que responda correctamente únicamente con la información del resumen de enrutamiento. Eso requiere tiempo real y no puede simularse en un conjunto de pruebas. Setenta y una pruebas pasan en Linux, macOS y Windows con Node 22 y 24, pero ninguna muestra lo que realmente se quiere saber.
La parte que vale la pena adoptar
Cualquiera que integre memoria en un flujo de trabajo de agente, ya sea propio o de uno que distribuya, puede aplicar estas cuatro reglas más allá de este proyecto:
- Indique la antigüedad del conocimiento donde se utilice, no en un panel de control que nadie abre.
- Deje que el mecanismo de validación falle al no escribir nada, y no agregue una bandera de desvío.
- Imprima lo que haya omitido, ya que una truncación silenciosa se percibe como cobertura total.
- Resuelva lo que nunca se puede dejar de lado antes de que el presupuesto se vuelva ajustado, porque las decisiones tomadas bajo presión son peores.
Ninguno de estos pasos es difícil de implementar. Los cuatro son fáciles de pasar por alto y quedan invisibles cuando funcionan, y precisamente por eso vale la pena anotarlos.