DEV Community

Cover image for Construye un agente de desarrollo .NET, Parte 3: haz que te recuerde
Juan Gómez
Juan Gómez

Posted on

Construye un agente de desarrollo .NET, Parte 3: haz que te recuerde

Construye un agente de desarrollo .NET, Parte 3: haz que te recuerde

El lunes por la mañana le pregunté a mi agente de desarrollo qué había estado haciendo el viernes. Ejecutó git status, puso en pantalla el nombre de mi propia rama y me dijo: "I can't see Friday's history, only the current state." No podía ver el historial del viernes, solo el estado actual.

Es una respuesta honesta, la de un compañero que lo olvida todo cada noche. Y no podía decir mucho más, porque todo lo demás que el agente sabía de mi repositorio se lo había escrito yo en el system prompt: tres proyectos, cuál importa, qué advertencia es ruido. Ese párrafo era memoria escrita a mano, en el único lugar que el agente no puede actualizar.

Un robot frente a un globo de diálogo que solo tiene un signo de interrogación, con una terminal y el ícono de una rama detrás, y una nota escrita a mano clavada a su lado, fuera de su alcance, con un candado.

Este post cambia las dos cosas por una memoria que escribe el propio agente con la herramienta de memoria de Claude, y mide lo que una demo no muestra: qué decide guardar, cuánto cuesta cargarlo cada mañana y qué pasa cuando un recuerdo deja de ser cierto. Todo corre sobre Claude Haiku 5.5, con el mismo repositorio y el mismo agente de voz de la Parte 2.

Dónde dejó la Parte 2 al agente

Construye un agente de desarrollo .NET, Parte 2: dale voz le dio voz al agente de la Parte 1: se pulsa una tecla para hablar, un Whisper local transcribe, una voz local de Piper lee las respuestas y una herramienta show_on_screen muestra en pantalla lo que es demasiado largo para escucharlo. Por debajo hay un ciclo de tool_use escrito a mano, con cuatro herramientas: git_status, dotnet_build, dotnet_test y show_on_screen.

Dentro de una sesión ya recuerda. Cada turno se guarda en una List<MessageParam> y se reenvía con la petición siguiente, así que no olvida nada hasta que el proceso termina, y entonces lo olvida todo. La Parte 3 cambia tres cosas:

  • El system prompt pierde el párrafo sobre mi repositorio. El agente aprende esos datos y los guarda en un directorio de memoria, uno por repositorio.
  • Una quinta herramienta, read_file. La sesión real de la Parte 2 terminó en "I can't read the code from here", y prometió esa herramienta para esta parte.
  • La corrección de un bug en código que el repositorio compañero agregó después de la Parte 2. Apareció al medir este post y, de paso, produjo el mejor recuerdo equivocado de la semana.

La prueba: un viernes y un lunes

La memoria no es un problema de voz, así que todas las mediciones usan texto escrito en lugar de grabaciones: las mismas palabras en cada corrida, sin errores de transcripción de por medio. El repositorio es el de la Parte 2, con el mismo renombrado a medias: ChangedFile.Patch pasó a llamarse Diff, quedó pendiente un uso en ReviewOrchestrator y el build falla con un CS1061, el error del compilador cuando un miembro no existe.

El "viernes", el agente recibe seis turnos:

  1. "Why is the build red?"
  2. "The core project is the one I care about. The CLI is just a wrapper."
  3. "And CS1591 is noise, ignore it. Nullable warnings are real."
  4. "What did I change?"
  5. "I'm renaming Patch to Diff in ChangedFile. I'll finish ReviewOrchestrator on Monday."
  6. "Run the tests."

Es decir: por qué está rojo el build, que el proyecto Core es el que importa, que CS1591 es ruido pero las advertencias de nulabilidad no, qué cambié, que ReviewOrchestrator lo termino el lunes, y que corra los tests. El "lunes", en un proceso nuevo, tres preguntas:

  1. "What was I doing on Friday?" (¿qué estaba haciendo el viernes?)
  2. "Build the project I care about." (compila el proyecto que me importa)
  3. "What's left to finish the rename?" (¿qué falta para terminar el renombrado?)

Antes de correr nada dejé escrito qué cuenta como acierto. La primera respuesta tiene que decir qué quedó pendiente, el uso en ReviewOrchestrator, en voz alta o en pantalla. La segunda tiene que compilar el proyecto Core sin preguntar cuál. La tercera tiene que nombrar ese uso, respaldado por una herramienta que el agente ejecutó esa mañana y no por una nota. Cada configuración corrió tres veces con Haiku 5.5 y esfuerzo low, igual que en la Parte 2, y cuatro de ellas corrieron una cuarta vez con la caché fría, para medir la latencia más abajo; en la tabla, esas cuatro cuentan cuatro lunes. Todos los lunes de una misma configuración parten del mismo viernes, así que la tabla compara los lunes, no lo que el viernes decidió guardar; esa variación aparece en las secciones siguientes.

Cinco formas de recordar, medidas

Las respuestas habituales a "¿cómo recuerda un agente?" tienen cuatro formas, y la última aparece aquí en dos versiones:

  • Guardar el historial. Se guarda la conversación entera del viernes y se reenvía el lunes.
  • Guardar una ventana. Solo los últimos turnos; aquí, los dos últimos del viernes.
  • Resumir. Al cerrar el viernes, una llamada extra escribe notas para la próxima vez, y el lunes arranca con ellas.
  • Guardar hechos. Durante la sesión, el agente decide qué guardar con la herramienta de memoria de Claude, y la sesión siguiente lo lee: bajo demanda, o cargado de antemano en el prompt.

Y, como punto de partida, el mismo agente sin ninguna memoria. Así fue el lunes con cada una, según las capturas de las corridas:

