Note-taking estructurado

2.1El problema

Magallanes arranca un encargo de 12 subtemas. Va bien: busca, lee, escribe sección tras sección. Al turno 30, la compaction que montaste en N1 entra en acción —el historial pesaba demasiado— y comprime el pasado en un resumen. El run sigue vivo. Todo correcto.

Y entonces Magallanes reabre el subtema 3. Ese ya lo había cerrado hace veinte turnos. Vuelve a buscar, vuelve a leer, redacta una sección que duplica otra que ya existe. El informe sale con una sección repetida y un agujero en otro subtema que nadie tocó.

¿Qué falló? La compaction comprimió el historial —los mensajes, los tool results— y lo hizo bien: eso era su trabajo. Pero el plan —qué subtemas quedan abiertos, cuáles están cerrados, qué decidiste— no vivía en ningún sitio estable. Vivía implícito en el historial. Cuando el historial se comprime, el plan implícito se va con él.

Un investigador humano no trabaja así. Lleva una libreta. Anota qué tiene hecho, qué le falta, qué decidió y por qué. Cuando vuelve de comer, no relee todas sus notas de la mañana: mira la libreta y retoma. Magallanes puede llevar esa libreta. Esta lección se la da.

2.2Qué vas a poder hacer

Al terminar serás capaz de:

• Implementar note-taking estructurado en Magallanes con sus 2 tools de notas (leer_notas, escribir_notas) y dos instrucciones de system prompt.
• Diseñar la plantilla de la nota —qué campos mantiene y por qué— partiendo de estado, decisiones y pendientes.
• Ajustar la política de escritura (cuándo escribe) y demostrar con una traza que las notas sobreviven a una compaction.
• Criticar una política de note-taking mal diseñada y distinguir una nota estructurada de un diario-vertedero.

Necesitas saber antes:

• De N2·L1 (La memoria es arquitectura): qué tipo CoALA son las notas de un encargo en curso y a qué scope pertenecen. Lo recuperamos en 2.3.
• De N1 (el nivel palancas-y-compaction): qué preservaba tu nodo de compaction y por qué. Esas tres cosas reaparecen como campos de la nota. Repásalo en /cursos/context-engineering/palancas-y-compaction si lo necesitas.
• El esqueleto congelado de Magallanes: el grafo de LangGraph y sus 3 tools (buscar, leer, escribir_seccion).

2.3Recupera

Antes de seguir, responde de memoria. Esto reactiva lo anterior y engancha lo nuevo.

1. De L1: las notas de un encargo en curso, ¿qué tipo CoALA son y a qué scope pertenecen —thread o cross-thread?
2. De L1: escribir esas notas durante el run, ¿es hot path o background? ¿Por qué?
3. De N1: tu nodo de compaction preservaba tres cosas explícitamente al comprimir. ¿Cuáles?

2.4El concepto

Cinco ideas encadenadas. Lee primero los títulos de las cinco subsecciones; te dan el esqueleto. Luego entra en cada una.

Qué es el note-taking estructurado

Aquí está la técnica. El structured note-taking es, en palabras de Anthropic, "a technique where the agent regularly writes notes persisted to memory outside of the context window. These notes get pulled back into the context window at later times". · fuente: corpus C.2.

Desmóntalo en tres movimientos. El agente escribe notas durante el run. Esas notas se persisten fuera de la ventana de contexto —en disco, en una tabla, donde sea, pero no en el historial—. Y más tarde el agente las trae de vuelta al contexto cuando las necesita.

La analogía es la libreta del investigador del problema. Escribe lo que importa, la guarda fuera de su cabeza, la consulta al retomar. Dónde falla la analogía: la libreta humana no se abre sola —el investigador decide cuándo mirarla por costumbre—. En el agente, "cuándo escribir" y "cuándo leer" son política de diseño que tú defines, no costumbre que surge. Esa política es la mitad de esta lección.

El beneficio que reporta Anthropic es preciso: "persistent memory with minimal overhead". La técnica mantiene "critical context and dependencies that would otherwise be lost across dozens of tool calls". · fuente: corpus C.2. Esa última frase es exactamente tu problema de 2.1: el plan que se perdía a través de docenas de tool calls.

La evidencia: tallies a través de miles de pasos

Hay una observación de Anthropic que ancla por qué esto funciona. Un agente jugando Pokémon, usando note-taking, mantiene "precise tallies across thousands of game steps… 'for the last 1,234 steps I've been training my Pokémon in Route 1…'". Desarrolla mapas y notas de estrategia sin instrucciones explícitas de estructura. · fuente: corpus C.2.

Lee el detalle que importa: miles de pasos. Ninguna ventana de contexto aguanta miles de pasos de juego sin comprimir. El agente no tiene acceso a los 1.234 pasos —no caben—; lee el tally que escribió fuera y volvió a leer. La nota es lo que sobrevive a la compresión del historial.

Aviso para no confundir: este Pokémon es el del note-taking de Anthropic. No es el Pokémon de la distracción que viste en N0·L2 —ese venía del Gemini 2.5 report vía Breunig, y trataba de otra cosa—. Mismo juego, dos evidencias distintas.

En producción esta técnica ya está por todas partes: las to-do lists de Claude Code, los archivos NOTES.md. · fuente: corpus C.2.

La versión productizada: el memory tool de la API

Anthropic empaquetó esta idea en una herramienta de su API: el memory tool. Es una tool client-side —Claude emite los tool calls; tu aplicación los ejecuta sobre tu storage—. Tú decides dónde viven las notas. · fuente: corpus C.3.

Su definición es literal: {"type": "memory_20250818", "name": "memory"} en tools. No requiere beta header para activarse. Expone seis comandos —view, create, str_replace, insert, delete, rename— sobre una convención de directorio /memories, con los paths restringidos para evitar path-traversal. · fuente: corpus C.3, F.6.

Lo más instructivo es el system prompt que Anthropic inyecta cuando la tool está activa. Empieza así:

1IMPORTANT: ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE.

Esa línea es la política de lectura hecha instrucción. Antes de trabajar, mira la memoria. Es el patrón "view memory primero" que vas a replicar en Magallanes con tus propias tools.

La pareja clave: memoria y compaction

Aquí está la conexión con N1 que cierra el círculo. El memory tool se combina con la compaction: la memoria persiste lo crítico a través de los límites de la compaction. · fuente: corpus C.3, B.4.

Piénsalo como una división de trabajo. La compaction comprime el historial dentro del hilo —es buena en eso—. La nota guarda lo que no debe comprimirse —el plan, las decisiones— fuera del historial. Cuando la compaction borra el pasado, la nota sigue ahí. Son la misma política de preservación, aplicada en dos sitios distintos.

La estructura mínima de la nota son tres campos, alineados con lo que pedirá el checkpoint C2: estado (qué está hecho, qué en curso), decisiones (qué resolviste y por qué) y pendientes (qué falta). Son las mismas tres que tu compaction de N1 ya preservaba.

Lo que NO es note-taking

Contraejemplo, y es el error más común. Volcar el historial entero a un archivo no es note-taking. Si guardas cada mensaje y cada tool result en un fichero, sin estructura, releerlo cuesta tantos tokens como el historial que pretendías ahorrarte. No has persistido el plan: has hecho una copia del problema.

La diferencia es la estructura. Una nota es un destilado —tres campos cortos que se sobrescriben—. Un volcado es una acumulación —todo, apilado, creciendo—. El primero te deja retomar leyendo cinco líneas; el segundo te obliga a releer el run completo.

2.5Míralo funcionar

Vamos a cablear el note-taking en Magallanes. Tres piezas: las 2 tools de notas del nivel, las dos instrucciones del system prompt, y una traza que demuestra que la nota sobrevive a la compaction.