El lunes arranca con Primera petición Dice qué quedó pendiente Compila Core sin preguntar Llamadas a la API, tres preguntas
Sin memoria 1.178 tokens 0 de 4 0 de 4 7–9
Todo el historial del viernes 3.362 tokens 4 de 4 4 de 4 5–7
Los dos últimos turnos del viernes 1.408 tokens 0 de 3 1 de 3 5–7
Un resumen del viernes 1.407 tokens 1 de 3 3 de 3 8
Memoria, leída bajo demanda 2.932 tokens 4 de 4 4 de 4 9–12
Memoria, precargada 3.210 tokens 4 de 4 4 de 4 8–11

Ninguna mañana costó más de un cuarto de centavo con Haiku, así que no es el precio lo que las diferencia, sino lo que hacen.

Cinco carriles del calendario al agente: la conversación entera, los turnos viejos cortados con tijeras, los turnos comprimidos en una sola nota con un embudo, una nota que el agente guarda en un cajón y otra que ya tiene delante antes de empezar.

Sin memoria es el agente de este post con la memoria apagada: sin el párrafo sobre mi repositorio en el prompt y con read_file. Pasó lo esperable: cuando le pedí compilar "el proyecto que me importa", en una de cuatro corridas preguntó cuál y en las otras tres compiló la solución entera.

El historial completo dio las mejores respuestas, y es una trampa. (La corrida en frío empezó diciendo "I don't have Friday's conversation", es decir, que no tenía la conversación del viernes, y luego en pantalla nombró lo pendiente sacándolo de esa misma conversación.) Seis turnos del viernes pesan 2.184 tokens y de ahí no sale nada nunca. El viernes siguiente el agente carga dos viernes, al mes carga un mes entero, incluida cada salida de build que leyó, que el modelo recibe como cosas que pasaron en esta misma conversación. Tampoco se puede recortar por el camino obvio; de eso trata la sección siguiente.

La ventana perdió dos veces. Conservó los últimos turnos del viernes, "lo termino el lunes" y "corre los tests", y aun así nunca dijo qué quedó pendiente: dos corridas respondieron "I can't see Friday". La fecha estaba en el primer mensaje del viernes, que la ventana descartó, así que nada le indicaba al modelo que esos turnos eran del viernes. Y lo que el lunes necesitaba, qué proyecto compilar y qué advertencia ignorar, estaba en los turnos dos y tres: en dos de las tres corridas me preguntó a qué proyecto me refería. Una ventana descarta lo más antiguo, no lo menos importante.

El resumen tenía la respuesta y casi nunca la usó. Las notas decían, con las palabras del propio modelo el viernes, que yo iba a "finish the ReviewOrchestrator call site on Monday". Dos de tres corridas ejecutaron git_status y respondieron solo con eso. La tercera acertó, después de empezar con "I can't see Friday's activity from here" con esas notas en su system prompt. Por qué las notas perdieron contra la herramienta y la memoria precargada de más abajo no, no lo puedo separar: la memoria venía con sus propias reglas y con la instrucción de la herramienta de memoria, y las notas no traían ninguna de las dos.

Los hechos guardados acertaron las dos preguntas en todas las corridas, en sus dos versiones. Lo que separa a una de otra viene más abajo. Antes, la ventana.

La ventana deslizante ahora es un 400

Haiku 5.5 puede pensar antes de responder, y cada bloque de razonamiento (thinking) vuelve con una firma, un sello que la API comprueba cuando le reenvías el bloque. En los modelos actuales de Claude ese sello cubre la conversación que produjo el bloque: todo lo que venía antes, lo que la API llama su prefijo. Si cortas los turnos más viejos del inicio de un historial y lo reenvías, cada bloque de razonamiento que quede adentro aparece a continuación de una conversación que nunca existió.

Mi primera ventana conservaba esos bloques, y en mi cuenta la petición pasó. La verificación solo se aplica por defecto a las cuentas creadas desde el 31 de agosto de 2026; en las anteriores, solo cuando la petición la pide. Así que repetí la misma petición pidiéndola, con el encabezado beta thinking-binding-controls-2026-08-01 y prefix_mismatch_behavior en "error". La respuesta fue un HTTP 400, invalid_request_error, con este mensaje:

messages.3.content.2: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block". Content that preceded this block when it was created is missing from this request, starting at `messages.0`.
Enter fullscreen mode Exit fullscreen mode

Eso es lo que recibe por defecto una cuenta más nueva. La ventana de la tabla quita los bloques de razonamiento de los turnos que conserva, y eso la API lo acepta. Las otras salidas son pedirle a la API que descarte los bloques que ya no valen (drop_block, que el propio error sugiere), resumir y empezar una conversación nueva que no reenvíe nada, o dejar que el servidor limpie los turnos viejos con edición de contexto o compactación. Debajo de todas hay una regla: un historial que lleva bloques de razonamiento solo puede crecer por el final. Por esa misma regla la fecha salió del system prompt del agente y pasó al primer mensaje de cada sesión. Un system prompt que dice "lunes" no es el prefijo de uno que decía "viernes".

Qué decidió recordar

Este es el archivo de memoria que escribió el agente el viernes del que partieron todos los lunes con memoria de la tabla, tal como lo guardó:

Project memory (ClaudeReviewBot), updated 2026-11-06

- Developer cares most about src/ClaudeReviewBot.Core. The CLI project is just a wrapper; lower priority.
- Branch rename-patch-to-diff: renaming ChangedFile.Patch to Diff (uncommitted, 4 files).
- Open build error: src/ClaudeReviewBot.Core/Review/ReviewOrchestrator.cs line 111 still uses file.Patch.
  Developer will finish this himself on Monday (2026-11-09). Don't fix it unless asked.
- Developer says CS1591 is noise and nullable warnings are real; last Core build showed 0 warnings.
Enter fullscreen mode Exit fullscreen mode

Casi todo está bien: qué proyecto importa, la convención sobre las advertencias y el plan del lunes con la ruta completa. Una parte no. El error del build en la línea 111, los cuatro archivos sin confirmar y "last Core build showed 0 warnings" son estado: algo que las herramientas ya saben y que el lunes está desactualizado.