Antes de leer el código línea a línea, lee los tres bloques de corrido una vez. Lo difícil no es ninguna firma suelta; es ver el ciclo completo. Sigue la forma: escribe nota → llega la compaction → lee nota → no reabre lo cerrado.

Las dos tools de notas

Magallanes ya tiene 3 tools congeladas (buscar, leer, escribir_seccion). El nivel le añade dos, análogas en forma. Sus firmas están congeladas en el diseño del nivel:

1# magallanes_n2.py — las 2 tools de notas del nivel (firmas congeladas)
2# NOTES = la libreta del encargo en curso. Vive fuera de la ventana de contexto.
3
4def leer_notas() -> str:
5    """Devuelve las NOTES del encargo en curso. Cadena vacía si aún no existen."""
6    ...   # tu app lee de SU storage (archivo, fila de tabla, lo que sea)
7
8def escribir_notas(contenido: str) -> str:
9    """Sobrescribe las NOTES con 'contenido'. Estructura esperada: estado, decisiones, pendientes."""
10    ...   # tu app escribe en SU storage; SOBRESCRIBE, no añade

Dos cosas de estas firmas marcan toda la lección:

• leer_notas devuelve cadena vacía si no existen. Eso permite el patrón "lee primero": en el turno 1 devuelve "", señal de arranque desde cero; al retomar, devuelve el plan. Una sola tool cubre los dos casos.
• escribir_notas sobrescribe. No es append. Esta decisión es la que separa una nota de un diario, y la veremos morder en la práctica de 2.6. Sobrescribir mantiene la nota del tamaño del estado; añadir la hace crecer con la historia.

Las dos instrucciones del system prompt

Las tools no se usan solas. La política de cuándo leer y cuándo escribir vive en el system prompt, como dos instrucciones:

1GESTIÓN DE NOTAS (libreta del encargo):
21. Al EMPEZAR, llama a `leer_notas` antes que a ninguna otra tool. Si devuelve
3   contenido, retomas desde ahí: NO repitas búsquedas ni lecturas ya registradas.
42. Al CERRAR cada sección, llama a `escribir_notas` con la nota completa actualizada:
5   - estado: secciones cerradas, sección en curso
6   - decisiones: qué resolviste y por qué (fuentes elegidas, enfoque)
7   - pendientes: subtemas que faltan, en orden
8   SOBRESCRIBE la nota entera. No apiles; reescribe el estado actual.

La instrucción 1 es el "view memory primero" del memory tool de Anthropic, traducido a las tools de Magallanes. La instrucción 2 fija cuándo escribe: al cerrar cada sección, no en cada turno. Esa elección no es cosmética —la justificamos al final de esta sección—.

El cableado en el grafo

Las dos tools se registran junto a las otras tres en el grafo congelado de Magallanes. La superficie de LangGraph es la de siempre (corpus F.1): un StateGraph, las tools en el nodo de tools, compile con el checkpointer:

1# magallanes_n2.py — registro en el grafo (superficie F.1)
2from langgraph.graph import StateGraph, MessagesState, START, END
3from langgraph.checkpoint.memory import InMemorySaver   # thread-scoped; itera en local
4
5TOOLS = [buscar, leer, escribir_seccion, leer_notas, escribir_notas]
6
7builder = StateGraph(MessagesState)
8# ... nodos: el modelo, el nodo de tools (TOOLS), el nodo de compaction de N1 ...
9
10graph = builder.compile(checkpointer=InMemorySaver())
11
12result = graph.invoke(
13    {"messages": [{"role": "user", "content": ENCARGO}]},
14    config={"configurable": {"thread_id": "encargo-007"}},
15)

InMemorySaver basta para iterar en local: las notas se prueban dentro de un mismo proceso. El backend persistente que sobrevive a un kill del proceso llega en L4 —hoy demostramos solo que la nota aguanta la compaction, que ocurre dentro del run vivo—.

La traza: el ciclo completo

Para ver que funciona, instrumentas el run con Langfuse, como en N0. El callback handler se engancha en el invoke (corpus F.7):