El prompt le decía que no lo hiciera. La primera versión de mis reglas pedía "never save what a tool can tell you: build or test results, changed files, error counts", y las dos corridas del viernes guardaron el error del build. La segunda versión lo nombraba sin rodeos, "whether the build passes, errors and their line numbers", y las dos corridas lo volvieron a guardar. Cuatro memorias de cuatro.

Ese estado guardado sería inofensivo si solo se leyera como historia, pero no fue así. Con la memoria de la primera versión, las tres corridas del lunes que la leían bajo demanda pusieron en pantalla, debajo de la respuesta hablada, alguna variante de "The build is red because ReviewOrchestrator still uses the old name" sin compilar. Era cierto porque nadie había tocado el repositorio el fin de semana. Si alguien lo hubiera arreglado, habría sido una línea falsa escrita con total seguridad.

Así que dejé de intentar que el prompt mantuviera el estado fuera de la memoria, y le pedí al agente que verifique cada recuerdo al leerlo. Esa regla está en todas las configuraciones con memoria de la tabla, y no es una garantía: el lunes el agente abrió ReviewOrchestrator.cs para comprobar la nota antes de repetirla en 2 de las 4 corridas precargadas y en 1 de las 4 bajo demanda. Las demás repitieron directo de la memoria la nota sobre la línea 111. Dónde se gana su lugar se ve dos secciones más abajo.

El almacén de memoria

La herramienta de memoria de Claude (memory_20250818) se ejecuta de tu lado. El modelo envía comandos (view, create, str_replace, insert, delete, rename) sobre rutas dentro de un directorio virtual /memories, y tu código los lleva a cabo donde quieras. Agregarla al agente es una entrada en la lista de herramientas, new MemoryTool20250818() en el SDK de C#, sin esquema que escribir.

Todo lo demás es el handler. Cada ruta y cada línea de texto que recibe vienen del modelo, así que merecen el mismo trato que la entrada de un usuario. Este es el comienzo de MemoryStore.cs:

using System.Globalization;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using System.Text.RegularExpressions;

/// <summary>
/// El almacenamiento detrás de la herramienta de memoria de Claude (memory_20250818). El modelo pide
/// operaciones de archivo sobre un directorio virtual /memories; esta clase las ejecuta en una carpeta real,
/// una por repositorio, fuera del repositorio para que una memoria nunca termine en un commit. Cada ruta
/// y cada línea de texto que envía el modelo es entrada no confiable.
/// </summary>
sealed partial class MemoryStore
{
    public const string Root = "/memories";

    // La memoria se carga en la primera petición de cada sesión, así que su tamaño se paga cada
    // mañana. Estos topes la dejan en unos 1.500 tokens; al pasarlos, se le pide al modelo que
    // combine o borre entradas en lugar de seguir agregando.
    const int MaxFileChars = 4_000;
    const int MaxTotalChars = 6_000;

    static readonly StringComparison PathComparison = OperatingSystem.IsWindows() || OperatingSystem.IsMacOS()
        ? StringComparison.OrdinalIgnoreCase
        : StringComparison.Ordinal;

    readonly string directory;   // ruta completa, terminada en separador

    public MemoryStore(string directory)
    {
        Directory.CreateDirectory(directory);
        this.directory = DevTools.WithSeparator(Path.GetFullPath(directory));

        // Un fallo entre escribir el archivo temporal y moverlo deja ese temporal atrás.
        // Está oculto, así que nada más lo contaría ni lo borraría nunca.
        foreach (string orphan in Directory.EnumerateFiles(this.directory, ".tmp-*"))
        {
            try
            {
                File.Delete(orphan);
            }
            catch (IOException)
            {
                // No es huérfano: otra sesión todavía lo está escribiendo, y ella misma lo moverá.
            }
        }
    }

    /// <summary>Una carpeta por repositorio, en los datos locales de la aplicación del usuario.</summary>
    public static MemoryStore ForRepository(string repo)
    {
        string full = Path.TrimEndingDirectorySeparator(Path.GetFullPath(repo));
        string key = PathComparison == StringComparison.OrdinalIgnoreCase ? full.ToLowerInvariant() : full;
        string hash = Convert.ToHexStringLower(SHA256.HashData(Encoding.UTF8.GetBytes(key)))[..8];
        string name = Path.GetFileName(full) is { Length: > 0 } folder ? folder : "repo";
        return new(Path.Combine(
            Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
            "VoiceDevAgent", "memories", $"{name}-{hash}"));
    }

    /// <summary>Ejecuta un comando de memoria. Los fallos vuelven al modelo como texto, nunca como excepciones.</summary>
    public (string Content, bool IsError) Run(IReadOnlyDictionary<string, JsonElement> input)
    {
        try
        {
            using FileStream gate = Lock();
            string result = Text(input, "command") switch
            {
                "view" => View(Text(input, "path"), input.GetValueOrDefault("view_range")),
                "create" => Create(Text(input, "path"), Text(input, "file_text")),
                "str_replace" => Replace(Text(input, "path"), Text(input, "old_str"), OptionalText(input, "new_str")),
                "insert" => Insert(Text(input, "path"), Number(input, "insert_line"), Text(input, "insert_text")),
                "delete" => Delete(Text(input, "path")),
                "rename" => Rename(Text(input, "old_path"), Text(input, "new_path")),
                string other => throw new MemoryException($"Error: unknown command {other}"),
            };
            return (result, false);
        }
        catch (MemoryException ex)
        {
            return (ex.Message, true);
        }
    }

    /// <summary>Todos los archivos de memoria, para el system prompt al empezar una sesión. Vacío si no hay ninguno.</summary>
    public string Snapshot()
    {
        StringBuilder all = new();
        foreach (string file in Files().Order(StringComparer.Ordinal))
            all.Append($"<memory path=\"{ToVirtual(file)}\">\n{File.ReadAllText(file).TrimEnd()}\n</memory>\n");
        return all.ToString();
    }
Enter fullscreen mode Exit fullscreen mode

Los seis comandos devuelven los textos que define la documentación de la herramienta de memoria, porque el modelo los lee (solo falta el fragmento del archivo editado que la documentación agrega tras un str_replace); están en el repositorio. Lo que vale la pena leer es por dónde entran las rutas y por dónde salen los archivos:

/// <summary>
/// Traduce "/memories/a/b.md" a una ruta real dentro de la carpeta, o la rechaza. Salir del directorio
/// se rechaza parte por parte, antes de que el sistema operativo las interprete: "..", nombres ocultos,
/// barras invertidas, letras de unidad y secuencias con % nunca llegan a Path.GetFullPath.
/// </summary>
string Resolve(string path)
{
    if (path != Root && !path.StartsWith(Root + "/", StringComparison.Ordinal))
        throw new MemoryException($"Error: {path} is outside {Root}");

    string relative = path[Root.Length..];
    foreach (string part in relative.Split('/', StringSplitOptions.RemoveEmptyEntries))
    {
        if (part.StartsWith('.') || part.IndexOfAny(['\\', ':', '%', '\0']) >= 0)
            throw new MemoryException($"Error: {path} is not an allowed path");
    }

    string full = Path.GetFullPath(Path.Combine(directory, relative.TrimStart('/')));
    string withSeparator = DevTools.WithSeparator(full);
    if (!withSeparator.StartsWith(directory, PathComparison))
        throw new MemoryException($"Error: {path} is outside {Root}");
    return Directory.Exists(full) ? withSeparator : full;
}

string ExistingFile(string path, string missing)
{
    string full = Resolve(path);
    if (!File.Exists(full)) throw new MemoryException(missing);
    return full;
}

/// <summary>Revisa los topes y el filtro de secretos, y luego reemplaza el archivo de forma atómica.</summary>
void Write(string path, string full, string text)
{
    if (LooksLikeSecret().IsMatch(text))
        throw new MemoryException($"Not written: {path} would contain something shaped like a credential. Never store secrets in memory.");
    if (text.Length > MaxFileChars)
        throw new MemoryException($"Not written: {path} would be {text.Length:N0} characters, over the {MaxFileChars:N0} limit. Merge or delete entries that are no longer true, then try again.");

    long others = Files().Where(f => !string.Equals(f, full, PathComparison)).Sum(f => (long)File.ReadAllText(f).Length);
    if (others + text.Length > MaxTotalChars)
        throw new MemoryException($"Not written: memory would total {others + text.Length:N0} characters, over the {MaxTotalChars:N0} limit. Merge or delete entries that are no longer true, then try again.");

    // Escribe al lado del destino y lo reemplaza: un fallo a mitad de escritura deja el archivo viejo, no medio archivo nuevo.
    Directory.CreateDirectory(Path.GetDirectoryName(full)!);
    string temp = Path.Combine(directory, $".tmp-{Guid.NewGuid():N}");
    using (FileStream file = new(temp, FileMode.CreateNew, FileAccess.Write))
    {
        file.Write(Encoding.UTF8.GetBytes(text));
        file.Flush(flushToDisk: true);   // en disco antes de mover, para que un corte de luz no deje un archivo vacío
    }
    File.Move(temp, full, overwrite: true);
}

/// <summary>
/// Dos sesiones sobre el mismo repositorio (una por voz, otra escrita) pueden editar el mismo archivo, y
/// str_replace lee, modifica y escribe. Cada comando mantiene un archivo de bloqueo exclusivo mientras corre,
/// así que ningún comando ve a medias la escritura de otro. No combina las dos sesiones: cada modelo
/// escribe a partir de lo último que leyó, y un create reemplaza lo que la otra haya guardado desde entonces.
/// </summary>
FileStream Lock()
{
    string path = Path.Combine(directory, ".lock");
    for (int attempt = 0; ; attempt++)
    {
        try
        {
            return new FileStream(path, FileMode.OpenOrCreate, FileAccess.ReadWrite, FileShare.None);
        }
        catch (DirectoryNotFoundException) when (attempt < 40)
        {
            // Alguien borró la carpeta a mitad de sesión para que el agente olvide: empieza un almacén
            // vacío en vez de decir que la memoria está ocupada.
            Directory.CreateDirectory(directory);
        }
        catch (IOException) when (attempt < 40)
        {
            Thread.Sleep(50);
        }
        catch (IOException)
        {
            throw new MemoryException("Error: memory is busy in another session; try again");
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

Algunas decisiones que hay ahí:

  • La memoria vive fuera del repositorio, en los datos locales de la aplicación del usuario, una carpeta por ruta de repositorio. Guarda lo que dijiste en voz alta sobre tu proyecto, y eso no debería terminar nunca en un commit.
  • Se rechaza cualquier intento de salir del directorio, parte por parte. .., los nombres ocultos, las barras invertidas, las letras de unidad y las secuencias con % se descartan antes de que Path.GetFullPath las vea, y la ruta resuelta se compara con la raíz de todos modos.
  • Topes que dicen qué hacer. Una escritura que dejaría un archivo por encima de 4.000 caracteres, o el almacén entero por encima de 6.000, se rechaza con un mensaje que le pide al modelo combinar o borrar entradas. La memoria se carga cada mañana, así que su tamaño es un costo que se repite.
  • Escritura atómica y un archivo de bloqueo. Dos sesiones sobre el mismo repositorio, una por voz y otra escrita, pueden hacer str_replace sobre el mismo archivo. El bloqueo hace que cada comando se ejecute entero, pero no combina las sesiones: cada modelo escribe a partir de lo último que leyó, así que un create de una reemplaza lo que la otra haya guardado desde entonces. Si borras la carpeta a mitad de sesión, el siguiente comando empieza con un almacén vacío.
  • Se rechaza el texto con forma de las credenciales habituales, decida lo que decida el modelo: claves y tokens de API, identificadores de claves de acceso de AWS y claves de API de Google, JWT, claves PEM y la contraseña de una cadena de conexión. Es una lista de exclusión, así que atrapa las formas comunes, no cualquier secreto.

Los errores vuelven al modelo como texto, nunca como excepciones, y eso importó más de lo que esperaba. La primera versión lanzaba una excepción con un view_range de [1.5, 10] y tumbaba el proceso entero; lo encontró una revisión antes de publicar, y ahora cualquier entrada mal formada es un resultado de error. Además, siete de los 52 comandos de memoria de estas corridas fueron str_replace con old_path, el campo que usa rename, en lugar de path. Cada uno recibió "Error: missing path" como resultado de la herramienta, y la sesión siguió en vez de caerse.

Cargar la memoria sin pagarla dos veces

Llevar la herramienta de memoria no es gratis. Medí la petición pieza por pieza con el endpoint de conteo de tokens:

La petición contiene Tokens de entrada
El prompt y las cinco herramientas de la Parte 2 1.151
+ la herramienta de memoria 2.589
+ las reglas de memoria 2.905
+ el archivo de memoria del viernes, precargado 3.183

La definición de la herramienta y la instrucción que la API le agrega pesan 1.438 tokens. La memoria en sí pesa 278. Esa instrucción empieza con "IMPORTANT: ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE", y el modelo se la toma al pie de la letra. Con la memoria leída bajo demanda, la primera llamada de 6 de las 7 corridas del lunes fue view /memories y nada más; la segunda leyó el archivo junto con git_status. En un agente de voz, eso es una petición extra, de 1,1 a 2,5 segundos aquí, antes de la primera palabra.

La primera petición de la mañana como una sola barra: un tramo corto rotulado en inglés The Agent's Tools and Prompt, uno mucho más ancho rotulado Memory Tool Definition and Instructions y uno delgado para la memoria, bajo una luna y un sol con el enlace roto entre ellos.

Por eso el agente carga la memoria él mismo al empezar la sesión, en un segundo bloque del system prompt, y lo avisa: "You do not need to view it again." Precargada, ninguna corrida la volvió a leer: 0 de 7. Eso ahorró menos tiempo de lo que parece: en las siete corridas de cada modo, el primer turno tardó en promedio 5,6 segundos con la memoria precargada y 6,1 bajo demanda, y los rangos se solapan, de 3,3 a 8,1 frente a 4,8 a 7,7. Con la segunda versión de las reglas, las dos corridas precargadas que leyeron el código antes de responder tardaron 6,1 y 6,9 segundos. La herramienta se queda, para escribir.

internal VoiceAgent(AnthropicClient client, string repo, MemoryStore? memory, DateOnly today, AgentSetup setup)
{
    this.client = client;
    this.repo = repo;
    this.memory = memory;
    this.setup = setup;
    tools = memory is null ? DevToolDefinitions : [.. DevToolDefinitions, new MemoryTool20250818()];

    // El system prompt se arma una vez y no cambia en toda la sesión. Lo que se escribe en la memoria
    // durante la sesión va al disco y aparece en el prompt de la sesión SIGUIENTE. Cambiar
    // el system prompt a mitad de sesión rompería la caché del prompt, y en Haiku 5.5 además
    // invalida todos los bloques de razonamiento que ya están en el historial.
    string prompt = BasePrompt;
    if (memory is not null) prompt += MemoryRules;
    if (memory is not null && setup.VerifyRule) prompt += VerifyRule;

    string context = "";
    if (memory is not null && setup.PreloadMemory)
    {
        string snapshot = memory.Snapshot();
        context = snapshot.Length == 0
            ? "Your memory directory is empty. This is the first session in this repository."
            : "Your memory, loaded when this session started. You do not need to view it again:\n" + snapshot;
    }
    if (setup.Notes is not null) context = "Notes from your previous session:\n" + setup.Notes;

    system = context.Length == 0
        ? [new() { Text = prompt, CacheControl = new CacheControlEphemeral() }]
        : [new() { Text = prompt }, new() { Text = context, CacheControl = new CacheControlEphemeral() }];

    // La fecha va en el primer mensaje de la sesión, no en el system prompt, para que un
    // historial traído de un día anterior siga siendo un prefijo de la petición siguiente.
    sessionNote = $"[Session started {today.ToString("dddd, MMMM d, yyyy", CultureInfo.InvariantCulture)}.]\n";

    if (setup.History is not null) Messages.AddRange(setup.History);
}
Enter fullscreen mode Exit fullscreen mode

El system prompt se arma una vez y no cambia durante la sesión. Lo que el agente escribe en la memoria a mitad de sesión va al disco y aparece en el prompt de la sesión siguiente, no en el de esta, por dos razones. Cambiar el system prompt a mitad de sesión descarta la caché del prompt, y en Haiku 5.5 además invalida todos los bloques de razonamiento del historial: la misma verificación del 400 de antes, solo que la dispara system en lugar de messages. Tampoco le hace falta la copia nueva, porque lo que acaba de escribir ya está en la conversación.

Dentro de una sesión, la caché cumple. En uno de los lunes con memoria precargada, 29.833 de los 31.798 tokens de entrada se leyeron de caché, a una décima parte del precio de entrada. Entre sesiones no ayuda en nada: una entrada de caché dura cinco minutos por defecto, o una hora si pagas el doble por escribirla, y nadie le habla a su agente de build una hora después de irse el fin de semana. La primera petición de cada mañana vuelve a escribir todo el prompt en la caché, a 1,25 veces el precio de entrada. Medida en frío, una corrida por configuración, esa primera petición tardó de 1,6 a 3,4 segundos, contra 1,1 a 2,3 con la caché caliente por la corrida anterior. Con prompts de este tamaño, casi toda esa diferencia es la variación propia de la API; el historial completo, el prompt más grande, fue el más lento en frío.

Estas son las reglas que recibe el agente junto con su memoria:

const string MemoryRules = """

    You have a memory directory that survives between sessions, one per repository.
    - Save what the tools cannot tell you: which project matters and why, conventions,
      what the developer is in the middle of and plans to do next, decisions and why.
    - Never save what a tool can tell you: whether the build passes, errors and their
      line numbers, test results, the list of changed files. All of it is out of date by
      the next session; run the tool instead.
    - Write file and project paths in full, relative to the repository root.
    - Keep one file, /memories/project.md, under 40 lines. Date what you write about work
      in progress. Update or remove entries that stop being true; do not append duplicates.
    - Save quietly: do not mention memory in your spoken reply unless asked.
    """;

const string VerifyRule = """

    A memory is a note from an earlier session, not a fact about now. Before you act on
    one or repeat it as current, check it with a tool. When a tool contradicts a memory,
    trust the tool, fix the memory, and say in a few words what changed.
    """;
Enter fullscreen mode Exit fullscreen mode

Cuando un recuerdo está mal

La última regla es la que se gana su lugar. Para probarla le di al agente la memoria del otro viernes con estas reglas, y cambié el repositorio debajo de ella de tres maneras. Cada escenario corrió dos veces con la regla y dos sin ella:

  • S1: terminé el renombrado el fin de semana y lo confirmé con un commit. Pregunta: "What's left to finish the rename?"
  • S2: el proyecto Core pasó de src/ClaudeReviewBot.Core a src/ReviewBot.Core. Pregunta: "Build the project I care about."
  • S3: la rama se fusionó en main y se borró. Pregunta: "What was I doing on Friday?"
Escenario Con la regla Sin ella
S1, trabajo terminado 2 de 2 lo comprobaron y dijeron que no faltaba nada 2 de 2 igual
S2, proyecto movido 2 de 2 recompilaron y corrigieron la ruta en la memoria 2 de 2 recompilaron, 1 corrigió la memoria
S3, rama fusionada 2 de 2 revisaron el código y dijeron que el trabajo estaba terminado 0 de 2 revisaron; las dos empezaron por el build rojo del viernes

S1 no necesitó la regla, porque la pregunta misma manda al agente a compilar. S2 falló de forma ruidosa, que es la manera amable de fallar: la ruta guardada no existía, la herramienta de build lo dijo y todas las corridas compilaron la solución entera. S3 es el peligroso, porque no falla nada. Sin la regla, la respuesta hablada fue:

"On Friday you were renaming ChangedFile.Patch to Diff, and the build was red at line 111 of the review orchestrator. The rest is on screen."

Es decir, que el viernes estaba renombrando y que el build estaba rojo en la línea 111, como si siguiera así. Con la regla:

"On Friday you were renaming ChangedFile.Patch to Diff. The work looks finished: the tree is clean on main, one commit ahead, and the line that was failing now uses Diff."

Para ser justos con las corridas sin la regla, las dos notaron algo en pantalla, más abajo. Una escribió: "Git now shows you on main with a clean tree and one commit ahead, so the rename was probably committed, but I haven't confirmed that." Es decir, que el cambio probablemente ya estaba confirmado, aunque no lo había comprobado. Las dos corridas con la regla leyeron la línea 111 antes de responder, y vieron que ya usaba Diff.

S2 muestra la otra cara de dejar que el agente edite su propia memoria. Las dos corridas con la regla corrigieron la ruta, y las dos agregaron de paso una regla nueva, sacada de un solo fallo. Estas son las dos líneas que escribió en una de ellas, tal como las guardó:

- Core project is the one the developer cares about: src/ReviewBot.Core (not ClaudeReviewBot.Core; path verified 2026-11-09). The CLI is only a thin wrapper around it.
- Build the whole solution with no project argument; the per-csproj path I guessed did not exist.
Enter fullscreen mode Exit fullscreen mode

La primera línea es correcta. La segunda no: compilar el proyecto Core funciona sin problema si le pasas su ruta nueva, y la línea siguiente de ese mismo archivo todavía apunta a la vieja. Una memoria que el agente corrige sigue siendo una memoria que el agente escribe.

Dos corridas por celda es una muestra pequeña. Lee la tabla como "la regla cambió el resultado donde nada fallaba", no como una tasa.

Dos paneles: a la izquierda, el agente lee su nota y responde con una X roja sin mirar la rama ya fusionada de abajo; a la derecha, primero revisa la rama con una lupa, corrige la nota con un lápiz y responde con una marca verde.

Dos cosas que se rompieron por el camino

El agente se quedó callado. En 16 de 133 turnos medidos, el modelo llamó a show_on_screen y terminó su turno sin ningún texto, con la herramienta de memoria cargada y sin ella. En pantalla, una respuesta que es solo una lista funciona. Por el altavoz es silencio, y el silencio suena a que el agente se colgó. Una línea en el prompt, "Always end with something to say", no lo evitó: todos esos turnos ya la tenían. Una línea de código en AskAsync asegura que el altavoz nunca se quede mudo:

bool shown = false;
string? reply = await RunTurnAsync(text => { shown = true; screen(text); }, ct);
// Un turno puede terminar en una llamada a herramienta sin ningún texto. Hablado, eso es silencio,
// y el silencio suena a que el agente se colgó. Nunca devuelvas nada vacío.
if (reply?.Length == 0) reply = shown ? "Details are on screen." : "Okay.";
if (reply is not null) return reply;
Enter fullscreen mode Exit fullscreen mode

Es otra vez la lección de la Parte 2: una regla que solo vive en el prompt se cumple hasta la primera vez que no.

La raíz del repositorio tenía dos separadores. En mis primeras corridas del viernes, cada build de un proyecto y cada read_file volvían con "outside the repository". El repositorio está en R:\, una unidad de subst que mantiene la ruta de mi perfil fuera de las capturas. Después de la Parte 2, el repositorio compañero agregó a dotnet_build una verificación de rutas que armaba la raíz como TrimEndingDirectorySeparator(path) + separator. TrimEndingDirectorySeparator no toca una raíz, así que R:\ se volvía R:\\, y ninguna ruta de adentro empezaba así. La corrección, con un test de regresión para la raíz de una unidad:

internal static string RepoRoot(string repo) => WithSeparator(Path.GetFullPath(repo));

/// <summary>
/// Agrega un separador solo si falta. TrimEndingDirectorySeparator no toca una
/// raíz, así que recortar y agregar convertía un repositorio en "R:\" en "R:\\", y
/// toda ruta de adentro se rechazaba por estar fuera del repositorio.
/// </summary>
internal static string WithSeparator(string path) =>
    Path.EndsInDirectorySeparator(path) ? path : path + Path.DirectorySeparatorChar;
Enter fullscreen mode Exit fullscreen mode

La corrección era una línea. Lo interesante fue el efecto secundario: antes de que encontrara el bug, el agente ya había escrito esto en su memoria:

- Repo root is R:\ ; Core lives at src/ClaudeReviewBot.Core. Tools reject per-project paths and the R:\src paths as "outside the repository", so only whole-solution builds work.
Enter fullscreen mode Exit fullscreen mode

Es una nota cuidadosa y exacta sobre un bug, y dejó de ser cierta en cuanto el bug se corrigió. Nadie se lo avisa a la memoria. Es el escenario S2, al que se llegó por accidente, y en S2 el agente volvió a escribir una nota del mismo tipo.

La herramienta que faltaba: read_file

El agente de la Parte 2 podía compilar el código pero no leerlo. Esta es la quinta herramienta:

using System.Text;
using System.Text.RegularExpressions;

// La única herramienta de desarrollo nueva de la Parte 3. La sesión real de la Parte 2 terminó en "I can't read the code
// from here"; esta es la herramienta que faltaba. Solo lee: a diferencia de dotnet_build y dotnet_test,
// que ejecutan el código del propio repositorio, no ejecuta nada.
static partial class DevTools
{
    const int MaxReadLines = 200;
    const int MaxReadChars = 16_000;
    const long MaxReadBytes = 1_000_000;

    // Todo lo que devuelve esta herramienta se envía a la API del modelo. Un agente de build nunca necesita estos.
    // Es una lista de exclusión, así que está incompleta: cualquier otra cosa del repositorio puede llegar a la API.
    static readonly string[] SecretExtensions = [".pfx", ".p12", ".key", ".pem", ".snk", ".env"];
    static readonly string[] SecretNames = ["id_rsa", "id_dsa", "id_ecdsa", "id_ed25519", "secrets.json"];

    /// <summary>
    /// Hasta 200 líneas numeradas, y 16.000 caracteres, de un archivo dentro del repositorio. Los
    /// números le permiten al modelo decir "línea 111", y pedir él mismo el rango siguiente cuando el archivo es más largo.
    /// </summary>
    internal static (string Content, bool IsError) ReadFile(string repo, string path, int? startLine, int? endLine)
    {
        string full, root = RepoRoot(repo);
        try
        {
            full = Path.GetFullPath(Path.Combine(repo, path));
        }
        catch (ArgumentException)
        {
            return ($"\"{path}\" is not a valid path.", true);
        }

        if (!full.StartsWith(root, PathComparison)) return ($"\"{path}\" is outside the repository.", true);

        string relative = Path.GetRelativePath(root, full).Replace('\\', '/');
        // En NTFS, "id_rsa::$DATA" abre id_rsa y ".git::$INDEX_ALLOCATION" abre .git, mientras que
        // todas las comprobaciones de abajo comparan nombres. Ningún archivo que necesite un agente de build lleva dos puntos en la ruta.
        if (relative.Contains(':')) return ($"\"{relative}\" has a colon in it; ask with the plain file name.", true);
        string[] parts = relative.Split('/');
        string name = parts[^1];
        // "GIT~1" es el nombre corto 8.3 que Windows puede darle a ".git"; las verificaciones de nombre de abajo no lo verían.
        if (parts.Any(part => ShortName().IsMatch(part)))
            return ($"\"{relative}\" uses a short (8.3) name; ask with the full name.", true);
        if (parts.Contains(".git", StringComparer.OrdinalIgnoreCase))
            return ($"\"{relative}\" is inside .git.", true);
        if (name.StartsWith(".env", StringComparison.OrdinalIgnoreCase)
            || SecretExtensions.Contains(Path.GetExtension(name), StringComparer.OrdinalIgnoreCase)
            || SecretNames.Contains(name, StringComparer.OrdinalIgnoreCase))
            return ($"\"{relative}\" may hold secrets and is not read.", true);

        // Un enlace en cualquier punto del camino, sea un symlink de carpeta, una junction o el propio archivo,
        // puede apuntar fuera del repositorio; las verificaciones de arriba solo vieron nombres.
        string current = root;
        foreach (string part in parts)
        {
            current = Path.Combine(current, part);
            FileSystemInfo entry = Directory.Exists(current) ? new DirectoryInfo(current) : new FileInfo(current);
            if (entry.LinkTarget is not null) return ($"\"{relative}\" goes through a link, which is not followed.", true);
        }

        FileInfo file = new(full);
        if (!file.Exists) return ($"\"{relative}\" does not exist.", true);
        if (file.Length > MaxReadBytes) return ($"\"{relative}\" is {file.Length:N0} bytes, too large to read.", true);

        string text = File.ReadAllText(full);
        if (text.Contains('\0')) return ($"\"{relative}\" is a binary file.", true);

        string[] lines = text.Replace("\r\n", "\n").TrimEnd('\n').Split('\n');
        int from = Math.Max(1, startLine ?? 1);
        if (from > lines.Length) return ($"\"{relative}\" has {lines.Length} lines.", true);
        int to = Math.Clamp(endLine ?? int.MaxValue, from, Math.Min(lines.Length, from + MaxReadLines - 1));

        // Un archivo minificado puede tener todo su tamaño en una sola línea, y lo que esto devuelve se queda en
        // un historial que solo puede crecer por el final. Por eso una lectura también se detiene en un límite de caracteres.
        StringBuilder body = new();
        int last = from - 1;
        for (int i = from; i <= to; i++)
        {
            string line = lines[i - 1];
            if (body.Length + line.Length > MaxReadChars)
            {
                if (i == from)
                {
                    body.Append($"{i,5}  {line[..MaxReadChars]} [line cut at {MaxReadChars} characters]\n");
                    last = i;
                }
                break;
            }
            body.Append($"{i,5}  {line}\n");
            last = i;
        }
        return ($"{relative}, lines {from}-{last} of {lines.Length}\n{body}", false);
    }

    [GeneratedRegex(@"~\d")]
    private static partial Regex ShortName();
}
Enter fullscreen mode Exit fullscreen mode

Es de solo lectura y no sale del repositorio. Rechaza .git, los archivos .env y *.env, los archivos de claves y los nombres habituales de claves privadas, cualquier ruta que pase por un enlace o por un nombre corto de Windows como GIT~1, cualquier ruta con dos puntos (en NTFS, id_rsa::$DATA abre id_rsa), los binarios y los archivos de más de 1 MB. Devuelve como mucho 200 líneas numeradas y 16.000 caracteres, para que el modelo pueda decir "línea 111" y pedir el rango siguiente él mismo, y para que un archivo minificado no llene un historial que solo crece. Todo lo que devuelve se envía a la API del modelo, y por eso están esas exclusiones: un agente de voz entiende "lee la configuración" con mucha más facilidad de la que querías. Aun así es una lista de exclusión, y lo que no está en ella puede llegar a la API, así que usa el agente con repositorios que no te importaría pegar en un chat.

El lunes fue la forma en que el agente comprobó su propia nota, cuando lo hizo: 2 de las 4 corridas precargadas abrieron ReviewOrchestrator.cs cerca de la línea 111 antes de repetir lo que decía la memoria, y 1 de las 4 bajo demanda. El único otro cambio está en Program.cs, que abre el almacén al empezar la sesión:

// Una memoria por repositorio, fuera de él, para que nunca termine en un commit. Borra la carpeta
// para que el agente olvide.
MemoryStore memory = MemoryStore.ForRepository(repo);
Console.WriteLine(memory.Snapshot().Length == 0 ? "No memory yet for this repository." : "Memory loaded for this repository.");
VoiceAgent agent = new(new AnthropicClient(), repo, memory, DateOnly.FromDateTime(DateTime.Now));
Enter fullscreen mode Exit fullscreen mode

Lo que la Parte 4 necesita de esto

La Parte 4 saca al agente de la laptop para que funcione las 24 horas, y hay tres cosas en este post que dan por hecho una laptop:

  • La memoria es una carpeta local identificada por una ruta. En un servidor tiene que vivir en un almacenamiento que sobreviva al contenedor, identificado por usuario y repositorio.
  • El bloqueo es un archivo. Sirve para dos procesos en la misma máquina, no para dos instancias detrás de un balanceador de carga.
  • La caché dura cinco minutos, o una hora pagando el doble por escribirla. Que el agente esté siempre encendido no la mantiene caliente entre conversaciones separadas por horas: la primera petición de cada una se sigue pagando completa.

Cuándo no darle memoria a tu agente

  • Cuando un recuerdo equivocado cuesta más que una pregunta. Un agente que pregunta "¿qué proyecto?" cada mañana molesta. Uno que compila con seguridad el proyecto equivocado es peor, y la memoria es la forma de conseguir el segundo.
  • Cuando el historial alcanza. Para un solo día largo, conservar la conversación entera fue la forma más precisa que medí, y la más simple. La memoria se justifica de un día para otro.
  • En máquinas compartidas o que no controlas. La memoria es lo que dijiste sobre tu trabajo, en texto plano, fuera del repositorio y de cualquier limpieza que hagas después.
  • Cuando no hay nada que valga la pena guardar. Si cada pregunta se responde ejecutando una herramienta, la memoria solo agrega una segunda respuesta, más vieja.

Puntos clave

  • Memoria es elegir qué guardar, no guardarlo todo. El historial completo respondió mejor el primer día y crece sin límite; una ventana olvida por antigüedad, y lo primero que se perdió fueron los datos más viejos.
  • En Haiku 5.5, un historial solo puede crecer por el final. Recortarlo desde el inicio con bloques de razonamiento adentro da un 400 en las cuentas creadas desde el 31 de agosto de 2026, y en las anteriores que piden la verificación.
  • No se puede sacar el estado de la memoria con el prompt, así que verifícalo al leerla. Cuatro de cuatro memorias guardaron el error del build contra reglas explícitas. Con una regla de "verifica antes de creerle", el agente revisó el código y detectó una rama ya fusionada dos de dos veces; sin ella, las dos corridas empezaron por el build rojo del viernes. La regla no es una garantía: cerca de la mitad de los lunes repitieron una nota sin comprobarla.
  • Precarga la memoria en vez de dejar que el modelo la pida. La propia instrucción de la herramienta costó una petición extra antes de la primera respuesta en 6 de 7 corridas; cargada en un system prompt que no cambia durante la sesión, ninguna. El primer turno solo fue medio segundo más rápido en promedio, y parte del tiempo ahorrado se fue en comprobar la nota.
  • La herramienta de memoria cuesta más describirla que llenarla. Sumó 1.438 tokens de definición e instrucción alrededor de una memoria de 278, pagados de nuevo cada mañana, porque la caché no sobrevive a la noche.

El código completo está en GitHub, listo para clonar y ejecutar: Juxn89/dotnet-voice-dev-agent. Los cambios de la Parte 3 están en su CHANGELOG.md, junto con la corrección de la raíz de unidad. El README está en inglés.


Siguiente en la serie: Construye un agente de desarrollo .NET, Parte 4: despliégalo en Azure o AWS para que funcione 24/7, para sacar al agente y su memoria de la laptop, y ver cuánto cuesta un agente siempre encendido cuando la caché igual olvida en menos de una hora.

Top comments (0)