1# La traza Langfuse captura cada tool call y la compaction, en orden (F.7)
2from langfuse.langchain import CallbackHandler
3
4handler = CallbackHandler()
5result = graph.invoke(
6    {"messages": [{"role": "user", "content": ENCARGO}]},
7    config={
8        "configurable": {"thread_id": "encargo-007"},
9        "callbacks": [handler],
10    },
11)

Ahora lee la traza del ciclo. Esto es lo que importa —el flujo, no las cifras concretas, que serán las de tu run—:

1turno 28  escribir_seccion("Subtema 3", ...)   → sección 3 cerrada
2turno 29  escribir_notas("estado: cerradas 1,2,3; en curso 4
3                          decisiones: subtema 3 usa doc-014 (fiable)
4                          pendientes: 5,6,7,8,9,10,11,12")
5turno 30  [COMPACTION]  historial 31K → resumen   ← el pasado se comprime
6turno 31  leer_notas()  → devuelve la nota del turno 29, intacta
7turno 32  modelo: "subtema 3 ya cerrado; sigo por el 4"   ← NO lo reabre

Lee el momento clave: el turno 30 comprime el historial, pero el turno 31 recupera la nota completa. El plan no estaba en el historial que se comprimió; estaba en la nota, fuera. Por eso el turno 32 sigue por el subtema 4 en vez de reabrir el 3. El problema de 2.1, resuelto.

Self-explanation

Antes de leer la respuesta, intenta tú: ¿por qué la instrucción de escribir va ligada a "cerrar sección" y no a "cada turno"?

2.6Hazlo tú

Andamiaje decreciente: diseñas la plantilla, ajustas la política con una traza, y al final amplías la nota sin guía.

Ejercicio 1 — la plantilla de la nota (con guía)

Tienes escribir_notas ya cableada. Diseña la plantilla que el agente rellenará. Parte de los tres campos —estado, decisiones, pendientes— y adáptala al encargo de 12 subtemas de Magallanes.

Decide, para cada campo: qué entra, qué NO entra, y en qué formato. Pista: el formato importa porque el agente lo va a releer; una lista de subtemas con su estado se relee más rápido que un párrafo en prosa.

No hay solución única. El criterio es: ¿podrías retomar el encargo leyendo solo esta plantilla rellena, sin tocar el historial?

Ejercicio 2 — ajusta la política y demuéstralo (con menos guía)

Tu política actual escribe "al cerrar cada sección". Cámbiala y demuéstralo con una traza:

1. Lanza un run con la política actual. Fuerza una compaction (baja el umbral, como en N1). Confirma en la traza Langfuse que leer_notas tras la compaction devuelve el plan intacto.
2. Ahora prueba la política "escribir solo al final del encargo". Provoca la misma compaction antes del final. Mira la traza: ¿qué devuelve leer_notas después?

Elaborative interrogation — antes de correrlo, predice: ¿qué política deja a Magallanes sin nota tras la compaction, y por qué?

Ejercicio 3 — fuentes descartadas (sin andamiaje)

Magallanes re-lee documentos que ya descartó. Evalúa doc-031, decide que no sirve, y tres turnos después —tras una compaction— vuelve a llamar leer(doc-031) porque olvidó que ya lo había mirado.

Sin guía:

1. Añade a tu plantilla de nota un registro de fuentes descartadas con su veredicto en una línea (p. ej. doc-031: descartado — no cubre la ruta).
2. Ajusta la instrucción del system prompt para que Magallanes consulte ese registro antes de llamar leer.
3. Verifica en la traza que, tras una compaction, Magallanes no vuelve a leer un documento ya descartado.

Normaliza el error. La primera versión de casi todas las notas degenera en diario: "busqué X, luego leí Y, luego escribí Z". El síntoma es claro —la nota crece linealmente con los turnos, igual que el historial que querías evitar—. La corrección no es escribir menos: es sobrescribir el estado, no apilar la historia. Un diario responde "qué hice"; una nota responde "dónde estoy". Solo la segunda te deja retomar leyendo cinco líneas.

2.7Comprueba

Sin pistas. Gate de maestría: distinguir una nota que sobrevive de una que no, y criticar una política.

Un compañero corrió el mismo encargo dos veces y guardó las NOTES de cada run. Las dos pasaron por una compaction agresiva en el turno 30. Aquí están, en el turno 31, justo después de la compaction:

1# NOTES — run A
2estado: cerradas [1,2,3,4]; en curso [5]
3decisiones: subtema 2 → doc-014 (fiable); subtema 4 → descartado doc-031 (no cubre ruta)
4pendientes: [6,7,8,9,10,11,12]
5fuentes descartadas: doc-031, doc-052

1# NOTES — run B
2turno 1: leí el encargo, 12 subtemas
3turno 2: busqué "ruta de Magallanes", 8 resultados
4turno 3: leí doc-002, interesante
5turno 4: escribí intro
6turno 5: busqué "tripulación"
7...
8turno 27: escribí subtema 4

1. Predice cuál de las dos NOTES permite a Magallanes retomar sin re-trabajo tras la compaction.
2. Señala las 2 diferencias concretas que lo explican.
3. Critica en 3 frases esta política de escritura propuesta: "escribir_notas en cada turno, añadiendo una línea con lo que pasó, sin estructura fija."

2.8Conecta

Acabas de dar a Magallanes su libreta. Las notas viven en el encargo —en el thread—. Mientras el run esté vivo, sobreviven a la compaction. Eso es la dimensión 1 del checkpoint C2: "retoma desde sus notas sin releer todo el historial; las notas tienen estructura". Hoy la implementaste.

Pero la libreta tiene un límite. Lo que Magallanes registra en este encargo —que doc-014 es fiable, que doc-031 no cubre la ruta— muere cuando el thread termina. Llega un encargo nuevo sobre un tema vecino y Magallanes vuelve a evaluar las mismas fuentes desde cero. Las notas son del encargo; lo aprendido entre encargos pide otra pieza.

Esa pieza es el otro scope que viste en L1: cross-thread. El Store de LangGraph. Es lo que montas en L3: dónde guardas lo que merece sobrevivir a un thread —fuentes fiables por tema, preferencias de formato— y con qué política decides qué entra y qué no.

Y queda una pregunta que esta lección dejó abierta a propósito. La nota de hoy sobrevive a la compaction porque vive en memoria, dentro del proceso. ¿Qué pasa cuando el proceso entero muere —un deploy, un OOM-kill— a mitad de encargo? Esa es la avería del nivel, y la enfrentas en L4. La libreta es el primer paso; la supervivencia completa necesita las tres piezas juntas.

Cierra el arco de 2.1: tenías un agente que reabría subtemas cerrados porque su plan vivía implícito en un historial que la compaction comprimía. Ahora el plan vive fuera, en tres campos que se sobrescriben, y Magallanes lo lee al retomar. El subtema 3 se queda cerrado.

2.9Reflexiona

Tómate un minuto. Responder esto por escrito consolida lo aprendido mejor que releer.

• ¿Qué aprendiste? Resume en una frase por qué sobrescribir el estado —y no apilar la historia— es lo que hace que una nota sirva para retomar.
• ¿Qué sigue sin estar claro? ¿Tienes clara la diferencia entre lo que comprime la compaction (el historial) y lo que guarda la nota (el plan)? Si no, vuelve a 2.4, a la pareja memoria-compaction.
• ¿Qué harías distinto? La próxima vez que un agente tuyo repita trabajo en un run largo, ¿qué tres campos pondrías en su nota antes de tocar nada más?

Esto requiere práctica. La intuición de "qué merece estar en la nota y qué es ruido" llega ajustando notas sobre runs reales, no leyendo. En L3 esa misma decisión —qué guardar, qué no— escala al Store, y la lista de "qué NO guardar" se vuelve una política con su propia cara oscura.